Create a CDS disk
Updated at：2025-10-20
- This API is used to create a CDS disk, supporting creation from a snapshot. However, system disk snapshots cannot be used for creating CDS disks.
- In the request parameters, you must specify either cdsSizeInGB to define the disk size or snapshotId to create a disk from a snapshot.
- If the snapshotId parameter exists and is not empty: If cdsSizeInGB is not specified, the CDS disk will default to the snapshot size. If cdsSizeInGB is specified, it cannot be smaller than the snapshot size.
- The creation API is asynchronous. The disk status can be queried through the [Query Disk Details](BCC/API Reference/Disk Related Interfaces/Query disk details.md) API
- When a prepaid CDS is mounted to a BCC instance with auto-renewal enabled, the CDS disk will automatically enable auto-renewal
Request structure
Plain Text
1POST /v{version}/volume?clientToken={clientToken} HTTP/1.1
2Host: bcc.bj.baidubce.com
3Authorization: authorization string
4{
5 "storageType": storageType,
6 "cdsSizeInGB" : cdsSizeInGB,
7 "snapshotId": snapshotId,
8 "purchaseCount" : purchaseCount,
9 "name": name,
10 "description": description,
11 "instanceId": "instanceId",
12 "encryptKey": encryptKey,
13 "renewTimeUnit": "renewTimeUnit",
14 "renewTime": renewTime,
15 "relationTag": relationTag,
16 "chargeType" : chargeType,
17 "deleteWithInstance" : deleteWithInstance
18 "zoneName": "zoneName",
19 "tags": [
20 {
21 "tagKey": "tagKey",
22 "tagValue": "tagValue"
23 }
24 ],
25 "resGroupId": "groupId",
26 "clusterId": "clusterId",
27 "autoSnapshotPolicy": {
28 "autoSnapshotPolicyId": "autoSnapshotPolicyId"
29 },
30 "billing":{
31 "paymentTiming":paymentTiming,
32 "reservation":{
33 "reservationLength":reservationLength,
34 "reservationTimeUnit":reservationTimeUnit
35 }
36 }
37}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). |
| purchaseCount | int | No | RequestBody | The number of CDS disks to create in bulk must be a positive integer greater than 0, with a maximum of 5 disks per operation. This is an optional parameter; the default value is 1. |
| name | String | No | RequestBody | The new disk name or custom image name supports uppercase and lowercase letters, numbers, Chinese characters, and special characters (-_/). It must begin with a letter and be 1-65 characters in length. |
| description | String | No | RequestBody | New description of the disk |
| cdsSizeInGB | int | No | RequestBody | CDS disk capacity must be a positive integer greater than 0, measured in GB, with a range of 5-32765 GB. For SSD-type cloud disk servers, the minimum starting capacity is 50 GB. This parameter is mandatory when the snapshotId parameter is empty or non-existent. |
| storageType | [StorageType](BCC/API Reference/Appendix.md#StorageType) | No | RequestBody | The CDS disk storage class includes four categories: enhanced_ssd_pl1 [Enhanced SSD_PL1], enhanced_ssd_pl2 [Enhanced SSD_PL2], cloud_hp1 or premium_ssd [General Purpose SSD], and hp1 or ssd [High-Performance Cloud Disk Server]. The default type is hp1. |
| chargeType | String | No | RequestBody | Billing type (payment method) includes prepay and postpay. This parameter is necessary only when instanceId is specified and the corresponding instance requires prepaid billing. If instanceId is not specified, a postpaid CDS is created by default. If instanceId is specified: For prepaid instances, the billing type must be explicitly defined. For postpaid instances, a postpaid CDS is automatically created. |
| snapshotId | String | No | RequestBody | Snapshot ID: Supports disk creation from a snapshot. When this parameter is present and not empty, the cdsSizeInGB parameter will be ignored and is not required. |
| zoneName | String | No | RequestBody | Specified availability zone: By default, this field is empty, and the system will automatically select the zone. |
| autoSnapshotPolicy | List<[AutoSnapshotPolicyModel](BCC/API Reference/Appendix.md#AutoSnapshotPolicyModel)> | No | RequestBody | Current automatic snapshot policy configured for the disk |
| renewTimeUnit | String | No | RequestBody | Monthly or yearly payment. "month" for monthly, "year" for yearly.Note: This parameter is deprecated. When creating a prepaid CDS and mounting it to a BCC with auto-renewal enabled, the CDS disk will automatically enable auto-renewal, and the renewal period will be consistent with that of the BCC instance. |
| renewTime | int | No | RequestBody | Auto-renewal period: 1-9 for monthly renewal, 1-3 for yearly renewal.Note: This parameter is deprecated. When creating a prepaid CDS and mounting it to a BCC with auto-renewal enabled, the CDS disk will automatically enable auto-renewal, and the renewal period will be consistent with that of the BCC instance. |
| instanceId | String | No | RequestBody | Create the disk and attach it to this virtual machine. A prepaid CDS must be linked to a prepaid BCC. Note: When a prepaid CDS is created and attached to a BCC with auto-renewal enabled, the CDS disk will automatically enable auto-renewal, with the renewal period matching that of the BCC instance. |
| encryptKey | String | No | RequestBody | KMS Key ID. |
| relationTag | boolean | No | RequestBody | Specify whether the new CDS tag should be associated with an existing tag key; the default value is false. Note: If set to true, ensure that the tag key already exists. |
| tags | List<[TagModel](BCC/API Reference/Appendix.md#TagModel)> | No | RequestBody | List of tags to be bound |
| clusterId | String | No | RequestBody | CDS dedicated cluster ID |
| resGroupId | String | No | RequestBody | Resource group ID |
| deleteWithInstance | boolean | No | RequestBody | Disk is deleted with instance, effective for Pay-As-You-Go, defaulting to false. V2 API requires setting the cdsAttributeActive parameter to true when releasing an instance for taking effect. |
| billing | [Billing](BCC/API Reference/Appendix.md#Billing) | No | RequestBody | Define the purchase duration when creating a prepaid disk; by default, it matches the BCC's expiration time. The prepaid disk's expiration time must be greater than or equal to that of the BCC. |
Response headers
No special headers are required beyond the standard ones.
Response parameters
| Parameter name | Types | Description |
|---|---|---|
| volumeIds | Disk ID, adhering to BCE specifications. It is a fixed-length string allowing only uppercase and lowercase letters, numbers, hyphens (-), and underscores (_). | |
| warningList | Warning information generated when attaching the disk |
Error codes
| Error code | Error description | HTTP status code | Chinese explanation |
|---|---|---|---|
| Volume.SystemSnapshotForbiddenOperation | System snapshot can not be used to create volume. | 403 | System snapshots are not allowed to create disks |
Request example
Plain Text
1POST http://bcc.bj.baidubce.com/v2/volume?clientToken=3A8d84403d-a94b-40ce-9d6a-f6225dd26676
2Host: bcc.bj.baidubce.com
3Authorization: bce-auth-v1/f81d3b34e48048fbb2634dc7882d7e21/2015-08-11T04:17:29Z/3600/host/74c506f68c65e26c633bfa104c863fffac5190fdec1ec24b7c03eb5d67d2e1de
4
5{
6 "storageType": "hp1",
7 "cdsSizeInGB" : 5,
8 "purchaseCount" : 2,
9 "name": "TestName2",
10 "description": "TestDesc2",
11 "chargeType": "Postpaid"
12}Response example
Plain Text
1HTTP/1.1 200 OK
2Content-Type: application/json;charset=UTF-8
3Date: Wed, 08 Jul 2015 03:28:11 GMT
4x-bce-request-id: d8752367-38e8-45e4-b4c7-e53be3137ce5
5Server: BWS
6
7{
8 "volumeIds": [
9 "v-NSuv0ssl",
10 "v-MPO0YONO"
11 ],
12 "warningList": [
13 "warning info"
14 ]
15}