Create a custom image
Updated at：2025-10-20
This API allows users to create custom images, which can then be used to create instances. Each user is allowed a maximum of 20 images per region.
- Two methods are supported for creating custom images: via an instance or via a snapshot.
- When creating via an instance, the operation will only succeed if the instance is in either Running or Stopped status; otherwise, a 409 error will occur.
- Custom images can only be generated from system disk snapshots.
- When creating via a snapshot, the operation will only be successful if the snapshot is in Available status; otherwise, a 409 error will occur.
Request structure
Plain Text
1POST /v{version}/image?clientToken={clientToken} HTTP/1.1
2Host: bcc.bj.baidubce.com
3Authorization: authorization string
4
5{
6 "imageName" : imageName,
7 "instanceId" : instanceId,
8 "snapshotId" : snapshotId,
9 "encryptKey": encryptKey,
10 "relateCds": relateCds
11 "detection": detection
12}Request headers
There are no special headers required beyond the common headers.
Request parameters
| Parameter name | Types | Whether required | Parameter location | Description |
|---|---|---|---|---|
| version | String | Yes | URL parameter | API version number |
| clientToken | String | Yes | Query | Idempotence Token, which is an ASCII string with a length not exceeding 64 bits. For details, see the [Idempotence](BCC/API Reference/General Description.md#Idempotence). |
| imageName | String | Yes | Request Body parameters | The name of the custom image to be created can include uppercase and lowercase letters, numbers, Chinese characters, and special characters such as -/_ starting with a letter, with a length of 1-65 characters. |
| instanceId | String | No | Request Body parameters | When creating an image from an instance, this parameter specifies the ID of the instance being used. This is an optional parameter and cannot coexist with snapshotId. If both are provided, only instanceId will be utilized. |
| snapshotId | String | No | Request Body parameters | When creating an image from a snapshot, this parameter specifies the ID of the snapshot being used. This is an optional parameter and cannot coexist with instanceId. If both are provided, only instanceId will be utilized. |
| relateCds | boolean | No | RequestBody | Whether to create a large image containing all CDS disks. If true, the image cannot be encrypted and must be in the allow list |
| encryptKey | String | No | RequestBody | Encrypted key |
| detection | bolean | No | RequestBody | Image detection: If this parameter is not set, no image detection will occur. If set to true, image detection will automatically be conducted once the image is created. If set to false, no detection will occur post-creation. The default value is false. |
Response headers
No special headers are required beyond the standard ones.
Response parameters
| Parameter name | Types | Description |
|---|---|---|
| imageId | String | ID of the created image |
Error codes
| Error code | Error description | HTTP status code | Chinese explanation |
|---|---|---|---|
| Image.ImageNameInvalid | Image name is invalid. | 400 | The image name is incorrect |
| Image.ImageIdIsEmpty | Image ID cannot be empty | 400 | The image ID format cannot be empty |
| Image.ImageQuotaExceedLimit | Image number exceeds the limit. | 413 | Count of images exceeds the limit |
| Image.InstanceStatusForbidden | Instance not in running or stopped status. | 409 | The instance status is not running or stopped. Please confirm and try again |
| Image.SnapshotStatusForbidden | Snapshot status is not Available, please confirm and retry. | 409 | The snapshot status is unavailable. Please confirm and try again |
| Image.NonSystemSnapshotForbidden | Non system snapshot can not used to create image, please confirm and retry. | 403 | Non-system snapshots cannot be used to create images |
Request example
Plain Text
1POST /v2/image?clientToken=1849ef6b-f73c-4f5d-b88b-259ca47af849 HTTP/1.1
2Host: bcc.bj.baidubce.com
3Authorization: bce-auth-v1/f81d3b34e48048fbb2634dc7882d7e21/2015-08-11T04:17:29Z/3600/host/74c506f68c65e26c633bfa104c863fffac5190fdec1ec24b7c03eb5d67d2e1de
4
5{
6 "imageName" : "template_example_001",
7 "instanceId":"i-1849ef6b"
8}Response example
Plain Text
1HTTP/1.1 200 OK
2x-bce-request-id: 1214cca7-4ad5-451d-9215-71cb844c0a50
3Date: Wed, 03 Dec 2014 06:42:19 GMT
4Content-Type: application/json;charset=UTF-8
5Server: BWS
6
7{
8 "imageId" : "m-nky7qeom"
9}