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

Exporting an Image

Function

This is an extended API used to export a private image to an OBS bucket.

Before exporting an image, ensure that you have Tenant Administrator permissions for OBS.

Constraints

Table 1 Constraints on exporting images

Item

Description

Region

An image can only be exported to a Standard bucket that is in the same region as the image.

Image type
The following private images cannot be exported:
  • Full-ECS images
  • ISO images
  • Private images created from a Windows, SUSE, Red Hat, or Oracle Linux public image
  • Private images created from a KooGallery image
NOTE:
  • Fast export is unavailable for encrypted images. To export an encrypted image, decrypt it first.
  • In some regions, private images created from Ubuntu public images can be exported. You can see on the console if such a private image can be exported.

Image format
  • You can export images to the ZVHD2, QCOW2, VMDK, VHD, or ZVHD format. By default, a private image is created in ZVHD2 format. The size of an exported image may vary depending on the export format you select.
  • Fast export only supports the ZVHD2 format. If you need to export the image in another format, you can use the qemu-img-hw tool to convert the image to the required format after the image is exported. For details, see Converting the Image Format Using qemu-img-hw.

Image size
The image size must be less than 1 TiB. Images larger than 128 GiB and smaller than 1 TiB only support fast export. For details about the differences between standard and fast export, see What Are the Differences Between Standard and Fast Import/Export?
NOTE:

In some regions, an image larger than 128 GiB can be exported without enabling fast export. You can see on the console if such a large image can be exported in that way.

Time

The time required for exporting an image depends on the image size and the number of concurrent export tasks.

Billing

You will be billed for storing exported images in the OBS bucket. For details, see OBS Pricing Details.

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}/file

Table 2 lists the parameters in the URI.
Table 2 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

    bucket_url

    Yes

    String

    Definition

    URL of the image file in the format of Bucket name:File name.

    Constraints

    The storage class of the OBS bucket and image files in it must be Standard.

    Range

    N/A

    Default Value

    N/A

    file_format

    Yes

    String

    Definition

    File format.

    Constraints

    N/A

    Range

    The value can be qcow2, vhd, zvhd, or vmdk.

    Default Value

    N/A

    is_quick_export

    No

    Boolean

    Definition

    Whether to use fast export.

    Constraints

    If fast export is used, the file_format parameter cannot be specified. The exported image file is in the ZVHD2 format.

    Range

    The value can be true or false.

    Default Value

    false

Example Request

Exporting an image to a QCOW2 file (file address in the target OBS bucket: ims-image:centos7_5.qcow2)

1
2
3
4
5
6
 
POST https://{Endpoint}/v1/cloudimages/d164b5df-1bc3-4c3f-893e-3e471fd16e64/file
{
   "bucket_url": "ims-image:centos7_5.qcow2",
   "file_format": "qcow2",
   "is_quick_export": false
}

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 about the returned error code, see Error Codes.

    401 Unauthorized

    Authentication failed.

    403 Forbidden

    Insufficient permissions.

    404 Not Found

    Requested resource not found.

    500 Internal Server Error

    Internal service error.

    503 Service Unavailable

    Service unavailable.
Parent topic: Image