AI 助理
备案控制台
文档
输入文档关键字查找
首页 云服务器 ECS 开发参考 API参考（ECS） API目录 镜像 CreateImage - 创建一份自定义镜像

CreateImage - 创建一份自定义镜像

更新时间：
产品详情
相关技术圈
我的收藏

调用CreateImage接口，创建一份自定义镜像。后续您可以使用创建的自定义镜像创建ECS实例（RunInstances），或者更换实例的系统盘（ReplaceSystemDisk）。

接口说明

调用该接口时，您需要注意：

  • 等待镜像状态变为可用（Available）后才能使用镜像资源。
  • 查询 ECS 实例信息时，如果返回数据中包含{"OperationLocks": {"LockReason" : "security"}}，则禁止一切操作。
  • 强烈建议在创建镜像时配置镜像检测参数，有助于系统帮助优化您的镜像。更多信息，请参见镜像检测概述。

以下描述了三种通过该接口创建自定义镜像的方法。请求参数的优先级为：InstanceId > DiskDeviceMapping > SnapshotId，若您的请求中同时含有两个及以上参数，默认以优先级更高的参数为准创建镜像。

  • 方法一：使用一台实例做模板，只需要指定实例 ID（InstanceId）。该台实例的状态必须为运行中（Running）或者已停止（Stopped）。接口调用成功后，该台实例的每块云盘均会新增一份快照。由于运行中的实例存在缓存数据未落盘的情况，可能导致创建的自定义镜像数据与实例数据不完全一致。因此阿里云推荐您停止实例（ StopInstances ）后创建镜像。
  • 方法二：针对某一台实例的系统盘创建自定义镜像，只需要指定实例系统盘的一份历史快照 ID（SnapshotId）。其中，指定的快照不能是 2013 年 7 月 15 日（含）之前创建的快照。
  • 方法三：将多份快照组合成一个镜像模板，需要建立几块云盘的数据关联（DiskDeviceMapping）。

使用方法三创建自定义镜像时，请注意：

  • 只能指定一个系统盘快照，系统盘的设备名必须为/dev/xvda。
  • 可以指定多个数据盘快照，最多不能超过 16 块，数据盘设备名默认由系统有序分配，从/dev/xvdb 依次排序到/dev/xvdz，不能重复。
  • 可以不指定SnapshotId，不指定时会创建一个指定大小的没有任何数据的空数据盘。
  • 指定的快照不能是 2013 年 7 月 15 日（含）之前创建的快照。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

  • 操作：是指具体的权限点。
  • 访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
  • 资源类型：是指操作中支持授权的资源类型。具体说明如下：
    • 对于必选的资源类型，用背景高亮的方式表示。
    • 对于不支持资源级授权的操作，用全部资源表示。
  • 条件关键字：是指云产品自身定义的条件关键字。
  • 关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。
