> For the complete documentation index, see [llms.txt](https://docs.console.zenlayer.com/api-reference/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.console.zenlayer.com/api-reference/compute/zec/instance/createzecinstances.md).
# CreateZecInstances
## 1. API Description
This API (CreateZecInstances) is used to create one or more elastic compute instances with specified configurations.
#### Prerequisites
* Query VM instance types: call [`DescribeZoneInstanceConfigInfos`](/api-reference/compute/zec/instance/describezoneinstanceconfiginfos.md) to query instance type information.
* Query GPU instance types: call [`DescribeZoneGpuInstanceConfigInfos`](/api-reference/compute/zec/instance/describezonegpuinstanceconfiginfos.md) to query GPU instance type information.
* Query images: call [`DescribeImages`](/api-reference/compute/zec/image/describeimages.md) to query image information.
* Query key pairs: call [`DescribeKeyPairs`](/api-reference/security/ccs/key-pair/describekeypairs.md) to query key pair ID information.
{% hint style="info" %}
**Notes**
* The instance will start automatically upon successful creation, and the instance status will change to `RUNNING`. If creation fails, the status will change to `CREATE_FAILED`.
* Ensure the account is in normal status before purchasing.
* Creating instances via this API supports automatic voucher deduction. For details, refer to the voucher selection rules.
* This is an asynchronous API. A list of instance IDs will be returned immediately after the request is successfully submitted, but the operation is not yet complete. During this period, the instance status will be `DEPLOYING`. You can query the creation result by calling [`DescribeInstances`](/api-reference/compute/zec/instance/describeinstances.md). If the instance status changes from `DEPLOYING` to `RUNNING`, the creation was successful; if it changes to `CREATE_FAILED`, the creation failed. No operations can be performed on the instance during the creation process.
* A maximum of **100** instances can be created at a time.
* The size of the guaranteed traffic package is only valid for billing periods of one month.
{% endhint %}
## 2. Input Parameters
The following request parameter list only provides API request parameters.
| Parameter Name | Required | Type | Description |
| ----------------------- | -------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| zoneId | Yes | String | Availability zone ID. |
| imageId | Yes | String | Valid image ID.
To obtain valid image ID, you can call DescribeImages , and find imageId in the response.
|
| instanceType | Yes | String | Instance type. For VM instances, the value can be obtained through [DescribeZoneInstanceConfigInfos](/api-reference/compute/zec/instance/describezoneinstanceconfiginfos.md). For GPU instances, the value can be obtained through [DescribeZoneGpuInstanceConfigInfos](/api-reference/compute/zec/instance/describezonegpuinstanceconfiginfos.md). |
| instanceCount | Yes | Integer | The number of instances to be purchased.
Value range: \[1,100].
Default value: 1.
Value range: \[1, 100]
Default value: 1
|
| subnetId | Yes | String | Subnet ID.
If you need to configure public IP, please ensure your subnet is public network accessible. Subnets only with IPv6 private network access type are not supported.
|
| timeZone | No | String | Time zone of instance.
Default value: America/Los\_Angeles .
|
| instanceName | No | String | Instance name to be displayed.
Default value: instance.
This parameter must start with a number or a letter, containing 2 to 63 characters. Only letters, numbers, - and periods (.) are supported.
If you purchase multiple instances at the same time, you can specify a pattern string \[begin\_number,bits] .
begin\_number : the starting value of an ordered number, value range: \[0,99999], default value: 0.
bits : the number of digits occupied by an ordered value, value range: \[1,6], default value: 6.
For example, if you purchase 1 instance and the instance name body is server\_\[3,3] , the instance name will be server003 ; if you purchase 2 instances, the instance names will be server003 , server004 .
Note:
Spaces are not supported in the pattern string. Multiple pattern strings are supported, such as server\_\[3,3]\_\[1,1] .
|
| password | No | String | Instance password.
The parameter must be 8-16 characters, including:
lowercase letters: \[a-z] uppercase letters: \[A-Z] digits: 0-9 special characters: \`\~!@$^\*-\_=+
|
| keyId | No | String | SSH key pair ID. For example: key-YWD2QFOl .
Your SSH key pair contains several public keys that can be placed on your server. You can access your instance with the private key. Call DescribeKeyPairs to obtain key pair information.
You can set either a password or a keyId , but not both; Windows and Generic images support neither option.
|
| nicNetworkType | No | [NicNetworkType](/api-reference/compute/zec/datastructure.md#nicnetworktype) | Network interface mode.
Default value: Auto .
Default value: Auto
|
| systemDisk | No | [SystemDisk](/api-reference/compute/zec/datastructure.md#systemdisk) | Boot disk configuration.
If the value is empty, the boot disk size is the minimum default value to store the operating system.
|
| dataDisks | No | Array of [DataDisk](/api-reference/compute/zec/datastructure.md#datadisk) | Data disk configuration for the instance. If not specified, no data disk is purchased by default. Each item in the list corresponds to one independent data disk. The total number of data disks is subject to the team quota. |
| securityGroupId | No | String | ID of the security group deployed on the primary vNIC.
Currently only one security group can be deployed.
If not specified, the security group associated with global VPC will be used by default.
|
| lanIp | No | String | Private IP. If the specified IP is occupied, a default private IP will be allocated. |
| enableAgent | No | Boolean | Whether to enable QEMU Guest Agent (QGA). QGA is enabled by default.
Default value: true
|
| enableIpForward | No | Boolean | Whether to enable IP forwarding. IP forwarding is disabled by default.
Default value: false
|
| internetChargeType | No | [InternetChargeType](/api-reference/compute/zec/datastructure.md#internetchargetype) | Public network pricing model. |
| trafficPackageSize | No | Float | The size of the data transfer package to order.
Unit: TB.
This value only takes effect when internetChargeType = ByTrafficPackage.
When IpStackType = IPv4\_IPv6, the data transfer package size applies to IPv4.
Value range: \[0.0, +)
|
| bandwidth | No | Integer | Public outbound bandwidth cap.
Unit: Mbps .
Bandwidth cap varies by instance size.
Value range: \[1, +)
|
| eipBindType | No | [BindType](/api-reference/compute/zec/datastructure.md#bindtype) | Elastic IP mode. If not specified, the default is Full NAT mode.
Default value: FullNat .
Default value: FullNat
|
| eipIds | No | Array of String | Assign the existing EIPs to the instances.
The number of IPs must be the same as the number of created instances.
If this field is specified, no new EIPs will be created and the related fields will be invalid (networkLineType).
Ensure that the created network card ipStackType includes IPv4.
|
| eipV4Type \[Deprecated] | No | [EipNetworkType](/api-reference/compute/zec/datastructure.md#eipnetworktype) | Network type of public IPv4.
If you need to specify the value, please ensure that your subnet supports IPv4 stack type.
If the subnet IP stack type is IPv4, the value is required.
ThreeLine are not supported for now.
Deprecated. Please use networkLineType instead.
|
| ipStackType | No | [SubnetStackType](/api-reference/compute/zec/datastructure.md#subnetstacktype) | Set the IP stack type.
If not specified, IPv4 is used by default when the subnet stack type is IPv4 or IPv4\_IPv6.
|
| networkLineType | No | [NetworkLineType](/api-reference/compute/zec/datastructure.md#networklinetype) | Network type of public IPv4.
If you need to specify the value, please ensure that your subnet supports IPv4 stack type.
If the subnet IP stack type is IPv4, the value is required.
ThreeLine are not supported for now.
|
| clusterId | No | String | Bandwidth cluster ID.
This parameter is required when the network billing model is BandwidthCluster.
|
| ipv6ClusterId | No | String | Bandwidth cluster ID of the public IPv6 address.
Required when the network billing model is BandwidthCluster and ipStackType is IPv4\_IPv6.
If not specified, clusterId is used by default.
This field is typically used when IPv4 and IPv6 belong to different bandwidth clusters.
|
| resourceGroupId | No | String | Resource group ID where the instances reside.
If the value is empty, the instance will be added into the default resource group.
|
| marketingOptions | No | [MarketingInfo](/api-reference/compute/zec/datastructure.md#marketinginfo) | Information on marketing campaigns. |
| tags | No | [TagAssociation](/api-reference/compute/zec/datastructure.md#tagassociation) | Bound tags when creating resources.
Tag keys must be unique.
|
| userData | No | String | Initialization command. |
| instanceOptions | No | [InstanceOptions](/api-reference/compute/zec/datastructure.md#instanceoptions) | Instance options configuration. |
## 3. Output Parameters
| Parameter Name | Type | Description |
| -------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| requestId | String | The unique request ID, which is returned for each request.
RequestId is required for locating a problem.
|
| orderNumber | String | Number of order. |
| instanceIdSet | Array of String | List of instance IDs.
The returned instance ID list does not mean the creation has been completed.uery the status of the instance according to dataSet . If the status changes from DEPLOYING to RUNNING , it means that the instance has been created successfully; CREATE\_FAILED or no instance found means the instance has been created failed.
|
| instances | Array of [DiskWithInstance](/api-reference/compute/zec/datastructure.md#diskwithinstance) | Set of disk IDs created along with the instances. If no disk is specified, the value is empty. |
## 4. Code Example
{% tabs %} {% tab title="Example" %}
1. **Create an instance with the simplest parameters with no public IPv4 assigned.**
```json
POST /api/v2/zec HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateZecInstances
Request：
{
"zoneId": "asia-east-1a",
"instanceType": "z2a.cpu.1",
"imageId": "ubuntu2404_20240712",
"instanceName": "Test-InstanceName",
"keyId": "key-rcfljdP5",
"subnetId": "1272168087751233112",
"nicNetworkType": "Auto",
"tags":
{
"tags": [
{
"key": "key1",
"value": "value1"
},
{
"key": "key2",
"value": "value2"
}
]
}
}
Response:
{
"requestId": "TA471524B-84E1-467B-AB77-75387BBD190B",
"response": {
"requestId": "TA471524B-84E1-467B-AB77-75387BBD190B",
"instanceIdSet": [
""
],
"instances": [
],
"orderNumber": ""
}
}
```
2. **Create 2 instances with public IPs, using BGP lines and bandwidth cluster billing, limited to `10` Mbps.**
```json
POST /api/v2/zec HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateZecInstances
Request：
{
"zoneId": "asia-east-1a",
"instanceType": "z2a.cpu.1",
"imageId": "ubuntu2404_20240712",
"instanceName": "Test-InstanceName",
"keyId": "key-rcfljdP5",
"subnetId": "1272168087751233112",
"internetChargeType": "BandwidthCluster",
"bandwidth": 10,
"clusterId": "",
"eipV4Type": "BGPLine"
}
Response:
{
"requestId": "TA471524B-84E1-467B-AB77-75387BBD190B",
"response": {
"requestId": "TA471524B-84E1-467B-AB77-75387BBD190B",
"instanceIdSet": [
""
],
"instances": [
],
"orderNumber": ""
}
}
```
4. **Create an instance configured with multiple data disks.**
```json
POST /api/v2/zec HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateZecInstances
Request：
{
"zoneId": "asia-east-1a",
"instanceType": "z2a.cpu.1",
"imageId": "ubuntu2404_20240712",
"instanceName": "Test-InstanceName",
"keyId": "key-rcfljdP5",
"subnetId": "1272168087751233112",
"nicNetworkType": "Auto",
"dataDisks": [
{
"diskSize": 100,
"diskCategory": "Standard NVMe SSD"
},
{
"diskSize": 200,
"diskCategory": "Standard NVMe SSD"
}
]
}
Response:
{
"requestId": "TA471524B-84E1-467B-AB77-75387BBD190B",
"response": {
"requestId": "TA471524B-84E1-467B-AB77-75387BBD190B",
"instanceIdSet": [
""
],
"instances": [
],
"orderNumber": ""
}
}
```
## 5. Developer Resources
Zenlayer Cloud API 2.0 integrates [SDKs](/api-reference/api-introduction/toolkit/api-sdk.md)，to make it easier for you to call APIs. More programming languages will be supported.
## 6. Error Codes
The following only lists the error codes related to the API business logic. For other error codes, see [Common Error Codes](/api-reference/api-introduction/instruction/commonerrorcode.md).
| HTTP Status Code | Error Code | Description |
| ---------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| 400 | INVALID\_DISK\_CATEGORY\_TYPE | Disk type error. |
| 404 | INVALID\_EIP\_NOT\_FOUND | Elastic IP does not exist. |
| 404 | INVALID\_GPU\_INSTANCE\_TYPE\_NOT\_FOUND | GPU instance type does not exist. |
| 400 | INVALID\_IMAGE\_AGENT\_NOT\_SUPPORT | QGA is not supported for the selected image. |
| 400 | INVALID\_IMAGE\_IPV6\_NOT\_SUPPORT | IPv6 stack type is not supported for the selected image. |
| 400 | INVALID\_IMAGE\_KEY\_PAIR\_NOT\_SUPPORT | The image does not support SSH key pairs. |
| 404 | INVALID\_IMAGE\_NOT\_FOUND | Image not found. |
| 400 | INVALID\_IMAGE\_PASSWORD\_NOT\_SUPPORT | The operating system does not support the specified password. |
| 400 | INVALID\_IMAGE\_SIZE\_EXCEED | Boot disk size should be larger than the image size. |
| 400 | INVALID\_IMAGE\_SPEC\_NOT\_SUPPORT | The minimum specification required by the image exceeds the current instance type. |
| 400 | INVALID\_INSTANCE\_COUNT\_LIMITATION | You are trying to create more instances than your remaining quota allows. |
| 404 | INVALID\_INSTANCE\_TYPE\_NOT\_FOUND | Instance type not found. |
| 400 | INVALID\_IP\_BROADCAST\_ADDRESS | The IP address cannot be a broadcast address. |
| 400 | INVALID\_IP\_FIRST\_ADDRESS | The IP address cannot be a gateway address. |
| 400 | INVALID\_IP\_NETWORK\_ADDRESS | The IP address cannot be a network address. |
| 400 | INVALID\_IP\_OUT\_OF\_RANGE | Invalid IP address. It does not belong to the CIDR block. |
| 404 | INVALID\_KEY\_PAIR\_NOT\_FOUND | SSH key pair does not exist. |
| 400 | INVALID\_LOGIN\_SETTING\_CONFLICT | You must and can only pass the value of either password or keyId . |
| 409 | INVALID\_NIC\_INSTANCE\_REGION\_MISMATCH | Instance and vNIC are not in the same zone. |
| 400 | INVALID\_PARAMETER\_INSTANCE\_NAME\_EXCEED | Instance name exceeds the maximum limit. |
| 400 | INVALID\_PARAMETER\_INSTANCE\_NAME\_EXCEED\_MINIMUM\_LENGTH | Instance name should be larger than the minimum limit. |
| 400 | INVALID\_PARAMETER\_INSTANCE\_NAME\_MALFORMED | Invalid instance name format. |
| 400 | INVALID\_PARAMETER\_USER\_DATA\_EXCEED | Initialization command exceeds length limit. |
| 404 | INVALID\_PASSWORD\_KEY\_PAIR\_MISSING | Neither password nor SSH key pair is specified. |
| 400 | INVALID\_PASSWORD\_MALFORMED | Password format error. |
| 404 | INVALID\_REGION\_NOT\_FOUND | Specified availability zone does not exist. |
| 400 | INVALID\_REGION\_ZONE\_MISMATCH | The specified availability zone is not under the specified region. |
| 404 | INVALID\_SECURITY\_GROUP\_NOT\_FOUND | The specified security group does not exist. |
| 409 | INVALID\_SUBNET\_IPV4\_INSUFFICIENT | Insufficient available IPv4 addresses in the subnet. |
| 409 | INVALID\_SUBNET\_IPV6\_INSUFFICIENT | Insufficient available IPv6 addresses in the subnet. |
| 404 | INVALID\_SUBNET\_NOT\_FOUND | Subnet does not exist. |
| 400 | INVALID\_SYSTEM\_DISK\_EXCEED\_LIMIT | Boot disk size exceeds the limit. |
| 404 | INVALID\_ZONE\_NOT\_FOUND | Region does not exist. |
| 400 | OPERATION\_DENIED\_CPU\_ILLEGAL | The number of CPUs in the specification is invalid. |
| 400 | OPERATION\_DENIED\_DISK\_IO\_BURST | The disk bursting function is not enabled. |
| 400 | OPERATION\_DENIED\_EIP\_INSTANCE\_NOT\_ADAPTER | Specified instance count does not match the number of elastic IPs to be created. |
| 400 | OPERATION\_DENIED\_EIP\_INSUFFICIENT | Insufficient elastic IP stock. |
| 400 | OPERATION\_DENIED\_EIP\_IS\_DEFAULT | Default public IP cannot be unbound. |
| 400 | OPERATION\_DENIED\_EIP\_IS\_NOT\_UN\_ASSIGN | Elastic IP is not in unassigned state. |
| 400 | OPERATION\_DENIED\_EIP\_NOT\_ASSIGNED | Elastic IP is not bound. |
| 400 | OPERATION\_DENIED\_EIP\_QUOTA\_LIMIT\_EXCEEDED | The number of elastic IPs exceeds the quota limit. |
| 400 | OPERATION\_DENIED\_EIP\_UNSUPPORTED\_NETWORK\_TYPE | The EIP network billing method is not supported. |
| 400 | OPERATION\_DENIED\_MEMORY\_AMOUNT\_ILLEGAL | The memory size in the specification is invalid. |
| 400 | OPERATION\_DENIED\_NIC\_NETWORK\_TYPE\_NOT\_SUPPORT | Network interface mode not supported. |
| 400 | OPERATION\_DENIED\_STACK\_TYPE\_NOT\_SUPPORT | Stack type is not supported. |
| 400 | OPERATION\_DENIED\_SUBNET\_TYPE\_NOT\_SUPPORT | Operations on subnets with such IP stack type is not supported. |
| 400 | OPERATION\_DENIED\_SUBNET\_TYPE\_NOT\_SUPPORT\_IPV4 | Subnet type does not support IPv4. |
| 400 | OPERATION\_DENIED\_SUBNET\_ZONE\_MISMATCH | Subnet the instance added in is not in the current zone. |
| 400 | INSTANCE\_STOCK\_INSUFFICIENT | Insufficient instance stock. |
| 400 | UNSUPPORTED\_SUBNET\_TYPE\_FOR\_INTERNET\_CHARGE\_TYPE | The subnet stack type does not support public network. |
| 400 | INVALID\_IP\_STACK\_TYPE\_NOT\_SUPPORT | IP stack type is not supported. |
| 400 | INVALID\_NESTED\_VIRTUALIZATION\_NOT\_ALLOWED | Nested virtualization is not allowed. |
| 400 | INVALID\_PARAMETER\_FLOW\_PACKAGE\_NOT\_SUPPORTED\_FOR\_PATH\_BASED | PathBasedBandwidthIP does not support custom traffic package sizes. Pass 0 or omit this parameter. |
| 400 | OPERATION\_DENIED\_FIXED\_BANDWIDTH\_NOT\_SUPPORTED\_FOR\_PATH\_BASED | PathBasedBandwidthIP does not support fixed bandwidth billing. |
| 400 | OPERATION\_DENIED\_INTERNET\_CHARGE\_TYPE\_NOT\_SUPPORT | IP network billing type is not supported. |
| 409 | INVALID\_INSTANCE\_EIP\_REGION\_MISMATCH | The instance and EIP are not on the same region. |
| 400 | OPERATION\_DENIED\_FLOW\_PACKAGE\_NOT\_SUPPORTED\_HOUR\_PERIOD | The current product cycle is based on hourly billing and does not support setting a minimum data package size. |