You can call this operation to copy a custom image from one region to another. You can deploy or copy ECS instances across regions by copying images.

Description

You can use the image copy to create ECS instances (RunInstances) or replace system disks of instances (ReplaceSystemDisk) in the destination region.

When you call this operation, take note of the following items:

  • Only custom images that are in the Available (Available) state can be copied.
  • You can copy only the images within your Alibaba Cloud account. Images cannot be copied from one account to another.
  • If an image is being copied, you cannot delete the image copy by calling the DeleteImage operation, but you can cancel the copy task by calling the CancelCopyImage operation.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates a sample code of the operation for different SDKs.

Request parameters

Parameter Position Type Required Example Description
Action Query String Yes CopyImage

The operation that you want to perform. Set the value to CopyImage.

ImageId Query String Yes m-bp1h46wfpjsjastc****

The ID of the source custom image.

RegionId Query String Yes cn-hangzhou

The region ID of the source custom image. You can call the DescribeRegions operation to query the most recent region list.

DestinationRegionId Query String No cn-shanghai

The ID of the destination region to which to copy the source custom image.

DestinationImageName Query String No YourImageName

The name of the image copy. The name must be 2 to 128 characters in length and can contain letters, digits, colons (:), underscores (_), and hyphens (-). It must start with a letter and cannot start with http:// or https://.

This parameter is empty by default.

DestinationDescription Query String No This is a description example.

The description of the image copy. The description must be 2 to 256 characters in length and cannot start with http:// or https://.

This parameter is empty by default.

Encrypted Query Boolean No false

Specifies whether to encrypt the image copy.

Default value: false.

KMSKeyId Query String No e522b26d-abf6-4e0d-b5da-04b7******3c

The ID of the key used to encrypt the image copy.

Response parameters

Parameter Type Example Description
ImageId String m-bp1h46wfpjsjastd****

The ID of the image copy.

RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

The ID of the request.

Examples

Sample requests

https://ecs.aliyuncs.com/?Action=CopyImage
&ImageId=m-bp1h46wfpjsjastc****
&RegionId=cn-hangzhou
&<Common request parameters>

Sample success responses

XML format

<CopyImageResponse>
      <RequestId>C8B26B44-0189-443E-9816-D951F59623A9</RequestId>
      <ImageId>m-bp1h46wfpjsjastd****</ImageId>
</CopyImageResponse>

JSON format

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

Error codes

HTTP status code Error code Error message Description
401 InvalidAliUid.IsNull The aliUid must not be null The error message returned because the required aliUid parameter is not specified.
400 InvalidImageName.Malformed The specified Image name is wrongly formed. The error message returned because the specified DestinationImageName parameter is invalid. The name must be 2 to 128 characters in length and can contain letters, digits, periods (.), underscores (_), and hyphens (-). It must start with a letter but cannot start with http:// or https://.
403 Forbbiden User not authorized to operate on the specified resource. The error message returned because you are not authorized to perform operations on the specified resource.
400 InvalidImageName.Malformed The specified destination Image name is wrongly formed. The error message returned because the specified DestinationImageName parameter is invalid. For more information, see the description for the DestinationImageName parameter.
400 InvalidDescription.Malformed The specified destination description is wrongly formed. The error message returned because the specified DestinationDescription parameter is invalid. The description must be 2 to 256 characters in length and cannot start with http:// or https://.
400 InvalidDescription.Malformed The specified description is wrongly formed. The error message returned because the specified DestinationDescription parameter is invalid. The description must be 2 to 256 characters in length and cannot start with http:// or https://.
400 SourceRegion.NotFound The source region not found The error message returned because the specified RegionId parameter does not exist.
400 DestinationRegion.NotFound The destination region not found The error message returned because the specified DestinationRegionId parameter does not exist.
404 InvalidImageId.NotFound The specified ImageId does not exist. The error message returned because the specified image does not exist in this account.
400 IncorrectImageStatus The image not available. The error message returned because the specified image is unavailable.
400 InvalidSnapshotId.NotFound The specified SnapshotId does not exist. The error message returned because the specified snapshot does not exist. Check whether the snapshot ID is correct.
400 InvalidImageName.Duplicated The destination image is exist. The error message returned because the specified image name already exists.
403 QuotaExceed.Image The Image Quota exceeds. The error message returned because the maximum number of custom images has been reached.
403 QuotaExceed.Snapshot The snapshot quota exceeds. The error message returned because the maximum number of snapshots has been reached. To store new snapshots, delete snapshots that are no longer needed.
403 OperationDenied.ImageCopying The Image are coping. The error message returned because the source image is being copied. Try again later.
403 RegionNotSupportCopy The region not support copy. The error message returned because the specified source or destination region does not support image copying.
403 InvalidSnapshot.TooOld This operation is denied because the specified snapshot is created before 2013-07-15. The error message returned because the operation is not supported while the specified snapshot was created before July 15, 2013.
403 OperationDenied The specified snapshot is not allowed to create image. The error message returned because the specified snapshot cannot be used to create images.
403 IncorrectDestinationRegion The destination region is not equal the target region. The error message returned because the source region is the same as the destination region.
403 SizeExceed.Image The image exceeds the maximum size. Please open a ticket to add the account to the white list. The error message returned because the size of the image exceeds the upper limit. Contact customer service to request a quota increase.
403 OperationDeined.EncryptedSnapshot The image contains encrypted snapshots, which do not support copying. The error message returned because the specified image contains encrypted snapshots and cannot be copied.
403 InternalError The request processing has failed due to some unknown error. The error message returned because an internal error has occurred. Try again later. If the problem persists, submit a ticket.
403 OperationDenied.SameRegionOnly The image shared from others can not be copied to another region directly. The error message returned because you cannot copy images shared by other Alibaba Cloud accounts to another region.
403 OperationDenied.NotPublished The operation is denied because corresponding marketplace image is not published in destination region. The error message returned because the image type is not supported in the destination region and the operation is rejected.
404 InvalidParameter.KMSKeyId.NotFound The specified KMSKeyId does not exist. The error message returned because the specified KMSKeyId parameter does not exist.
403 InvalidParameter.KMSKeyId.KMSUnauthorized ECS service have no right to access your KMS. The error message returned because ECS is not authorized to access your KMS resources.
500 InternalError The request processing has failed due to some unknown error, exception or failure. The error message returned because an internal error has occurred. Try again later. If the problem persists, submit a ticket.
403 InvalidRegion.NotSupport The specified region does not support byok. The error message returned because the bring your own key (BYOK) feature is not supported in this region.
403 UserNotInTheWhiteList The user is not in byok white list. The error message returned because you are not in the BYOK whitelist. Try again when you are in the whitelist.
400 InvalidParameter.EncryptedIllegal The specified parameter Encrypted must be true when kmsKeyId is not empty. The error message returned because the encryption feature is not enabled after a KMS key ID is specified.

For a list of error codes, visit the API Error Center.