Help Center/ Image Management Service/ API Reference/ IMS APIs/ Image Replication/ Replicating an Image Across Regions
Updated on 2026-07-07 GMT+08:00
View PDF
Share

Replicating an Image Across Regions

Function

This is an extended API used to replicate a private image from one region to another. In the destination region, the replicated image can be used to create ECSs identical to those in the source region. This allows you to migrate services between regions.

This is an asynchronous API. If job_id is returned, the job is successfully delivered. You need to query the status of the asynchronous job. If the status is success, the job is successfully executed. If the status is failed, the job fails.

Huawei Cloud has stopped providing Windows images. This API will no longer be used to replicate Windows images.

Constraints

  • The destination region cannot be the same as the source region.
  • Encrypted images cannot be replicated across regions.
  • The size of an image to be replicated across regions cannot exceed 128 GB.
  • A maximum of five private images can be replicated at a time.
  • Private images created from ISO files cannot be replicated across regions.

Debugging

You can debug this API in API Explorer.

Authorization

Each account has all of the permissions required to call all APIs, but IAM users must have the required permissions specifically assigned. For details about the required permissions, see Permissions and Supported Actions.

URI

POST /v1/cloudimages/{image_id}/cross_region_copy

Table 1 lists the parameters in the URI.
Table 1 Parameter description

Parameter

Mandatory

Type

Description

image_id

Yes

String

Definition

Image ID. For details about how to obtain an image ID, see Querying Images.

Constraints

N/A

Range

N/A

Default Value

N/A

Request

Request parameters

Parameter

Mandatory

Type

Description

name

Yes

String

Definition

Image name. For details about name, see Image Attributes.

Constraints

A name cannot start or end with a space. The name length must be 1 to 128 characters.

Range

A name can contain only letters, digits, spaces, hyphens (-), underscores (_), and periods (.), and cannot start or end with a space.

Default Value

N/A

description

No

String

Definition

Image description. For details about description, see Image Attributes.

Constraints

The value contains a maximum of 1,024 characters, including letters and digits. Carriage returns and angle brackets (< >) are not allowed.

Range

N/A

Default Value

N/A

region

Yes

String

Definition

Destination region ID.

For details about how to obtain region IDs, see Listing Regions.

Constraints

N/A

Range

N/A

Default Value

N/A

project_name

Yes

String

Definition

Name of a project in the destination region.

Constraints

N/A

Range

N/A

Default Value

N/A

agency_name

Yes

String

Definition

Agency name.

For details about how to create an IAM agency, see How Do I Create an IAM Agency?

Constraints

N/A

Range

N/A

Default Value

N/A

vault_id

No

String

Definition

Vault ID.

You can obtain a vault ID from the CBR console or by referring to Querying the Vault List.

Constraints

This parameter is mandatory if you are replicating a full-ECS image.

Range

N/A

Default Value

N/A

Example Request

  • Replicating an image to project-1 of region-1 
    1
2
3
4
5
6
7
8
    		 
    POST https://{Endpoint}/v1/cloudimages/465076de-dc36-4aec-80f5-ef9d8009428f/cross_region_copy
{
    "name":"test-copy-1001-4",
    "description":"test",
    "region":"region-1",
    "project_name":"project-1",
    "agency_name":"ims_copy_image"
}
  • Replicating a full-ECS image to project-1 of region-1 (vault ID: 6yhtb5df-1bc3-4c3f-893e-3e4716yhgt61) 
    1
2
3
4
5
6
7
8
9
    		 
    POST https://{Endpoint}/v1/cloudimages/465076de-dc36-4aec-80f5-ef9d8009428f/cross_region_copy
{
    "name":"test-copy-1001-4",
    "description":"test",
    "region":"region-1",
    "project_name":"project-1",
    "agency_name":"ims_copy_image",
    "vault_id":"6yhtb5df-1bc3-4c3f-893e-3e4716yhgt61"
}

Response

  • Response parameters

    Parameter

    Type

    Description

    job_id

    String

    Definition

    Asynchronous job ID.

    For details, see Querying the Progress of an Asynchronous Job.

    Range

    N/A
  • Example response 
    STATUS CODE 200
    1
2
3
    		 
    {
    "job_id": "edc89b490d7d4392898e19b2deb34797"
}

Returned Values

  • Normal

    200

  • Abnormal

    Returned Value

    Description

    400 Bad Request

    Request error. For details, see Error Codes.

    401 Unauthorized

    Authentication failed.

    403 Forbidden

    You do not have the rights to perform the operation.

    404 Not Found

    The requested resource was not found.

    500 Internal Server Error

    Internal service error.

    503 Service Unavailable

    The service is unavailable.
Parent topic: Image Replication