调用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:CreateImage | create | *Image acs:ecs:{#regionId}:{#accountId}:image/**Instance acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}*Snapshot acs:ecs:{#regionId}:{#accountId}:snapshot/{#snapshotId} |
| 无 |
请求参数
| 名称 | 类型 | 必填 | 描述 | 示例值 |
|---|---|---|---|---|
| RegionId | string | 是 | 镜像所在的地域 ID。您可以调用 DescribeRegions 查看最新的阿里云地域列表。 | cn-hangzhou |
| SnapshotId | string | 否 | 用于创建自定义镜像的快照 ID。 | s-bp17441ohwkdca0**** |
| InstanceId | string | 否 | 实例 ID。 | i-bp1g6zv0ce8oghu7**** |
| ImageName | string | 否 | 镜像名称。长度为 2~128 个英文或中文字符。必须以大小写字母或中文开头，不能以 http://和 https://开头。可以包含数字、半角冒号（:）、下划线（_）或者短划线（-）。 | TestCentOS |
| ImageFamily | string | 否 | 镜像族系名称。长度为 2~128 个英文或中文字符。必须以大小写字母或中文开头，不能以 aliyun 和 acs:开头，不能包含 http://或者 https://。可以包含数字、半角冒号（:）、下划线（_）或者短划线（-）。 | hangzhou-daily-update |
| ImageVersion | string | 否 | 镜像版本。 说明
当您指定了实例 ID（ InstanceId），并且该实例的镜像是云市场镜像或者来自云市场镜像创建的自定义镜像时。该参数必须和当前实例的镜像的 ImageVersion 相同或置为空。
| 2017011017 |
| Description | string | 否 | 镜像的描述信息。长度为 2~256 个英文或中文字符，不能以 http://或 https://开头。 | ImageTestDescription |
| Platform | string | 否 | 指定数据盘快照做镜像的系统盘后，需要通过 Platform 确定系统盘的操作系统发行版。取值范围：
默认值：Others Linux。 | CentOS |
| BootMode | string | 否 | 修改镜像的启动模式。取值范围：
注意
为了避免使用镜像不支持的启动模式导致实例无法正常启动，请您务必在选择该参数之前了解目标镜像支持的启动模式。镜像启动模式详情，请参见镜像启动模式。
| BIOS |
| Architecture | string | 否 | 指定数据盘快照做镜像的系统盘后，需要通过 Architecture 确定系统盘的系统架构。取值范围：
默认值为 x86_64。 | x86_64 |
| ClientToken | string | 否 | 保证请求幂等性。从您的客户端生成一个参数值，确保不同请求间该参数值唯一。ClientToken 只支持 ASCII 字符，且不能超过 64 个字符。更多信息，请参见如何保证幂等性。 | 123e4567-e89b-12d3-a456-426655440000 |
| ResourceGroupId | string | 否 | 自定义镜像所在的资源组 ID。如果不设置该参数值，创建的镜像属于默认资源组。 说明
如果您当前使用的是 RAM 用户调用该接口，且 ResourceGroupId取值为空，您需要注意，当 RAM 用户没有默认资源组权限时，调用接口会返回报错信息Forbidden: User not authorized to operate on the specified resource。请您设置 RAM 用户支持的资源组 ID 或者通过相应阿里云账号为该 RAM 用户授予默认资源组权限后，再次调用该接口。
| rg-bp67acfmxazb4p**** |
| DiskDeviceMapping | array<object> | 否 | 创建的自定义镜像信息列表。 | |
| object | 否 | 创建的自定义镜像信息列表。 | ||
| SnapshotId | string | 否 | 根据指定的快照创建自定义镜像。 | s-bp17441ohwkdca0**** |
| Size | integer | 否 | 云盘的大小，单位为 GiB。DiskDeviceMapping.N.Size 的取值和默认值和 DiskDeviceMapping.N.SnapshotId 有关：
| 2000 |
| Device | string | 否 | 指定在自定义镜像中的设备名称。取值范围：
| /dev/vdb |
| DiskType | string | 否 | 指定在新镜像中的云盘类型。您可以通过该参数使用数据盘快照做为镜像的系统盘，如果不指定，默认为快照对应的云盘类型。取值范围：
| system |
| Tag | array<object> | 否 | 标签列表。 | |
| object | 否 | 标签列表。 | ||
| key | string | 否 | 镜像的标签键。 说明
为提高兼容性，建议您尽量使用 Tag.N.Key 参数。
| null |
| Key | string | 否 | 镜像的标签键。N 的取值范围为 1~20。一旦传入该值，则不允许为空字符串。最多支持 128 个字符，不能以 | KeyTest |
| Value | string | 否 | 镜像的标签值。N 的取值范围为 1~20。一旦传入该值，允许为空字符串。最多支持 128 个字符，不能以 | ValueTest |
| value | string | 否 | 镜像的标签值。 说明
为提高兼容性，建议您尽量使用 Tag.N.Value 参数。
| null |
| DetectionStrategy | string | 否 | 镜像检测策略，不配置此参数时不触发检测。仅支持标准（Standard）检测模式。 说明
目前已支持大部分的 Linux/Windows 版本，关于镜像检测项与操作系统限制说明，请参见镜像检测概述和镜像检测操作系统限制。
| Standard |
| Features | object | 否 | 镜像特性相关属性。 | |
| ImdsSupport | string | 否 | 镜像的元数据访问模式，可能值：
默认值：当使用快照创建镜像时，默认为 v1。当使用实例创建镜像时，默认取实例创建时镜像的 ImdsSupport 属性值。 | v2 |
返回参数
示例
正常返回示例
JSON格式
{
"ImageId": "m-bp146shijn7hujku****",
"RequestId": "C8B26B44-0189-443E-9816-*******"
}错误码
| HTTP status code | 错误码 | 错误信息 | 描述 |
|---|---|---|---|
| 400 | InvalidImageName.Malformed | The specified Image name is wrongly formed. | 镜像名称格式错误。长度为2~128个字符。必须以大小字母或中文开头，不能以aliyun和acs:开头，不能包含http://或者https://。可以包含数字、半角句号（.）、半角冒号（:）、下划线（_）或者短划线（-）。 |
| 400 | InvalidImageName.Duplicated | The specified Image name has already bean used. | 镜像名称已经重复。 |
| 400 | InvalidDescription.Malformed | The specified description is wrongly formed. | 指定的资源描述格式不合法。长度为 2-256 个字符，不能以 http:// 和 https:// 开头。 |
| 400 | InvalidImageVersion.Malformed | The specified ImageVersion is wrongly formed. | 无效的镜像版本号取值（或者您无权使用该快照）。 |
| 400 | IncorrectInstanceStatus | The current status of the instance does not support this operation. | 当前实例状态不支持此操作。 |
| 400 | InstanceLockedForSecurity | The specified operation is denied as your instance is locked for security reasons. | 实例被安全锁定。 |
| 400 | InvalidDevice.Malformed | The specified parameter DiskDeviceMapping.n.Device is not valid. | 指定的参数 DiskDeviceMapping.n.Device 不合法。 |
| 400 | MissingParameter | The input parameter SnapshotId or InstanceId or DiskDeviceMapping that is mandatory for processing this request is not supplied. | 参数 SnapshotId，InstanceId 和 DiskDeviceMapping 不得为空。 |
| 400 | InvalidSize.ValueNotSupported | The specified parameter DiskDeviceMapping.n.Size beyond the permitted range. | 指定的参数 DiskDeviceMapping.n.Size 超出取值范围。 |
| 400 | InvalidDevice.InUse | The specified parameter DiskDeviceMapping.n.Device has been occupied. | 指定的参数 DiskDeviceMapping.n.Device 已被占用。 |
| 400 | OperationDenied | The specified parameter DiskDeviceMapping.n.SnapshotId does not contain system disk snapshot. | 系统盘快照中不存在指定的 DiskDeviceMapping 快照 ID。 |
| 400 | OperationDenied | The specified parameter DiskDeviceMapping.n.SnapshotId contains two or more system disk snapshots. | 指定的 DiskDeviceMapping 快照 ID 中已存在系统盘快照。 |
| 400 | InvalidDiskCategory.CreateImage | The specified diskCategory is not allowed to create image. | 指定的磁盘类型不允许创建镜像。 |
| 400 | InvalidArchitecture.Malformed | The specified Architecture is wrongly formed. | 参数 Architecture 格式错误。 |
| 400 | InvalidPlatform.Malformed | The specified Platform is wrongly formed. | 指定的镜像操作系统发行版不合法。 |
| 400 | OperationDenied | Not support creating system image from an encrypted snapshot/disk. | 被加密的磁盘和快照不允许创建系统镜像。 |
| 400 | InvalidParameter.AllEmpty | %s | 您没有输入任何参数，请输入必要的参数。 |
| 400 | InvalidParameter.DiskType | The specified disk type which has kms key can't convert to system disk. | - |
| 400 | Duplicate.TagKey | The Tag.N.Key contain duplicate key. | 标签中存在重复的键，请保持键的唯一性。 |
| 400 | InvalidTagKey.Malformed | The specified Tag.n.Key is not valid. | 指定的标签键参数有误。 |
| 400 | InvalidTagValue.Malformed | The specified Tag.n.Value is not valid. | 指定的标签值参数有误。 |
| 400 | InvalidInstance.NotFoundSystemDisk | The specified instance does not have system disk. | - |
| 400 | InvalidImageFamily.Malformed | The format of the specified image family is invalid. | 指定的镜像族系格式有误。 |
| 400 | ImageQuotaExceed.ImageFamily | The specified image family exceeds the maximum number of images for one image family. | - |
| 400 | ImageFamilyQuotaExceed | The number of image families exceeds the limit in the region. | - |
| 400 | InvalidDiskType.ValueNotSupported | The specified disk type is not supported. | 指定的磁盘属性不支持。 |
| 400 | IdempotenceParamNotMatch | Request uses a client token in a previous request but is not identical to that request. | 与相同 ClientToken 的请求参数不符合。 |
| 400 | OperationDenied | Shared snapshots do not support creating images. | 共享快照不支持创建自定义镜像。 |
| 400 | InvalidBootMode.NotSupport | The specified parameter BootMode is not supported for current image architecture. | 当前的镜像架构不支持设置该启动模式。 |
| 400 | InvalidParameter.FeaturesImdsSupport | The specified parameter Features.ImdsSupport is not supported. | 指定的参数Features.ImdsSupport不支持。 |
| 403 | IncorrectDiskStatus.NeverAttached | The specified disk has never been attached to instance. | - |
| 403 | InvalidSnapshotId.NotReady | The current status of the DiskDeviceMapping.n.SnapshotId or SnapshotId does not support this operation. | 当前磁盘有创建中的快照，请稍后重试 |
| 403 | InvalidSnapshot.TooOld | This 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 之前。 |
| 403 | OperationDenied | The specified snapshot is not allowed to create image. | 指定快照不允许创建镜像。 |
| 403 | QuotaExceed.Image | The Image Quota exceeds. | 自定义镜像额度已用完。 |
| 403 | OperationDenied | The specified snapshot is not from system disk. | 指定的快照不是系统盘快照。 |
| 403 | InvalidParamter.Conflict | The specified same token is trying to make requests with different parameters. | 同一个 Token 正在请求处理两个不同的参数。 |
| 403 | InvalidAccountStatus.NotEnoughBalance | Your account does not have enough balance. | 账号余额不足，请您先充值再进行该操作。 |
| 403 | InvalidAccountStatus.SnapshotServiceUnavailable | Snapshot service has not been opened yet. | 快照服务未开通，操作无法执行。 |
| 403 | UserNotInTheWhiteList | The user is not in the white list of create image by data disk snapshot. | 您不能通过数据磁盘快照创建镜像，请先加入到该白名单中。 |
| 403 | IncorrectDiskStatus.Invalid | Device status is invalid, please restart instance and try again. | 设备状态无效，请重启实例后再试。 |
| 403 | OperationDenied.InvalidSnapshotCategory | %s | 该快照类型不支持此操作。 |
| 403 | QuotaExceed.Snapshot | The snapshot quota exceeds. | 快照额度超过限制，若要存储新快照，在不影响业务的情况下，请您删除已有的老快照。 |
| 403 | IncorrectDiskStatus.Transferring | The specified device is transferring, you can retry after the process is finished. | 指定磁盘正在迁移中，请在迁移完毕后重试。 |
| 403 | IncorrectDiskStatus | The current disk status does not support this operation. | 当前的磁盘不支持此操作，请您确认磁盘处于正常使用状态，是否欠费。 |
| 403 | InvalidSystemSnapshot.Missing | %s | - |
| 403 | IncorrectDiskStatus.CreatingSnapshot | A previous snapshot creation is in process. | 当前磁盘有创建中的快照，请您等待创建完成再试。 |
| 403 | InvalidParameter.KMSKeyId.CMKUnauthorized | The CMK needs to be added ECS tag. | CMK 未授权 |
| 403 | InvalidParameter.KMSKeyId.CMKNotEnabled | The CMK needs to be enabled. | 加密云盘设置了 KMSKeyId 后，CMK必须处于启用状态。您可以调用密钥管理服务的 DescribeKey 接口查询指定CMK的相关信息。 |
| 403 | InvalidParameter.KMSKeyId.KMSUnauthorized | ECS service have no right to access your KMS. | ECS 服务无权访问您的 KMS。 |
| 403 | QuotaExceed.Tags | %s | 标签数超过可以配置的最大数量。%s为变量，将根据调用API的实际情况动态返回错误信息。 |
| 403 | InvalidSnapshotCategory.NotSupportImageCreation | The specified snapshot category does not support create image. | - |
| 403 | TooManySnapshot.Unfinished | There are too many snapshots being created, please wait for them to be created done. | - |
| 403 | HibernationConfigured.InstanceOperationForbidden | The operation is not permitted due to limit of the hibernation configured instance. | 不符合开启休眠选项的实例的相关限制，操作不被允许。 |
| 403 | SnapshotNotReady | The specified snapshot is not ready. | 快照未完成创建，无法用来创建镜像。 |
| 403 | IncorrectInstanceStatus.NeedRestart | The instance needs to be restarted after adding a disk in a shutdown status. | 在关机状态下添加云盘后需要重启实例后才能创建自定义镜像。 |
| 403 | QuotaExceed.ConcurrentSnapshotQuota | The 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. | 该磁盘正在创建的快照数量已超过并发配额，请等待之前的快照完成后再重试。 |
| 404 | InvalidSnapshotId.NotFound | The specified SnapshotId does not exist. | 指定的快照不存在，请您检查快照是否正确。 |
| 404 | InvalidInstanceId.NotFound | The specified InstanceId does not exist. | 指定的InstanceId不存在。 |
| 404 | InvalidResourceGroup.NotFound | The ResourceGroup provided does not exist in our records. | 资源组并不在记录中。 |
| 500 | InternalError | The process of creating snapshot has failed due to some unknown error. | 创建快照失败。 |
| 500 | InternalError | The request processing has failed due to some unknown error, exception or failure. | 内部错误，请重试。 |
访问错误中心查看更多错误码。
变更历史
| 变更时间 | 变更内容概要 | 操作 |
|---|---|---|
| 2024-12-05 | OpenAPI 错误码发生变更、OpenAPI 入参发生变更 | 查看变更详情 |
| 2024-10-22 | OpenAPI 错误码发生变更 | 查看变更详情 |
| 2024-06-12 | OpenAPI 错误码发生变更 | 查看变更详情 |
| 2024-05-09 | OpenAPI 错误码发生变更 | 查看变更详情 |
| 2021-06-17 | OpenAPI 错误码发生变更 | 查看变更详情 |