Creates a custom image. You can use a custom image to create instances (RunInstances) or change the system disk for an existing instance (ReplaceSystemDisk).

Description

When you call this interface, consider the following:

  • You can use a custom image only after its status becomes Available (Available).

  • If the specified instance is locked, and the OperationLocks of the instance indicates LockReason:  "security".

Approaches

Three approaches of creating a custom image are as follows:

Approach 1. If you want to create a custom image based on the system disk of your ECS instance, you can specify one of the system disk snapshots (SnapshotId) to create a custom image. However, the specified snapshot cannot be created on or earlier than July 15, 2013.

Approach 2. If you want to create a template for a whole ECS instance, you can specify the (InstanceId) to create a custom image. You must make sure that the status of the specified instance is Running or Stopped. Running (Running) or Stopped (Stopped). After a successful invocation, each disk of the specified instance has a new snapshot created.

Approach 3. If you want to combine multiple snapshots to make an image template, you can specify DiskDeviceMapping to create a custom image. When you specify DiskDeviceMapping, consider the following:

  • You can only specify one system disk snapshot. The device name of the system disk must be /dev/xvda.

  • You can specify multiple data disk snapshots. The device names of the data disks are allocated sequentially from /dev/xvdb to /dev/xvdz, without duplicates.

  • SnapshotId is not required, if you do not specify the SnapshotId, a disk with empty size is created.

  • However, the specified SnapshotId cannot be created on or earlier than July 15, 2013.

Request parameters

Name Type Required Description
Action String Yes The name of this interface. Value: CreateImage.
RegionId String Yes The region ID of the image. For more information, see DescribeRegions.
SnapshotId String No The snapshot ID. A custom image is created from the specified snapshot.
InstanceId String No Instance ID.
DiskDeviceMapping.N.Size String No The size of a disk. The unit of measurement is GiB. Value range: [5, 2000] GiB.
  • The default value is the value of snapshot size (DiskDeviceMapping.N.SnapshotId) if you do not specify this parameter.
  • If you do not specify the snapshot ID (DiskDeviceMapping.N.SnapshotId), the default size is 5 GiB.
  • The size value cannot be less than the size of the snapshot (DiskDeviceMapping.N.SnapshotId).
The value range of n in DiskDeviceMapping.n is: [1, 17].
  • n =1: Indicates the specified disk is a system disk.
  • n =2, 3, ……17: Indicates the specified disk is a data disk.
DiskDeviceMapping.N.SnapshotId String No The snapshot ID of the disk DiskDeviceMapping.N..
ImageName String No Image name.
  • Can contain [2, 128] characters in length. Must begin with an English letter or Chinese character. Can contain digits, colons (:), underscores (_), or hyphens (-).
  • Cannot begin with http:// or https://.
ImageVersion String No The version number of the image, with a length limit of [1, 40] English characters.
Description String No The description of the image.
  • It can be [0, 256] letters in length.
  • It cannot begin with http:// or https://.
  • Default value: null.
ClientToken String No Guarantees the idempotence of the request. The value is generated by a client. It must be unique among all requests and contains a maximum of 64 ASCII characters. For more information, see How to ensure idempotence.

Response parameters

Name Type Description
ImageId String Image ID

Examples

Request example
https://ecs.aliyuncs.com/?Action=CreateImage
&RegionId=cn-hangzhou
&SnapshotId=s-snapshot1
&ImageName=demo_image
&<Common Request Parameters>
Response example

XML format

<CreateImageResponse>
    <RequestId>C8B26B44-0189-443E-9816-D951F59623A9</RequestId>
    <ImageId>m-63DFD5FB2</ImageId>
</CreateImageResponse>
JSON format
{
    "RequestId": "C8B26B44-0189-443E-9816-D951F59623A9",
    "ImageId": "m-63DFD5FB2"
}

Error codes

Error codes specific to this interface are as follows. For more error codes, visit the  API error center.

Error code Error message HTTP status code  Description
IncorrectInstanceStatus The current status of the instance does not support this operation. 400 The status of the specified instance must be Running or Stopped.
InstanceLockedForSecurity The input parameter InstanceId that is mandatory for processing this  security reasons. 400 The specified instance has been locked for the sake of security.
InvalidDescription.Malformed The specified description is wrongly formed. 400 The specified Description is invalid.
InvalidImageName.Duplicated The specified Image name has already been used. 400 The value of the specified ImageName already exists.
InvalidImageName.Malformed The specified Image name is wrongly formed. 400 The format of the specified ImageName is incorrect.
InvalidImageVersion.Malformed The specified ImageVersion is wrongly formed. 400 The format of the specified ImageVersion is incorrect. Or you are not authorized to access the specified ImageVersion.
InvalidInstanceId.NotFound The specified InstanceId does not exist. 400 The specified InstanceId does not exist.
InvalidInstanceId.ValueNotSupported The specified InstanceId is not allowed to create image. 400 The specified InstanceId cannot be used to create custom images.
InvalidSize.ValueNotSupported The specified parameter DiskDeviceMapping.n.Size beyond the permitted range. 400 The maximum size of the specified DiskDeviceMapping.n.Size value is exceeded.
MissingParameter The input parameter SnapshotId or InstanceId or DiskDeviceMapping that is mandatory for processing this request is not supplied. 400 You must specify the required SnapshotId, InstanceId, or DiskDeviceMapping.
OperationDenied The specified parameter DiskDeviceMapping.n.SnapshotId does not contain system disk snapshot. 400 One system disk snapshot must be contained in the list of DiskDeviceMapping.n.SnapshotId.
OperationDenied The specified parameter DiskDeviceMapping.n.SnapshotId contains two or more system disk snapshots. 400 Parameter Only one system disk snapshot can be contained in the list of DiskDeviceMapping.n.SnapshotId.
Invalidaccountant status. Your account does not have enough balance. 403 Your registered credit card is invalid or you have insufficient balance in your PayPal account.
InvalidAccountStatus.SnapshotServiceUnavailable Snapshot service has not been opened yet. 403 You have not signed up for the snapshot service yet. Please visit ECS console to sign up and activate your account.
InvalidParamter.Conflict The specified same token is trying to make requests with different parameters. 403 The specified ClientToken is uniformed with the parameters.
InvalidSnapshot.TooOld This operation is denied because the specified snapshot by DiskDeviceMapping.n.SnapshotId or SnapshotId is created before 2013-07-15. 403 The specifed snapshot cannot be created on or earlier than July 15, 2013.
InvalidSnapshotId.NotReady The current status of the DiskDeviceMapping.n.SnapshotId or SnapshotId does not support this operation. 403 The status of specified snapshot is incorrect.
OperationDenied The specified snapshot is not allowed to create image. 403 The snapshot of the specified disk cannot be used to create images.
OperationDenied The specified snapshot is not from system disk. 403 Only a system disk snapshot can be used to create custom images.
QuotaExceed.Image The Image Quota exceeds. 403 The maximum number of your custom images have exceeded.
InvalidRegionId.NotFound The specified RegionId does not exist. 404 The specified RegionId does not exist.
InvalidSnapshotId.NotFound The specified SnapshotId does not exist. 404 The specified SnapshotId does not exist.
InvalidSnapshotId.NotFound The specified SnapshotId does not exist. 404 The specified SnapshotId does not exist.