Call the CreateImage API to create a custom image - Elastic Compute Service - Alibaba Cloud - Elastic Compute Service

Creates a custom image. You can use the created custom image to create ECS instances (RunInstances) or replace the system disk of an instance (ReplaceSystemDisk).

Operation description

Before you begin

This is an asynchronous operation. After a request to create a custom image is sent, the image ID is returned. However, the image creation is not immediately complete. Call DescribeImage to query the image information. When the status in the response is Available, the image is created and ready for use. For more information, see Custom image overview.
When you query ECS instance information, if the response contains {"OperationLocks": {"LockReason" : "security"}}, you cannot create a custom image.
Configure the image detection parameter DetectionStrategy when creating an image to help the system optimize your image. For more information, see Image detection overview.

The following describes three methods to create a custom image by calling this operation. The priority of request parameters is: InstanceId > DiskDeviceMapping > SnapshotId. If your request contains two or more of these parameters, the image is created based on the parameter with the highest priority.

Create a custom image from an instance: Specify the instance ID (InstanceId).
- The instance must be in the Running (Running) or Stopped (Stopped) state.
- After the operation is called, a new snapshot is created for each disk of the instance.
Important Because a running instance may have cached data that has not been written to disks, the data of the created custom image may be inconsistent with the instance data. Stop the instance (StopInstances) before creating the image.
Create a custom image from a snapshot (the specified snapshot cannot be one created on or before July 15, 2013.)
- Create a custom image from a system disk snapshot: Specify only the snapshot ID of the instance system disk (SnapshotId).
- Create a custom image from system disk and data disk snapshots: Establish data associations among multiple disks (DiskDeviceMapping).
  - Only one system disk snapshot can be specified.
  - You can specify multiple data disk snapshots, up to a maximum of 16. If DiskDeviceMapping.N.SnapshotId is not specified, an empty data disk with the default capacity is created.

Note

When an instance is released, the system disk is retained as a pay-as-you-go data disk. Snapshots created from this disk do not support creating custom images. Create a custom image before releasing the instance as needed.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

ecs:CreateImage

create

*Image

acs:ecs:{#regionId}:{#accountId}:image/*

Instance

acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}

Snapshot

