Creating an Image (New)

Function

This API is used to create a private image. The following methods are supported:

• Create a system or data disk image from an ECS.
• Create a system disk image from an external image file uploaded to an OBS bucket.
• Create a system disk image from a data disk.

This is an asynchronous API. A successful call only means the cloud platform has received the request. To see if an image is created successfully, you need to use the asynchronous job query API to query the image creation status. For details, see Querying the Progress of an Asynchronous Job.

Constraints

• To create an encrypted image, you must have permissions for KMS actions.
• Creating a private image using an external image file

  For details about constraints on image files, see Preparing an Image File.

• Creating a system disk image using a data disk

  Before using a data disk to create a system disk image, you need to initialize the source VM to ensure the image availability. For details, see Preparations for Creating a Private Image.

  The system cannot verify that an OS has been installed on the data disk. Therefore, ensure that the value of os_version is valid when creating a system disk image from the data disk. For details, see Values of Related Parameters.

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 /v2.1/cloudimages/action

Request

• Parameters for creating a system or data disk image from an ECS

  Parameter	Mandatory	Type	Description
  name	No	String	Definition System disk image name. For details about name, see Image Attributes. NOTICE: This parameter is mandatory when you use a cloud server to create a system disk image. 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
  instance_id	No	String	Definition ID of an ECS used to create an image. To obtain the ECS ID, perform the following operations: Log in to the ECS console. In the ECS list, click the name of the ECS and view its ID. Constraints This parameter is mandatory when you use a cloud server to create a system disk image. Range N/A Default Value N/A
  data_images	No	Array of objects	Definition Data disk details. This parameter is mandatory when the data disk of an ECS is used to create a private data disk image. For details, see Table 1. Constraints When you create a data disk image from a data disk, attribute values in data_images take priority over those set by other parameters (such as name, description, and tags). In this case, you cannot specify instance_id. Range N/A Default Value If you are not creating a data disk image, this parameter is left blank by default.
  tags	No	Array of strings	Definition Image tags. Constraints Use either tags or image_tags. Range A tag key can contain letters, digits, spaces, underscores (_), periods (.), colons (:), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space or start with sys_. A tag value can contain letters, digits, spaces, underscores (_), periods (.), colons (:), slashes (/), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space. Default Value N/A
  image_tags	No	Array of objects	Definition Image tags (new format). For details about image_tags, see Table 3. Constraints Use either tags or image_tags. Range A tag key can contain letters, digits, spaces, underscores (_), periods (.), colons (:), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space or start with sys_. A tag value can contain letters, digits, spaces, underscores (_), periods (.), colons (:), slashes (/), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space. Default Value N/A
  enterprise_project_id	No	String	Definition Enterprise project that an image belongs to. For more information about enterprise projects and how to obtain enterprise project IDs, see Enterprise Center. Constraints If only enterprise project authorization is used, the enterprise_project_id parameter must be specified. Otherwise, an error may occur, indicating that you do not have the required permissions. Range If the value is 0 or left blank, the image belongs to the default enterprise project. If the value is a UUID, the image belongs to the enterprise project corresponding to the UUID. Default Value N/A
  max_ram	No	Integer	Definition Maximum memory (MB) supported by an image. Constraints The value must be greater than or equal to min_ram. Range An integer greater than 0 Default Value N/A
  min_ram	No	Integer	Definition Minimum memory (MB) supported by an image. Constraints N/A Range An integer greater than 0 Default Value The default value is 0, which means no limit.

  Table 1 Data structure description of the data_images field

  Parameter	Mandatory	Type	Description
  name	Yes	String	Definition Data disk image name. 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
  volume_id	Yes	String	Definition Data disk ID. Constraints N/A Range N/A Default Value N/A
  description	No	String	Definition Data disk description. 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
  tags	No	Array of strings	Definition Data disk image tags. Constraints Use either tags or image_tags. Range A tag key can contain letters, digits, spaces, underscores (_), periods (.), colons (:), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space or start with sys_. A tag value can contain letters, digits, spaces, underscores (_), periods (.), colons (:), slashes (/), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space. Default Value N/A

