CreateInstances

1. API Description

This API is for customers who previously used the Virtual Machine API to create one or more elastic compute instances with specified configurations.

Prerequisites

Query instance model: call DescribeZoneInstanceConfigInfos to check specifications.
Query image: call DescribeImages to check information on image.
Query key pair: 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.

instanceType

Yes

String

Instance size.

To view specific values, you can call .

imageId

Yes

String

Valid image ID.

To obtain valid image ID, you can call, and find imageId in the response.

resourceGroupId

String

Resource group ID where the instances reside.

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

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].

instanceCount

Integer

The number of instances to be purchased.

Value range: [1,100].

Default value: 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: `~!@$^*-_=+|;:,.?

You must and can only pass the value of either password or keyId.

keyId

String

SSH key pair ID.

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 to obtain key pair information.

SSH key pairs and passwords cannot to set at the same time. SSH key pairs are not supported for Windows operating system. For example: key-YWD2QFOl You must and can only pass the value of either password or keyId.

internetChargeType

Yes

String

Public network pricing model.

See for details.

trafficPackageSize

Float

Traffic package size (TB).

The parameter is valid only when internetChargeType is ByTrafficPackage.

Default value: 0.

subnetId

Yes

String

Subnet ID.

Subnets only with IPv6 private network access type are not supported.

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

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.

timeZone

String

Time zone of instance.

Default value: Asia/Shanghai.

enableAgent

Boolean

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

enableIpForward

Boolean

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

eipV4Type

String

Network type of public IPv4. See for all values.

If you need to specify the value, please ensure that your subnet supports IPv4 stack type.

LocalLine and ThreeLine are not supported for now. Default value: BGPLine.

3. Output Parameters

Parameter Name

Type

Description

instanceIdSet

Array of String

List of instance IDs.

The returned instance ID list does not mean the creation has been completed. You can call to query 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.

orderNumber

String

Number of order.

instances

Array of

Set of disk IDs created along with the instances. If no disk is specified, the value is empty.

requestId

String

The unique request ID, which is returned for each request. RequestId is required for locating a problem.

4. Code Example

Create an instance with the simplest parameters Assuming to create an instance in Shanghai with the model of 1c2g, Standard NVMe SSD boot disk, data transfer billing method, SSH key pair instance access, and ubuntu24.04 image installed.

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

Request:
{
  "zoneId": "asia-east-1a",
  "instanceType": "z2a.cpu.1",
  "imageId": "ubuntu2404_20240712",
  "instanceName": "Sherlock1126151625",
  "instanceCount": 1,
  "keyId": "key-rcfljdP5",
  "internetChargeType": "ByTrafficPackage",
  "subnetId": "1272168087751233112",
  "systemDisk": {
    "diskSize": 40,
    "diskCategory": "Standard NVMe SSD"
  }
}

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

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_PARAMETER_INSTANCE_NAME_EXCEED

Invalid instance name length. The specified instance name exceeds the maximum length.

400

INVALID_PARAMETER_INSTANCE_NAME_MALFORMED

Invalid instance name format.

404

INVALID_IMAGE_NOT_FOUND

Image not found.

404

INVALID_ZONE_NOT_FOUND

Availability zone does not exist.

404

INVALID_INSTANCE_TYPE_NOT_FOUND

Instance type not found.

403

INVALID_SUBNET_NOT_FOUND

Subnet does not exist.

403

INVALID_INSTANCE_COUNT_LIMITATION

You are trying to create more instances than your remaining quota allows.

400

INVALID_KEY_PAIR_NOT_FOUND

SSH key pair does not exist.

400

RESOURCE_INSUFFICIENT_PRODUCT_SOLD_OUT

Resources not for sale.

403

INVALID_IMAGE_SIZE_EXCEED

Boot disk size should be larger than the image size.

400

INVALID_DISK_SIZE_LESS_MINIMUM

Disk size should be larger than the minimum limit.

400

INVALID_DISK_SIZE_EXCEED_MAXIMUM

Disk size exceeds the maximum limit.

403

OPERATION_DENIED_SUBNET_ZONE_MISMATCH

Subnet the instance added in is not in the current zone.

400

OPERATION_FAILED_RESOURCE_GROUP_NOT_FOUND

Resource group does not exist.

400

INVALID_PARAMETER_INSTANCE_NAME_EXCEED_MINIMUM_LENGTH

Instance name should be larger than the minimum limit.

400

INVALID_PARAMETER_INSTANCE_NAME_EXCEED

Instance name exceeds the maximum limit.

400

INVALID_SYSTEM_DISK_EXCEED_LIMIT

Boot disk size exceeds the limit.

400

INVALID_INSTANCE_TYPE_ZONE_NO_SELL

Instance type sold out or not for sale in the current zone.

403

OPERATION_DENIED_INTERNET_CHARGE_TYPE_NOT_SUPPORT

Public network billing model not supported in current zone.

400

INVALID_PASSWORD_MALFORMED

Password format error.

404

INVALID_TIME_ZONE_NOT_FOUND

Time zone does not exist.

400

STOCK_INSUFFICIENT

Insufficient instance stock.

400

INVALID_DISK_CATEGORY_TYPE

Disk type error.

400

INVALID_PARAMETER_TRAFFIC_PACKAGE_EXCEED

Data traffic package exceeds the maximum limit.

400

INVALID_PARAMETER_TRAFFIC_PACKAGE

Invalid data traffic package size. Only integers or one decimal place are allowed.

400

OPERATION_DENIED_EIP_UNSUPPORT_NETWORK_TYPE

Network type of the elastic IP is not supported for instance creating.

400

OPERATION_DENIED_EIP_INSUFFICIENT

Insufficient elastic IP stock.

400

OPERATION_DENIED_SUBNET_TYPE_NOT_SUPPORT

Stack type of the subnet is not supported for instance creating.

400

INVALID_IMAGE_IPV6_NOT_SUPPORT

IPv6 stack type is not supported for the selected image.

400

INVALID_IMAGE_AGENT_NOT_SUPPORT

QGA is not supported for the selected image.

404

INVALID_PASSWORD_KEY_PAIR_NOT_FOUND

Password or SSH key pair is not defined.

400

INVALID_LOGIN_SETTING_CONFLICT

You must and can only pass the value of either password or keyId.

400

INVALID_DISK_ILLEGAL_AMOUNT

Size of the disk created along with the instance exceeds the maximum limit.

Last updated 3 hours ago