acs:ecs:{#regionId}:{#accountId}:snapshot/{#snapshotId}

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID of the image. You can call DescribeRegions to query the most recent region list.	cn-hangzhou
SnapshotId	string	No	The snapshot ID used to create the custom image. Note If you want to create a custom image only from the system disk snapshot of an instance, you can use this parameter or the `DiskDeviceMapping.N.SnapshotId` parameter. To include data disk snapshots, use only the `DiskDeviceMapping.N.SnapshotId` parameter to specify snapshots.	s-bp17441ohwkdca0****
InstanceId	string	No	The instance ID. This parameter is required when you create a custom image from an instance.	i-bp1g6zv0ce8oghu7****
ImageName	string	No	The image name. The name must be 2 to 128 characters in length. It must start with a letter or a Chinese character and cannot start with http:// or https://. It can contain digits, colons (:), underscores (_), or hyphens (-).	TestCentOS
ImageFamily	string	No	The image family name. The name must be 2 to 128 characters in length. It must start with a letter or a Chinese character and cannot start with aliyun or acs:. It cannot contain http:// or https://. It can contain digits, colons (:), underscores (_), or hyphens (-).	hangzhou-daily-update
ImageVersion	string	No	The image version. Note If you specify an instance ID (`InstanceId`) and the image of the instance is an Alibaba Cloud Marketplace image or a custom image created from an Alibaba Cloud Marketplace image, this parameter must be the same as the `ImageVersion` of the current instance image or left empty.	2017011017
Description	string	No	The description of the image. The description must be 2 to 256 characters in length and cannot start with http:// or https://.	ImageTestDescription
Platform	string	No	The operating system distribution. After a data disk snapshot is specified as the system disk of the image, use this parameter to specify the operating system distribution of the system disk. Valid values: 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 Default value: Others Linux.	CentOS
BootMode	string	No	The boot mode of the image. Valid values: BIOS: BIOS boot mode. UEFI: UEFI boot mode. (Default) UEFI-Preferred: dual boot mode. Important To prevent instances from failing to start due to an unsupported boot mode, make sure that you understand the boot modes supported by the target image before specifying this parameter. For more information about image boot modes, see Image boot modes. Valid values: BIOS : BIOS UEFI : UEFI UEFI-Preferred : UEFI-Preferred	BIOS
Architecture	string	No	The system architecture. After a data disk snapshot is specified as the system disk of the image, use this parameter to specify the system architecture of the system disk. Valid values: i386. x86_64. arm64. Default value: x86_64.	x86_64
ClientToken	string	No	The client token that is used to ensure the idempotence of the request. You can use the client to generate the token, but make sure that the token is unique among different requests. ClientToken can contain only ASCII characters and cannot exceed 64 characters in length. For more information, see How to ensure idempotence.	123e4567-e89b-12d3-a456-426655440000
ResourceGroupId	string	No	The ID of the resource group to which the custom image belongs. If this parameter is not set, the created image belongs to the default resource group. Note If you invoke this operation as a Resource Access Management (RAM) user and `ResourceGroupId` is left empty, note that when the RAM user does not have permissions on the default resource group, the error message `Forbidden: User not authorized to operate on the specified resource` is returned. Set a resource group ID that the RAM user has permissions on, or grant the RAM user permissions on the default resource group before invoking this operation again.	rg-bp67acfmxazb4p****
DiskDeviceMapping	array<object>	No	The disk and snapshot information used to create the custom image. Use this parameter to specify snapshots when you want to create a custom image from system disk and data disk snapshots.
	object	No	The disk and snapshot used to create the custom image.
SnapshotId	string	No	The snapshot ID.	s-bp17441ohwkdca0****
Size	integer	No	The size of the disk, in GiB. The valid values and default value of DiskDeviceMapping.N.Size depend on DiskDeviceMapping.N.SnapshotId: If SnapshotId is not specified, the valid values and default value of Size are: Basic disk: 5 to 2000 GiB. Default value: 5. Other disk types: 20 to 32768 GiB. Default value: 20. If SnapshotId is specified, the value of Size must be greater than or equal to the size of the snapshot. Default value: the size of the snapshot.	2000
Device	string	No	The device name in the custom image. Valid values: The device name of the system disk must be /dev/xvda. Data disk device names are sequentially ordered from /dev/xvdb to /dev/xvdz and cannot be duplicated.	/dev/xvdb
DiskType	string	No	The type of the disk in the new image. You can use this parameter to specify a data disk snapshot as the system disk of the image. If this parameter is not specified, the disk type defaults to the type of the disk corresponding to the snapshot. Valid values: system: system disk. Only one system disk snapshot can be specified. data: data disk. Up to 16 data disk snapshots can be specified.	system
Tag	array<object>	No	The tags.
	object	No	The tags.
key	string	No	The tag key of the image. Note For better compatibility, use Tag.N.Key instead.	null
Key	string	No	The tag key of the image. Valid values of N: 1 to 20. The tag key cannot be an empty string. It can be up to 128 characters in length and cannot start with `aliyun` or `acs:`. It cannot contain `http://` or `https://`.	KeyTest
Value	string	No	The tag value of the image. Valid values of N: 1 to 20. The tag value can be an empty string. It can be up to 128 characters in length and cannot start with `acs:`. It cannot contain `http://` or `https://`.	ValueTest
value	string	No	The tag value of the image. Note For better compatibility, use Tag.N.Value instead.	null
DetectionStrategy	string	No	The image detection strategy. If this parameter is not specified, detection is not triggered. Only the Standard detection mode is supported. Note Most Linux and Windows versions are supported. For more information about image detection items and operating system limitations, see Image detection overview and Operating system limitations for image detection.	Standard
Features	object	No	The image feature properties.
ImdsSupport	string	No	The metadata access mode of the image. Valid values: v1: When you create an ECS instance from this image, you cannot set the metadata access mode to "security hardening mode only". v2: When you create an ECS instance from this image, you can set the metadata access mode to "security hardening mode only". Default value: When creating an image from a snapshot, the default is v1. When creating an image from an instance, the default is the ImdsSupport value of the image used when the instance was created.	v2
DryRun	boolean	No

Response elements

Element	Type	Description	Example
	object
ImageId	string	The image ID.	m-bp146shijn7hujku****
RequestId	string	The request ID.	C8B26B44-0189-443E-9816-*******

Examples

Success response

JSON format

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

Error codes

HTTP status code	Error code	Error message	Description
400	InvalidImageName.Malformed	The specified Image name is wrongly formed.	The specified image name is invalid. The name must be 2 to 128 characters in length. It must start with a letter and cannot start with acs: or aliyun. It can contain letters, digits, periods (.), colons (:), underscores (_), and hyphens (-). It cannot contain http:// or https://.
400	InvalidImageName.Duplicated	The specified image name is already in use.	The specified image name is already in use.
400	InvalidDescription.Malformed	The specified description is wrongly formed.	The resource description is invalid. The description must be 2 to 256 characters in length and cannot start with http:// or https://.
400	InvalidImageVersion.Malformed	The specified ImageVersion is wrongly formed.	The specified image version is invalid, or you are not authorized to use the snapshot.
400	IncorrectInstanceStatus	The current status of the instance does not support this operation.	The instance is in a state that does not support the current 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.	The specified DiskDeviceMapping.N.Device parameter is invalid.
400	MissingParameter	The input parameter SnapshotId or InstanceId or DiskDeviceMapping that is mandatory for processing this request is not supplied.	The SnapshotId, InstanceId, and DiskDeviceMapping parameters are required.
400	InvalidSize.ValueNotSupported	The specified parameter DiskDeviceMapping.n.Size beyond the permitted range.	The specified DiskDeviceMapping.N.Size parameter is out of range.
400	InvalidDevice.InUse	The specified parameter DiskDeviceMapping.n.Device has been occupied.	Device names specified in the DiskDeviceMapping.N.Device value are already in use.
400	OperationDenied	The specified parameter DiskDeviceMapping.n.SnapshotId does not contain system disk snapshot.	The specified DiskDeviceMapping.N.SnapshotID parameter does not contain a system disk snapshot ID.
400	InvalidDiskCategory.CreateImage	The specified diskCategory is not allowed to create image.	Disks of the specified category cannot be used to create custom images.
400	InvalidArchitecture.Malformed	The specified Architecture is wrongly formed.	The specified Architecture parameter is invalid.
400	InvalidPlatform.Malformed	The specified Platform is wrongly formed.	The specified platform is invalid.
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.	The specified tag key already exists. Tag keys must be unique.
400	InvalidTagKey.Malformed	The specified Tag.n.Key is not valid.	The specified Tag.N.Key parameter is invalid.
400	InvalidTagValue.Malformed	The specified Tag.n.Value is not valid.	The specified tag value is invalid.
400	InvalidInstance.NotFoundSystemDisk	The specified instance does not have system disk.
400	InvalidImageFamily.Malformed	The format of the specified image family is invalid.	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.	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.	This request and the previous request contain the same client token but different other parameters.
400	InvalidBootMode.NotSupport	The specified parameter BootMode is not supported for current image architecture.	The current image architecture does not support setting this boot mode.
400	InvalidParameter.FeaturesImdsSupport	The specified parameter Features.ImdsSupport is not supported.	The specified parameter Features.ImdsSupport is not supported.
400	InvalidOperation.DiskCategoryUnsupported	The current category of the disk does not support this operation.	The disk type does not support the current operation.
400	AccountForbidden.CreateOrder	Order cannot be created due to abnormal account.	The current account is not allowed to create orders.
400	InvalidBootMode.Malformed	The specified parameter BootMode is invalid. Valid options are BIOS, UEFI, and UEFI-Preferred.	The specified parameter BootMode is invalid. Valid options are BIOS, UEFI, and UEFI-Preferred.
400	InvalidDetectionStrategy.Malformed	The specified value for parameter DetectionStrategy is not supported. Please refer to the documentation for accepted values.	The specified DetectionStrategy parameter value is not supported. Refer to the documentation for acceptable values.
400	InvalidParameter.SecureBootSupport	The specified parameter SecureBootOptions.SecureBootSupport is not valid.	The specified parameter SecureBootOptions.SecureBootSupport is not valid.
500	InternalError	The process of creating snapshot has failed due to some unknown error.	The snapshot cannot be created.
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.	The current disk has a snapshot being created, please try again later.
403	InvalidSnapshot.TooOld	This operation is denied because the specified snapshot by DiskDeviceMapping.n.SnapshotId or SnapshotId is created before 2013-07-15.	The operation is denied because the snapshot specified by the DiskDeviceMapping.N.SnapshotId or SnapshotId parameter was created before July 15, 2013.
403	OperationDenied	The specified snapshot is not allowed to create image.	The specified snapshot cannot be used to create images.
403	QuotaExceed.Image	The Image Quota exceeds.
403	InvalidParamter.Conflict	The specified same token is trying to make requests with different parameters.	The same token is used to make requests that contain different parameters.
403	InvalidAccountStatus.NotEnoughBalance	Your account does not have enough balance.
403	InvalidAccountStatus.SnapshotServiceUnavailable	Snapshot service has not been opened yet.	The operation is not supported while the snapshot service is not activated.
403	UserNotInTheWhiteList	The user is not in the white list of create image by data disk snapshot.	You are not authorized to create an image based on data disk snapshots. Try again when you are authorized to do so.
403	IncorrectDiskStatus.Invalid	Device status is invalid, please restart instance and try again.	The device is in an invalid state. Restart the instance and try again.
403	OperationDenied.InvalidSnapshotCategory	%s	This type of snapshot does not support the operation.
403	QuotaExceed.Snapshot	The snapshot quota exceeds.
403	IncorrectDiskStatus.Transferring	The specified device is transferring, you can retry after the process is finished.	The specified disk is being migrated. Wait until the migration is complete and try again.
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.	ECS does not have the permission to encrypt or decrypt your CMK.
403	InvalidParameter.KMSKeyId.CMKNotEnabled	The CMK needs to be enabled.
403	InvalidParameter.KMSKeyId.KMSUnauthorized	ECS service have no right to access your KMS.	ECS is not authorized to access your KMS resources.
403	QuotaExceed.Tags	%s	The number of specified tags exceeds the upper limit. %s is a variable. An error message is dynamically returned based on call conditions.
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.	The operation cannot be performed due to the limitations of instances for which the instance hibernation feature is enabled.
403	SnapshotNotReady	The specified snapshot is not ready.	The specified snapshot is being created and cannot be used to create images.
403	IncorrectInstanceStatus.NeedRestart	The instance needs to be restarted after adding a disk in a shutdown status.	If you have attached disks to an instance in the Stopped state, you must start the instance before you can create a custom image from the instance.
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.	The number of snapshots being created for this disk has exceeded the concurrent quota. Please wait for the previous snapshots to complete before trying again.
403	InvalidOperation.SnapshotStorageLocationUnsupported	Snapshots with storage location in CloudBox do not support the current operation.	The snapshot of the storage location in the CloudBox does not support the current operation.
403	AccountEnterpriseStatusInvalid	Your enterprise registration is marked as revoked/deregistered in the National Enterprise Credit Information Publicity System. Account transaction features (purchase/renewal/recharge) are disabled. Please update real-name certification via Account Center. Restrictions will auto-remove after verification.	The registration status of your enterprise has been canceled (or revoked) in the national enterprise credit information publicity system, and your account will not be able to carry out transaction operations such as new purchase, renewal and recharge of products. Please change the real name authentication through the account center as soon as possible. After the change is completed, Aliyun will automatically lift the purchase restriction.
403	InvalidOperation.DefaultFreeSnapshotNotSupport	The specified snapshot is a default free snapshot and does not support this operation.	The specified snapshot is a default free snapshot and does not support the current operation.
404	InvalidSnapshotId.NotFound	The specified SnapshotId does not exist.
404	InvalidInstanceId.NotFound	The specified instance %s does not exist.	The specified instance does not exist.
404	InvalidResourceGroup.NotFound	The ResourceGroup provided does not exist in our records.	The specified resource group does not exist.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.