操作访问级别资源类型条件关键字关联操作
ecs:CreateImagecreate
*Image
acs:ecs:{#regionId}:{#accountId}:image/*
*Instance
acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}
*Snapshot
acs:ecs:{#regionId}:{#accountId}:snapshot/{#snapshotId}
    无
无

请求参数

名称类型必填描述示例值
RegionIdstring是

镜像所在的地域 ID。您可以调用 DescribeRegions 查看最新的阿里云地域列表。

cn-hangzhou
SnapshotIdstring否

用于创建自定义镜像的快照 ID。

s-bp17441ohwkdca0****
InstanceIdstring否

实例 ID。

i-bp1g6zv0ce8oghu7****
ImageNamestring否

镜像名称。长度为 2~128 个英文或中文字符。必须以大小写字母或中文开头，不能以 http://和 https://开头。可以包含数字、半角冒号（:）、下划线（_）或者短划线（-）。

TestCentOS
ImageFamilystring否

镜像族系名称。长度为 2~128 个英文或中文字符。必须以大小写字母或中文开头，不能以 aliyun 和 acs:开头，不能包含 http://或者 https://。可以包含数字、半角冒号（:）、下划线（_）或者短划线（-）。

hangzhou-daily-update
ImageVersionstring否

镜像版本。

说明 当您指定了实例 ID（InstanceId），并且该实例的镜像是云市场镜像或者来自云市场镜像创建的自定义镜像时。该参数必须和当前实例的镜像的 ImageVersion 相同或置为空。
2017011017
Descriptionstring否

镜像的描述信息。长度为 2~256 个英文或中文字符，不能以 http://或 https://开头。

ImageTestDescription
Platformstring否

指定数据盘快照做镜像的系统盘后，需要通过 Platform 确定系统盘的操作系统发行版。取值范围：

  • Aliyun
  • Anolis
  • CentOS
  • Ubuntu
  • CoreOS
  • SUSE
  • Debian
  • OpenSUSE
  • FreeBSD
  • RedHat
  • Kylin
  • UOS
  • Fedora
  • Fedora CoreOS
  • CentOS Stream
  • AlmaLinux
  • Rocky Linux
  • Gentoo
  • Customized Linux
  • Others Linux
  • Windows Server 2022
  • Windows Server 2019
  • Windows Server 2016
  • Windows Server 2012
  • Windows Server 2008
  • Windows Server 2003

默认值：Others Linux。

CentOS
BootModestring否

修改镜像的启动模式。取值范围：

  • BIOS：BIOS 启动模式。
  • UEFI：UEFI 启动模式。
  • UEFI-Preferred：双启动模式。
注意 为了避免使用镜像不支持的启动模式导致实例无法正常启动，请您务必在选择该参数之前了解目标镜像支持的启动模式。镜像启动模式详情，请参见镜像启动模式。
BIOS
Architecturestring否

指定数据盘快照做镜像的系统盘后，需要通过 Architecture 确定系统盘的系统架构。取值范围：

  • i386。
  • x86_64。
  • arm64。

默认值为 x86_64。

x86_64
ClientTokenstring否

保证请求幂等性。从您的客户端生成一个参数值，确保不同请求间该参数值唯一。ClientToken 只支持 ASCII 字符，且不能超过 64 个字符。更多信息，请参见如何保证幂等性。

123e4567-e89b-12d3-a456-426655440000
ResourceGroupIdstring否

自定义镜像所在的资源组 ID。如果不设置该参数值，创建的镜像属于默认资源组。

说明 如果您当前使用的是 RAM 用户调用该接口，且ResourceGroupId取值为空，您需要注意，当 RAM 用户没有默认资源组权限时，调用接口会返回报错信息Forbidden: User not authorized to operate on the specified resource。请您设置 RAM 用户支持的资源组 ID 或者通过相应阿里云账号为该 RAM 用户授予默认资源组权限后，再次调用该接口。
rg-bp67acfmxazb4p****
DiskDeviceMappingarray<object>否

创建的自定义镜像信息列表。

object否

创建的自定义镜像信息列表。

SnapshotIdstring否

根据指定的快照创建自定义镜像。

s-bp17441ohwkdca0****
Sizeinteger否

云盘的大小，单位为 GiB。DiskDeviceMapping.N.Size 的取值和默认值和 DiskDeviceMapping.N.SnapshotId 有关：

  • 如果没有指定 SnapshotId，Size 取值以及默认值为：
    • 普通云盘：5~2000GiB，默认为 5。
    • 其他云盘：20~32768GiB，默认为 20。
  • 如果指定了 SnapshotId，Size 取值必须大于等于 SnapshotId 的大小，默认为 SnapshotId 的大小。
2000
Devicestring否

指定在自定义镜像中的设备名称。取值范围：

  • 其他云盘（例如 SSD 云盘、高效云盘和 ESSD 云盘）：/dev/vda~/dev/vdz。
  • 普通云盘：/dev/xvda~/dev/xvdz。
/dev/vdb
DiskTypestring否

指定在新镜像中的云盘类型。您可以通过该参数使用数据盘快照做为镜像的系统盘，如果不指定，默认为快照对应的云盘类型。取值范围：

  • system：系统盘。只能指定 1 块系统盘快照。
  • data：数据盘。最多可以指定 16 块数据盘快照。
system
Tagarray<object>否

标签列表。

object否

标签列表。

keystring否

镜像的标签键。

说明 为提高兼容性，建议您尽量使用 Tag.N.Key 参数。
null
Keystring否

镜像的标签键。N 的取值范围为 1~20。一旦传入该值，则不允许为空字符串。最多支持 128 个字符，不能以aliyun或acs:开头，不能包含http://或者https://。

KeyTest
Valuestring否

镜像的标签值。N 的取值范围为 1~20。一旦传入该值，允许为空字符串。最多支持 128 个字符，不能以acs:开头，不能包含http://或者https://。

ValueTest
valuestring否

镜像的标签值。

说明 为提高兼容性，建议您尽量使用 Tag.N.Value 参数。
null
DetectionStrategystring否

镜像检测策略，不配置此参数时不触发检测。仅支持标准（Standard）检测模式。

说明 目前已支持大部分的 Linux/Windows 版本，关于镜像检测项与操作系统限制说明，请参见镜像检测概述和镜像检测操作系统限制。
Standard

返回参数

名称类型描述示例值
object
ImageIdstring

镜像 ID。

m-bp146shijn7hujku****
RequestIdstring

请求 ID。

C8B26B44-0189-443E-9816-*******

示例

正常返回示例

JSON格式

{
  "ImageId": "m-bp146shijn7hujku****",
  "RequestId": "C8B26B44-0189-443E-9816-*******"
}

错误码

HTTP status code错误码错误信息描述
400InvalidImageName.MalformedThe specified Image name is wrongly formed.镜像名称格式错误。长度为2~128个字符。必须以大小字母或中文开头，不能以aliyun和acs:开头，不能包含http://或者https://。可以包含数字、半角句号（.）、半角冒号（:）、下划线（_）或者短划线（-）。
400InvalidImageName.DuplicatedThe specified Image name has already bean used.镜像名称已经重复。
400InvalidDescription.MalformedThe specified description is wrongly formed.指定的资源描述格式不合法。长度为 2-256 个字符，不能以 http:// 和 https:// 开头。
400InvalidImageVersion.MalformedThe specified ImageVersion is wrongly formed.无效的镜像版本号取值（或者您无权使用该快照）。
400IncorrectInstanceStatusThe current status of the instance does not support this operation.当前实例状态不支持此操作。
400InstanceLockedForSecurityThe specified operation is denied as your instance is locked for security reasons.实例被安全锁定。
400InvalidDevice.MalformedThe specified parameter DiskDeviceMapping.n.Device is not valid.指定的参数 DiskDeviceMapping.n.Device 不合法。
400MissingParameterThe input parameter SnapshotId or InstanceId or DiskDeviceMapping that is mandatory for processing this request is not supplied.参数 SnapshotId，InstanceId 和 DiskDeviceMapping 不得为空。
400InvalidSize.ValueNotSupportedThe specified parameter DiskDeviceMapping.n.Size beyond the permitted range.指定的参数 DiskDeviceMapping.n.Size 超出取值范围。
400InvalidDevice.InUseThe specified parameter DiskDeviceMapping.n.Device has been occupied.指定的参数 DiskDeviceMapping.n.Device 已被占用。
400OperationDeniedThe specified parameter DiskDeviceMapping.n.SnapshotId does not contain system disk snapshot.系统盘快照中不存在指定的 DiskDeviceMapping 快照 ID。
400OperationDeniedThe specified parameter DiskDeviceMapping.n.SnapshotId contains two or more system disk snapshots.指定的 DiskDeviceMapping 快照 ID 中已存在系统盘快照。
400InvalidDiskCategory.CreateImageThe specified diskCategory is not allowed to create image.指定的磁盘类型不允许创建镜像。
400InvalidArchitecture.MalformedThe specified Architecture is wrongly formed.参数 Architecture 格式错误。
400InvalidPlatform.MalformedThe specified Platform is wrongly formed.指定的镜像操作系统发行版不合法。
400OperationDeniedNot support creating system image from an encrypted snapshot/disk.被加密的磁盘和快照不允许创建系统镜像。
400InvalidParameter.AllEmpty%s您没有输入任何参数，请输入必要的参数。
400InvalidParameter.DiskTypeThe specified disk type which has kms key can't convert to system disk.-
400Duplicate.TagKeyThe Tag.N.Key contain duplicate key.标签中存在重复的键，请保持键的唯一性。
400InvalidTagKey.MalformedThe specified Tag.n.Key is not valid.指定的标签键参数有误。
400InvalidTagValue.MalformedThe specified Tag.n.Value is not valid.指定的标签值参数有误。
400InvalidInstance.NotFoundSystemDiskThe specified instance does not have system disk.-
400InvalidImageFamily.MalformedThe format of the specified image family is invalid.指定的镜像族系格式有误。
400ImageQuotaExceed.ImageFamilyThe specified image family exceeds the maximum number of images for one image family.-
400ImageFamilyQuotaExceedThe number of image families exceeds the limit in the region.-
400InvalidDiskType.ValueNotSupportedThe specified disk type is not supported.指定的磁盘属性不支持。
400IdempotenceParamNotMatchRequest uses a client token in a previous request but is not identical to that request.与相同 ClientToken 的请求参数不符合。
400OperationDeniedShared snapshots do not support creating images.共享快照不支持创建自定义镜像。
400InvalidBootMode.NotSupportThe specified parameter BootMode is not supported for current image architecture.当前的镜像架构不支持设置该启动模式。
403IncorrectDiskStatus.NeverAttachedThe specified disk has never been attached to instance.-
403InvalidSnapshotId.NotReadyThe current status of the DiskDeviceMapping.n.SnapshotId or SnapshotId does not support this operation.当前磁盘有创建中的快照，请稍后重试
403InvalidSnapshot.TooOldThis operation is denied because the specified snapshot by DiskDeviceMapping.n.SnapshotId or SnapshotId is created before 2013-07-15.该操作被拒绝。因为 DiskDeviceMapping.n.SnapshotId 或 SnapshotId 指定的快照创建于 2013-07-15 之前。
403OperationDeniedThe specified snapshot is not allowed to create image.指定快照不允许创建镜像。
403QuotaExceed.ImageThe Image Quota exceeds.自定义镜像额度已用完。
403OperationDeniedThe specified snapshot is not from system disk.指定的快照不是系统盘快照。
403InvalidParamter.ConflictThe specified same token is trying to make requests with different parameters.同一个 Token 正在请求处理两个不同的参数。
403InvalidAccountStatus.NotEnoughBalanceYour account does not have enough balance.账号余额不足，请您先充值再进行该操作。
403InvalidAccountStatus.SnapshotServiceUnavailableSnapshot service has not been opened yet.快照服务未开通，操作无法执行。
403UserNotInTheWhiteListThe user is not in the white list of create image by data disk snapshot.您不能通过数据磁盘快照创建镜像，请先加入到该白名单中。
403IncorrectDiskStatus.InvalidDevice status is invalid, please restart instance and try again.设备状态无效，请重启实例后再试。
403OperationDenied.InvalidSnapshotCategory%s该快照类型不支持此操作。
403QuotaExceed.SnapshotThe snapshot quota exceeds.快照额度超过限制，若要存储新快照，在不影响业务的情况下，请您删除已有的老快照。
403IncorrectDiskStatus.TransferringThe specified device is transferring, you can retry after the process is finished.指定磁盘正在迁移中，请在迁移完毕后重试。
403IncorrectDiskStatusThe current disk status does not support this operation.当前的磁盘不支持此操作，请您确认磁盘处于正常使用状态，是否欠费。
403InvalidSystemSnapshot.Missing%s-
403IncorrectDiskStatus.CreatingSnapshotA previous snapshot creation is in process.当前磁盘有创建中的快照，请您等待创建完成再试。
403InvalidParameter.KMSKeyId.CMKUnauthorizedThe CMK needs to be added ECS tag.CMK 未授权
403InvalidParameter.KMSKeyId.CMKNotEnabledThe CMK needs to be enabled.加密云盘设置了 KMSKeyId 后，CMK必须处于启用状态。您可以调用密钥管理服务的 DescribeKey 接口查询指定CMK的相关信息。
403InvalidParameter.KMSKeyId.KMSUnauthorizedECS service have no right to access your KMS.ECS 服务无权访问您的 KMS。
403QuotaExceed.Tags%s标签数超过可以配置的最大数量。%s为变量，将根据调用API的实际情况动态返回错误信息。
403InvalidSnapshotCategory.NotSupportImageCreationThe specified snapshot category does not support create image.-
403TooManySnapshot.UnfinishedThere are too many snapshots being created, please wait for them to be created done.-
403HibernationConfigured.InstanceOperationForbiddenThe operation is not permitted due to limit of the hibernation configured instance.不符合开启休眠选项的实例的相关限制，操作不被允许。
403SnapshotNotReadyThe specified snapshot is not ready.快照未完成创建，无法用来创建镜像。
403IncorrectInstanceStatus.NeedRestartThe instance needs to be restarted after adding a disk in a shutdown status.在关机状态下添加云盘后需要重启实例后才能创建自定义镜像。
403QuotaExceed.ConcurrentSnapshotQuotaThe number of snapshots being created for the disk %s has exceeded the concurrent quota (%s). Please wait for the previous snapshots to complete before trying again.该磁盘正在创建的快照数量已超过并发配额，请等待之前的快照完成后再重试。
404InvalidSnapshotId.NotFoundThe specified SnapshotId does not exist.指定的快照不存在，请您检查快照是否正确。
404InvalidInstanceId.NotFoundThe specified InstanceId does not exist.指定的实例ID未找到。
404InvalidResourceGroup.NotFoundThe ResourceGroup provided does not exist in our records.资源组并不在记录中。
500InternalErrorThe process of creating snapshot has failed due to some unknown error.创建快照失败。
500InternalErrorThe request processing has failed due to some unknown error, exception or failure.内部错误，请重试。

访问错误中心查看更多错误码。

变更历史

变更时间变更内容概要操作
2024-10-22OpenAPI 错误码发生变更查看变更详情
2024-06-12OpenAPI 错误码发生变更查看变更详情
2024-05-09OpenAPI 错误码发生变更查看变更详情
2021-06-17OpenAPI 错误码发生变更查看变更详情
上一篇：镜像下一篇：ImportImage - 导入本地镜像文件
文档推荐