• Parameters for creating an image using an image file uploaded to the OBS bucket

  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
  os_type	No	String	Definition OS type. Constraints N/A Range The value can be Linux, Windows, or Other. Default Value N/A
  os_version	No	String	Definition OS version. Constraints If an ISO file is uploaded, this parameter is mandatory. If is_quick_import is true, a system disk image is imported using fast import. In this case, this parameter is mandatory. Range This parameter is valid if an external image file uploaded to the OBS bucket is used to create an image. For its value, see Values of Related Parameters. Default Value N/A
  license_type	No	String	Definition OS license type. Constraints Currently, this parameter is only available for Windows. Range platform: license provided by Huawei Cloud byol: Bring Your Own License Default Value N/A
  image_url	Yes	String	Definition URL of the external image file in an OBS bucket. This parameter is mandatory if an external image file in the OBS bucket is used to create an image. The format is <OBS bucket name>:<Image file name>. To obtain an OBS bucket name: Log in to the OBS console. All OBS buckets are displayed in the list. Filter the OBS buckets by region and locate the target bucket in the current region. To obtain an OBS image file name: Log in to the OBS console. All OBS buckets are displayed in the list. Filter the OBS buckets by region and locate the target bucket in the current region. Click the name of the target bucket to go to the bucket details page. In the navigation pane on the left, choose Objects to display objects in the OBS bucket and then locate the external image file used to create an image. Constraints The storage class of the OBS bucket and image files in it must be Standard. Range N/A Default Value N/A
  min_disk	Yes	Integer	Definition Minimum size of a system disk. This parameter is mandatory if an external image file in an OBS bucket is used to create an image. Constraints N/A Range For Linux, the value ranges from 10 GB to 1024 GB. For Windows, the value ranges from 20 GB to 1024 GB. Default Value N/A
  is_config	No	Boolean	Definition Whether to enable automatic configuration. For details about automatic configuration, see Registering an Image File as a Private Image. Constraints N/A Range The value can be true or false. If automatic configuration is required, set the value to true. Otherwise, set it to false. Default Value The default value is false.
  cmk_id	No	String	Definition Custom key used to encrypt an image. Constraints N/A Range For details, see Viewing Key Details. Default Value N/A
  tags	No	Array of strings	Definition Lists the image tags. Constraints Use either tags or image_tags. Range A tag key can contain letters, digits, spaces, underscores (_), periods (.), colons (:), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space or start with sys_. A tag value can contain letters, digits, spaces, underscores (_), periods (.), colons (:), slashes (/), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space. Default Value N/A
  image_tags	No	Array of objects	Definition Lists the image tags. For details about image_tags, see Table 3. Constraints Use either tags or image_tags. Range A tag key can contain letters, digits, spaces, underscores (_), periods (.), colons (:), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space or start with sys_. A tag value can contain letters, digits, spaces, underscores (_), periods (.), colons (:), slashes (/), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space. Default Value N/A
  enterprise_project_id	No	String	Definition Enterprise project that an image belongs to. For more information about enterprise projects and how to obtain enterprise project IDs, see Enterprise Center. Constraints If only enterprise project authorization is used, the enterprise_project_id parameter must be specified. Otherwise, an error may occur, indicating that you do not have the required permissions. Range If the value is 0 or left blank, the image belongs to the default enterprise project. If the value is a UUID, the image belongs to the enterprise project corresponding to the UUID. Default Value N/A
  max_ram	No	Integer	Definition Maximum memory (MB) supported by an image. Constraints The value must be greater than or equal to min_ram. Range An integer greater than 0 Default Value N/A
  min_ram	No	Integer	Definition Minimum memory (MB) required by an image. Constraints N/A Range An integer greater than 0 Default Value The default value is 0, which means no limit.
  data_images	No	Array of objects	Definition Information about a data disk to be imported. For details, see Table 2. An external image file can contain a maximum of three data disks. In this case, one system disk and three data disks will be created. Constraints An external image file can contain a maximum of three data disks. In this case, one system disk and three data disks will be created. When you use a data disk image file to create a data disk image, the OS type of the data disk image will be the same as that of the system disk image. Attribute values in data_images take priority over those set by other parameters (such as name, description, and tags). Range N/A Default Value N/A
  is_quick_import	No	Boolean	Definition Whether to use fast import to import a system disk image. Constraints For details about constraints on fast image file import, see Importing an Image File Quickly. Range If yes, set the value to true. If no, set the value to false. Default Value N/A
  architecture	No	String	Definition Image architecture. Constraints If the architecture is Arm, the boot mode is automatically changed to UEFI. Range x86 arm Default Value The default value is x86.
  hw_firmware_type	No	String	Definition ECS boot mode. Constraints If the image architecture is Arm, only the UEFI boot mode is supported. Range bios indicates the BIOS boot mode. uefi indicates the UEFI boot mode. Default Value N/A

  Table 2 Data structure description of the data_images field

  Parameter	Mandatory	Type	Description
  name	No	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
  image_url	Yes	String	Definition URL of the external image file in an OBS bucket. This parameter is mandatory if an external image file in an OBS bucket is used to create an image. The format is <OBS-bucket-name>:<image-file-name>. To obtain an OBS bucket name: Log in to the OBS console. All OBS buckets are listed. Filter the OBS buckets by region and locate the target bucket in the current region. To obtain an OBS image file name: Log in to the OBS console. All OBS buckets are listed. Filter the OBS buckets by region and locate the target bucket in the current region. Click the bucket name to go to its details page. In the navigation pane on the left, choose Objects to display objects in the OBS bucket and then locate the external image file used to create an image. Constraints The storage class of the OBS bucket and image files in it must be Standard. Range N/A Default Value N/A
  min_disk	Yes	Integer	Definition Minimum data disk size. Unit: GB Constraints N/A Range 1~2048GB Default Value N/A
  is_quick_import	No	Boolean	Definition Whether to use fast import to import an image file for data disk image creation. Constraints For details about constraints on fast image file import, see Importing an Image File Quickly. Range If yes, set the value to true. If no, set the value to false. Default Value N/A
  tags	No	Array of strings	Definition Image tags. Constraints Use either tags or image_tags. Range A tag key can contain letters, digits, spaces, underscores (_), periods (.), colons (:), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space or start with sys_. A tag value can contain letters, digits, spaces, underscores (_), periods (.), colons (:), slashes (/), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space. Default Value N/A
  image_tags	No	Array of objects	Definition Lists the image tags. For details about image_tags, see Table 3. Constraints Use either tags or image_tags. Range A tag key can contain letters, digits, spaces, underscores (_), periods (.), colons (:), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space or start with sys_. A tag value can contain letters, digits, spaces, underscores (_), periods (.), colons (:), slashes (/), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space. Default Value N/A

