CreateZecInstances

1. API Description

This API (CreateZecInstances) is used to create one or more elastic compute instances with specified configurations.

Prerequisites

Query standard instance types: call DescribeZoneInstanceConfigInfos to query instance type information.
Query GPU instance types: call DescribeZoneGpuInstanceConfigInfos to query GPU instance type information.
Query accelerator instance types: call DescribeZoneAcceleratorConfigInfos to query accelerator instance type information.
Query images: call DescribeImages to query image information.
Query key pairs: call DescribeKeyPairs to query key pair ID information.

Notes

Once an instance is created successfully, it will automatically power on and its status will change to RUNNING. If creation fails, the status will change to CREATE_FAILED.
Ensure your 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 async API. Once the create-instance request is successfully submitted, a list of instance IDs is returned, but the creation is not yet complete at that point. During this period the instance status will be DEPLOYING. You can query the creation result by calling DescribeInstances. If the instance status changes from DEPLOYING to RUNNING, the creation succeeded; if it changes to CREATE_FAILED, the creation failed. No operations can be performed on the instance while creation is in progress.
A maximum of 100 instances can be created in a single request.
The guaranteed traffic package size is only valid for monthly billing periods.
When eipIds is bound to a block-type (CIDR) EIP, eipBindType can only use Passthrough and must be explicitly specified (it cannot be omitted — omitting it is equivalent to FullNat and will be rejected).

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. For GPU instances, the value can be obtained through DescribeZoneGpuInstanceConfigInfos.

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

String

Time zone of instance.

Default value: America/Los_Angeles .

instanceName

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

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

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

NicNetworkType

Network interface mode.

Default value: Auto .

Default value: Auto

systemDisk

SystemDisk

Boot disk configuration.

If the value is empty, the boot disk size is the minimum default value to store the operating system.

dataDisks

Array of 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

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

String

Private IP. If the specified IP is occupied, a default private IP will be allocated.

enableAgent

Boolean

Whether to enable QEMU Guest Agent (QGA). QGA is enabled by default.

Default value: true

enableIpForward

Boolean

Whether to enable IP forwarding. IP forwarding is disabled by default.

Default value: false

internetChargeType

InternetChargeType

Public network pricing model.

trafficPackageSize

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

Integer

Public outbound bandwidth cap.

Unit: Mbps .

Bandwidth cap varies by instance size.

Value range: [1, +)

eipBindType

BindType

Binding mode of the public IP.

Must be specified when a public IP is assigned.

When binding a block-type (CIDR) EIP, only Passthrough can be used, and it must be explicitly specified (it cannot be omitted — omitting it is equivalent to FullNat and will be rejected).

Default value: FullNat

eipIds

Array of String

Assigns existing EIPs to the instances.

The number of IPs must match the number of instances being created.

If this field is specified, no new EIPs are created and the related fields become invalid (networkLineType).

Ensure that the created network interface's ipStackType includes IPv4.

eipV4Type [Deprecated]

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

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

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

String

Bandwidth cluster ID.

This parameter is required when the network billing model is BandwidthCluster.

ipv6ClusterId

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

String

Resource group ID where the instances reside.

If the value is empty, the instance will be added into the default resource group.

marketingOptions

MarketingInfo

Information on marketing campaigns.

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

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. No public IP address is assigned.

POST /api/v2/zec HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateZecInstances
<Common Request Params>

Request：
{
  "zoneId": "asia-east-1a",
  "instanceType": "z2a.cpu.1",
  "imageId": "ubuntu2404_20240712",
  "instanceName": "Test-InstanceName",
  "keyId": "key-rcfljdP5",
  "subnetId": "1272168087751233112",
  "nicNetworkType": "Auto",
  "eipIds": ["<eipId1>"],
  "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": [
      "<instanceId>"
    ],
    "instances": [
    ],
    "orderNumber": "<orderNumber>"
  }
}

2. Create 1 instance and assign a public IP. The line type is BGP, and network billing uses a shared bandwidth package. The bandwidth limit is 10Mbps.

POST /api/v2/zec HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateZecInstances
<Common Request Params>

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": "<clusterId>",
  "networkLineType": "PremiumBGP"
}

Response:
{
  "requestId": "TA471524B-84E1-467B-AB77-75387BBD190B",
  "response": {
    "requestId": "TA471524B-84E1-467B-AB77-75387BBD190B",
    "instanceIdSet": [
      "<instanceId>"
    ],
    "instances": [
    ],
    "orderNumber": "<orderNumber>"
  }
}

3. Create 1 instance and assign both a public IPv4 and public IPv6 address. The IPv4 line type is BGP, and network billing uses a shared bandwidth package. The bandwidth limit is 10Mbps.

POST /api/v2/zec HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateZecInstances
<Common Request Params>

Request：
{
  "zoneId": "asia-east-1a",
  "instanceType": "z2a.cpu.1",
  "imageId": "ubuntu2404_20240712",
  "instanceName": "Test-InstanceName",
  "keyId": "key-rcfljdP5",
  "subnetId": "1272168087751233112",
  "internetChargeType": "BandwidthCluster",
  "bandwidth": 10,
  "ipStackType": "IPv4_IPv6",
  "clusterId": "<clusterId>",
  "ipv6ClusterId": "<ipv6ClusterId>",
  "networkLineType": "PremiumBGP"
}

Response:
{
  "requestId": "TA471524B-84E1-467B-AB77-75387BBD190B",
  "response": {
    "requestId": "TA471524B-84E1-467B-AB77-75387BBD190B",
    "instanceIdSet": [
      "<instanceId>"
    ],
    "instances": [
    ],
    "orderNumber": "<orderNumber>"
  }
}

4. Create 1 instance configured with multiple data disks.

POST /api/v2/zec HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateZecInstances
<Common Request Params>

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": [
      "<instanceId>"
    ],
    "instances": [
    ],
    "orderNumber": "<orderNumber>"
  }
}

5. Developer Resources

Zenlayer Cloud API 2.0 integrates SDKs，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.

HTTP Status Code

Error Code

Description

400

INVALID_DISK_CATEGORY_TYPE

Disk type error.

400

INVALID_EIP_BINDING_MODE_UNSUPPORTED

EIP Block does not support NAT binding mode.

404

INVALID_EIP_NOT_FOUND

Elastic IP does not exist.

404

INVALID_GPU_INSTANCE_TYPE_NOT_FOUND

GPU instance type does not exist.

404

INVALID_ACCELERATOR_TYPE_NOT_FOUND

Accelerator 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

The specified region 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

The EIP is already in use (not in unassigned state) and cannot be bound.

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.

Last updated 20 days ago