CreateZecInstances

1. API Description

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

Prerequisites

• Query instance models: call DescribeZoneInstanceConfigInfos to check specifications.

• Query images: call DescribeImages to check information on image.

• Query key pairs: call DescribeKeyPairs to check information on key pair ID.

Note

• After an instance is created successfully, it will start up automatically, and the instance status will become "RUNNING".

• Please ensure your account balance is sufficient before calling this API.

• Vouchers can be used for fee deduction in instance creation. See Vouchers for more details.

• This API is an async API. An instance ID list is returned after the creation request is sent. However, it does not mean the creation has been completed. The status of the instance will be DEPLOYING during the creation. You can use DescribeInstances to query the status of the instance. If the status changes from DEPLOYING to Running, it means that the instance has been created successfully; CREATE_FAILED means creation failed. Any operations on the instances are not allowed while creating.

• A maximum of 100 instances can be created in one request.

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 size. To view specific values, you can call DescribeZoneInstanceConfigInfos .
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 . 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	Network interface mode. Default value: Auto . Default value: Auto
systemDisk	No	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	Disk configuration. If the value is empty, no disk is attached by default. Only 1 disk can be attached along with the instance for now.
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	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	Elastic IP mode. If not specified, the default is Full NAT mode. Default value: FullNat . Default value: FullNat
eipV4Type [Deprecated]	No	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	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	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	Information on marketing campaigns.
tags	No	TagAssociation	Bound tags when creating resources. Tag keys must be unique.
userData	No	String	Initialization command.
instanceOptions	No	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	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.

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",
  "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>"
  }
}

1. Create 2 instances with public IPs, using BGP lines and bandwidth cluster billing, limited to 10 Mbps.

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>",
  "eipV4Type": "BGPLine"
}

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_DATA_DISK_COUNT_LIMITATION	The number of disks exceeds the limit.
400	INVALID_DISK_CATEGORY_TYPE	Disk type error.
400	INVALID_DISK_ILLEGAL_AMOUNT	Size of the disk created along with the instance exceeds the maximum limit.
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_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_NOT_SUPPORT_PASS_THROUGH_BIND_TYPE	Elastic IP does not support the Bypass mode.
400	OPERATION_DENIED_EIP_QUOTA_LIMIT_EXCEEDED	The number of elastic IPs exceeds the quota limit.
400	OPERATION_DENIED_EIP_UNSUPPORT_NETWORK_TYPE	Elastic IP network billing model is not supported.
400	OPERATION_DENIED_INSTANCE_TYPE_FOR_WINDOWS	The instance type is not compatible with machines using Windows image types.
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	STOCK_INSUFFICIENT	Insufficient instance stock.
400	UNSUPPORT_SUBNET_TYPE_FOR_INTERNET_CHARGE_TYPE	Subnets only with IPv6 private network access type are not supported.
400	INVALID_IP_STACK_TYPE_NOT_SUPPORT	IP stack type is not supported.
400	INVALID_NESTED_VIRTUALIZATION_NOT_ALLOWED	Nested virtualization is not allowed.