• Parameters for creating a system disk image using a data disk

  Parameter	Mandatory	Type	Description
  name	Yes	String	Definition System disk 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
  volume_id	Yes	String	Definition Data disk ID. Constraints N/A Range N/A Default Value N/A
  os_version	Yes	String	Definition OS version. Constraints During the creation of a system disk image, if the OS can be detected from the disk, the OS version in the disk is used. In this case, the os_version value is invalid. If the OS cannot be detected from the data disk, the os_version value is used. Range Set the value of os_version based on Values of Related Parameters. Otherwise, the created system disk image may be unavailable. Default Value N/A
  type	No	String	Definition Image type. Constraints N/A Range The value can be ECS, BMS, FusionCompute, or Ironic. ECS and FusionCompute: indicates an ECS image. BMS and Ironic: indicates a BMS image. Default Value The default value is ECS.
  description	No	String	Definition Image description. For details, 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
  min_ram	No	Integer	Definition Minimum memory (MB) required for running an image. Constraints N/A Range An integer greater than 0 The value depends on cloud server specifications. Default Value The default value is 0.
  max_ram	No	Integer	Definition Maximum memory (MB) supported by an image. Constraints The value must be greater than or equal to min_ram. Range An integer greater than 0 The value depends on cloud server specifications. Default Value The default value is 0.
  tags	No	Array of strings	Definition Image tags. Constraints Use either tags or image_tags. Range A tag key can contain letters, digits, spaces, underscores (_), periods (.), colons (:), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space or start with sys_. A tag value can contain letters, digits, spaces, underscores (_), periods (.), colons (:), slashes (/), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space. Default Value N/A
  image_tags	No	Array of objects	Definition Lists the image tags. For details about image_tags, see Table 3. Constraints Use either tags or image_tags. Range A tag key can contain letters, digits, spaces, underscores (_), periods (.), colons (:), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space or start with sys_. A tag value can contain letters, digits, spaces, underscores (_), periods (.), colons (:), slashes (/), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space. Default Value N/A
  enterprise_project_id	No	String	Definition Enterprise project that an image belongs to. For more information about enterprise projects and how to obtain enterprise project IDs, see Enterprise Center. Constraints If only enterprise project authorization is used, the enterprise_project_id parameter must be specified. Otherwise, an error may occur, indicating that you do not have the required permissions. Range If the value is 0 or left blank, the image belongs to the default enterprise project. If the value is a UUID, the image belongs to the enterprise project corresponding to the UUID. Default Value N/A

Example Request

• Creating a system disk image with parameter tags using an ECS (ID: 877a2cda-ba63-4e1e-b95f-e67e48b6129a)

  POST https://{Endpoint}/v2.1/cloudimages/action
  {
      "name": "ims_test",
      "description": "Create a system disk image from an ECS",
      "instance_id": "877a2cda-ba63-4e1e-b95f-e67e48b6129a",
      "tags": [
          "aaa.111",
          "bbb.333",
          "ccc.444"
      ]
  }

