CreateImage

Last Updated: May 17, 2018

Description

Creates a custom image. When you call this interface, consider the following:

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 SnapshotId 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. 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 DiskDeviceMappings to create a custom image. When you specify DiskDeviceMappings, 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 Regions and Zones.
SnapshotId String Yes The snapshot ID. A custom image is created from the specified snapshot.
InstanceId String No The instance ID.
DiskDeviceMapping.N.Size String No The size of a disk. Value range: [5, 2000] GB.
  • The default value is the value of snapshot size (DiskDeviceMapping.N.SnapshotId) if you do not specify this parameter.
  • The default size is 5 GB if you do not specify the SnapshotId (DiskDeviceMapping.N.SnapshotId).
  • 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.
ImageName String No The name of the image.
  • It can be [2, 128] letters in length.
  • It must begin with an uppercase or lowercase letter and may contain numbers, colons(:), underscores (_) or hyphens (-).
  • It 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 Used to guarantee 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 ID of an image.

Examples

Request example

  1. https://ecs.aliyuncs.com/?Action=CreateImage
  2. &RegionId=cn-hangzhou
  3. &SnapshotId=s-snapshot1
  4. &ImageName=demo_image
  5. &<Common Request Parameters>

Response example

XML format

  1. <CreateImageResponse>
  2. <RequestId>C8B26B44-0189-443E-9816-D951F59623A9</RequestId>
  3. <ImageId>m-63DFD5FB2</ImageId>
  4. </CreateImageResponse>

JSON format

  1. {
  2. "RequestId": "C8B26B44-0189-443E-9816-D951F59623A9",
  3. "ImageId": "m-63DFD5FB2"
  4. }

Error codes

Error code Error message HTTP status code Meaning
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 specified operation is denied as your instance is locked for 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 ImageVersion 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 snapshot.
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 Only one system disk snapshot can be contained in the list of DiskDeviceMapping.n.SnapshotId.
InvalidAccountStatus.NotEnoughBalance Your account does not have enough balance. 403 You registered credit card is invalid or no 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. For more information, see Regions and zones.
InvalidSnapshotId.NotFound The specified SnapshotId does not exist. 404 The specified SnapshotId does not exist.
Thank you! We've received your feedback.