• Creating a data disk image with parameter tags using a data disk (ID: c5dfbd0c-bf0a-4798-a453-61dc6b54aa30) of an ECS

  1 2 3 4 5 6 7 8 9 10 11 12

  POST https://{Endpoint}/v2.1/cloudimages/action { "data_images": [{"name": "ims_data_image_test", "description": "Create a data disk image from the data disk of an ECS", "volume_id": "c5dfbd0c-bf0a-4798-a453-61dc6b54aa30", "tags": [ "aaa.111", "bbb.333", "ccc.444" ] }] }

• Creating an image with parameter tags using a file in an OBS bucket (file address in the bucket: ims-image:centos70.qcow2)

  1 2 3 4 5 6 7 8 9 10 11 12 13

  POST https://{Endpoint}/v2.1/cloudimages/action { "name": "ims_test_file", "description": "Create an image from a file in an OBS bucket", "image_url": "ims-image:centos70.qcow2", "os_version": "CentOS 7.0 64bit", "min_disk": 40, "tags": [ "aaa.111", "bbb.333", "ccc.444" ] }

• Creating a system disk image with parameter image_tags using an ECS (ID: 877a2cda-ba63-4e1e-b95f-e67e48b6129a)

  POST https://{Endpoint}/v2.1/cloudimages/action
  {
      "name": "ims_test",
      "description": "Create a system disk image from an ECS",
      "instance_id": "877a2cda-ba63-4e1e-b95f-e67e48b6129a",
      "image_tags": [
          {
              "key": "key2",
              "value": "value2"
          },
          {
              "key": "key1",
              "value": "value1"
          }
      ]
  }

• Creating a data disk image with parameter image_tags using a data disk (ID: c5dfbd0c-bf0a-4798-a453-61dc6b54aa30) of an ECS

  1 2 3 4 5 6 7 8

  POST /v2.1/cloudimages/action { "data_images": [{"name": "ims_data_image_test", "description": "Create a data disk image from the data disk of an ECS", "volume_id": "c5dfbd0c-bf0a-4798-a453-61dc6b54aa30", "image_tags": [{"key":"key2","value":"value2"},{"key":"key1","value":"value1"}] }] }

• Creating an image with parameter image_tags using a file in an OBS bucket (file address in the bucket: ims-image:centos70.qcow2)

  1 2 3 4 5 6 7 8 9

  POST https://{Endpoint}/v2.1/cloudimages/action { "name": "ims_test_file", "description": "Create an image from a file in an OBS bucket", "image_url": "ims-image:centos70.qcow2", "os_version": "CentOS 7.0 64bit", "min_disk": 40, "image_tags": [{"key":"key2","value":"value2"},{"key":"key1","value":"value1"}] }

• Creating an image with parameter tags using an ISO file in an OBS bucket (file address in the bucket: ims-image:centos70.iso)

  POST https://{Endpoint}/v2.1/cloudimages/action
  {
      "name": "ims_test_file",
      "min_disk": 40,
      "image_url": "ims-image:centos70.iso",
     "description": "Create an image from an ISO file",
      "type": "IsoImage",
      "os_version": "CentOS 7.0 64bit",
      "tags": ["aaa.111", "bbb.333", "ccc.444"]
  }

• Creating an image with parameter image_tags using an ISO file in an OBS bucket (file address in the bucket: ims-image:centos70.iso)

  POST https://{Endpoint}/v2.1/cloudimages/action
  {
      "name": "ims_test_file",
      "min_disk": 40,
      "image_url": "ims-image:centos70.iso",
     "description": "Create an image from an ISO file",
      "type": "IsoImage",
      "os_version": "CentOS 7.0 64bit",
      "image_tags": [{"key":"key2","value":"value2"},{"key":"key1","value":"value1"}]
  }

• Creating a system disk image with parameter tags using a data disk (ID: 877a2cda-ba63-4e1e-b95f-e67e48b6129a)

  1 2 3 4 5 6 7 8 9 10 11 12 13

  POST https://{Endpoint}/v2.1/cloudimages/action { "name": "ims_test", "description": "Create a system disk image from a data disk", "volume_id": "877a2cda-ba63-4e1e-b95f-e67e48b6129a", "type": "ECS", "os_version": "CentOS 7.0 64bit", "tags": [ "aaa.111", "bbb.333", "ccc.444" ] }

• Creating a system disk image with parameter image_tags using a data disk (ID: 877a2cda-ba63-4e1e-b95f-e67e48b6129a)

  1 2 3 4 5 6 7 8 9

  POST https://{Endpoint}/v2.1/cloudimages/action { "name": "ims_test", "description": "Create a system disk image from a data disk", "volume_id": "877a2cda-ba63-4e1e-b95f-e67e48b6129a", "type": "ECS", "os_version": "CentOS 7.0 64bit", "image_tags": [{"key":"key2","value":"value2"},{"key":"key1","value":"value1"}] }

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": "8a12fc664fb4daa3014fb4e581380005" }

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	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.