CreateInstances

1. API Description

This API is used to create one or more virtual machine instances with a specified configuration.

Prerequisites

Query instance model: call DescribeZoneInstanceConfigInfos to check specifications.
Query image: call DescribeImages to check information on image.

Note

After an instance is created successfully, it will start up automatically, and the instance status will become "RUNNING".
If you create a subscription instance, the amount required will be pre-deducted. If the balance is insufficient, the request will fail. If you create a pay-as-you-go instance, 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 PENDING or DEPLOYING during the creation. You can use DescribeInstances to query the status of the instance. If the status (instanceStatus) changes from PENDING or DEPLOYING to Running, it means that the instance has been created successfully; if no instance has been queried, it means the instance has been created 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

Parameter Name	Required	Type	Description
zoneId	Yes	String	Zone ID to which the instances belong.
instanceChargeType	Yes	String	Instance pricing model. PREPAID: subscription POSTPAID: pay-as-you-go.
instanceChargePrepaid	No	ChargePrepaid	Details of the monthly subscription, including the purchase period, auto-renewal. It is required if the `instanceChargeType` is `PREPAID`.
instanceType	Yes	String	Instance model ID. To view specific values, you can call `DescribeZoneInstanceConfigInfos`.
imageId	Yes	String	Valid image ID. To obtain valid image ID, you can call `DescribeImages`, and find `imageId` in the response.
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.
instanceName	No	String	Instance name to be displayed. Default value: instance. This parameter can contain up to 64 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	No	Integer	The number of instances to be purchased. Value range: [1,100]. Default value: 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: !@#$%^&*`~()-+= You must and can only pass the value of either `password` or `keyId`.
keyId	No	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. 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 InternetChargeType for details.
internetMaxBandwidthOut	No	Integer	Public network bandwidth cap (Mbps). Default value: 1 Mbps. The parameter value differs with different instance models. See bandwidth configuration for details.
trafficPackageSize	No	Float	Traffic package size (TB). The parameter is valid only when `internetChargeType` is `ByTrafficPackage`. If not passed in, the default value will be the size of the free traffic package.
subnetId	Yes	String	Subnet ID.
systemDisk	No	SystemDisk	System disk configuration. If the value is empty, the system disk size is the minimum default value to store the operating system.
dataDisks	No	Array of DataDisk	Data disk configuration. If the value is empty, no data disk is attached by default. Only 10 data disk can be attached along with the instance for now.
securityGroupId	No	String	Security group ID. To obtain security group ID, you can call DescribeSecurityGroups , and find `sgId` in the response.

zoneId

Yes

String

Zone ID to which the instances belong.

instanceChargeType

Yes

String

Instance pricing model.

PREPAID: subscription

POSTPAID: pay-as-you-go.

instanceChargePrepaid

ChargePrepaid

Details of the monthly subscription, including the purchase period, auto-renewal. It is required if the instanceChargeType is PREPAID.

instanceType

Yes

String

Instance model ID. To view specific values, you can call DescribeZoneInstanceConfigInfos.

imageId

Yes

String

Valid image ID. To obtain valid image ID, you can call DescribeImages, 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 can contain up to 64 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. 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 InternetChargeType for details.

internetMaxBandwidthOut

Integer

Public network bandwidth cap (Mbps).

Default value: 1 Mbps.

The parameter value differs with different instance models. See bandwidth configuration for details.

trafficPackageSize

Float

Traffic package size (TB).

The parameter is valid only when internetChargeType is ByTrafficPackage. If not passed in, the default value will be the size of the free traffic package.

subnetId

Yes

String

Subnet ID.

systemDisk

SystemDisk

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

dataDisks

Array of DataDisk

Data disk configuration. If the value is empty, no data disk is attached by default. Only 10 data disk can be attached along with the instance for now.

securityGroupId

String

Security group ID. To obtain security group ID, you can call DescribeSecurityGroups , and find sgId in the response.

3. Output Parameters

Parameter Name Type Description

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. The status of the instance will be `PENDING` or `DEPLOYING` during the creation. You can call `DescribeInstances` to query the status of the instance according to `dataSet`. If the status changes from `PENDING` or `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.
requestId	String	The unique request ID, which is returned for each request. RequestId is required for locating a problem.

instanceIdSet

Array of String

List of instance IDs.

The returned instance ID list does not mean the creation has been completed. The status of the instance will be PENDING or DEPLOYING during the creation. You can call DescribeInstances to query the status of the instance according to dataSet. If the status changes from PENDING or 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.

requestId

String

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

4. Code Example

Create a pay-as-you -go instance with the simplest parameters Assuming to create a pay-as-you-go instance in Seoul A with the model of 1c2g, 1 Mbps flat rate bandwidth billing method, random system-generated password, and no images installed.

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

Request:
{
    "zoneId":"SEL-A",
    "instanceType":"c.1c2g",
    "imageId":"img-yKK4q6XybymPgfx7ynUUqC3N8",
    "instanceChargeType":"POSTPAID",
    "internetChargeType":"ByBandwidth"
}

Response:
{
    "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
    "response": {
        "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
        "instanceIdSet": ["instanceId1"],
        "orderNumber" : "the id of order number"
    }
}

Create two subscription instances Assuming to create two subscription instances in Seoul A with the model of 1c2g for 2 months, named SEL-1C2G-01 and SEL-1C2G-02, with the password: Password-12345~, image ID: image-xxxxx, and with 10 Mbps flat rate bandwidth billing method.

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

Request:
{
    "instanceChargeType": "PREPAID",
    "instanceCount": 2, 
    "instanceChargePrepaid":{
        "period": 2
    },
    "instanceName": "SEL-1C2G-[1,2]",
    "internetMaxBandwidthOut": 10,
    "password": "Password-12345~",
    "instanceType": "c.1c2g",
    "internetChargeType": "ByBandwidth",
    "zoneId": "SEL-A", 
    "imageId": "image-xxxxx"
}

Response:
{
    "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D4",
    "response": {
        "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D4",
        "instanceIdSet": ["instanceId3", "instanceId4"],
        "orderNumber" : "the id of order number"
    }
}

Create two subscription instances with traffic package billing method Similar to Example 2, but the difference is that the public network billing method created this time is a traffic package with a 10 TB size and 100 Mbps bandwidth cap.

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

Request:
{
    "instanceChargeType": "PREPAID",
    "instanceCount": 2, 
    "instanceChargePrepaid":{
        "period": 2
    },
    "instanceName": "SEL-1C2G-[1,2]",
    "internetMaxBandwidthOut": 100,
    "password": "Password-12345~",
    "instanceType": "c.1c2g",
    "internetChargeType": "ByTrafficPackage",
    "trafficPackageSize": 10,
    "zoneId": "SEL-A", 
    "imageId": "image-xxxxx"
}

Response:
{
    "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D4",
    "response": {
        "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D4",
        "instanceIdSet": ["instanceId5", "instanceId6"],
        "orderNumber" : "the id of order number"
    }
}

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.
403	OPERATION_FILED_INTERNET_CHARGE_TYPE_NOT_SUPPORT	Network billing method not supported in current zone.
404	INVALID_IMAGE_NOT_FOUND	Image not found.
404	INVALID_ZONE_NOT_FOUND	Zone does not exist.
404	INVALID_INSTANCE_TYPE_NOT_FOUND	Instance model not found.
403	INVALID_PARTITION_IMAGE_NOT_SET	Custom partition are only supported for specific operating system.
403	OPERATION_DENIED_INSTANCE_QUOTA_EXCEED	You are trying to create more instances than your remaining quota allows.
400	INVALID_BANDWIDTH_VALUE_EXCEED_MAXIMUM	Bandwidth exceeds the maximum limit.
400	INVALID_PARAMETER_VALUE_PASSWORD_MALFORMED	Invalid password.
400	RESOURCE_INSUFFICIENT_PRODUCT_SOLD_OUT	Resources not for sale.
403	OPERATION_DENIED_CHARGE_TYPE_NOT_SUPPORT	Pricing model not supported in current zone.
400	RESOURCES_SOLDOUT_INSTANCE_TYPE	Instance models sold out.
400	INVALID_DISK_SIZE_LESS_MINIMUM	Data disk size should be larger than the minimum limit.
400	INVALID_DISK_SIZE_EXCEED_MAXIMUM	Data disk size exceeds the maximum limit.
403	OPERATION_DENIED_SUBNET_ZONE_MISMATCH	Subnet the instance added in is not in the current zone.
400	INVALID_SYSTEM_DISK_SIZE	Invalid system disk size. The size should be multiples of 10 GB.
400	INVALID_SYSTEM_DISK_EXCEED_LIMIT	System disk size exceeds the maximum limit.
400	INVALID_INSTANCE_TYPE_ZONE_NO_SELL	Instance models sold out or not for sale in the current zone.
400	INVALID_DISK_ZONE_NO_SELL	Data disks sold out or not for sale in the current zone. You cannot create a data disk for now.
403	OPERATION_DENIED_INTERNET_CHARGE_TYPE_NOT_SUPPORT	Public network billing model not supported in current zone.
400	INVALID_PASSWORD_MALFORMED	Invalid password format. Please check the specified restrictions again.
400	INVALID_PARAMETER_BANDWIDTH_EXCEED	Public bandwidth exceeds the maximum limit.
403	OPERATION_DENIED_SUBNET_IP_INSUFFICIENT	Insufficient private IP addresses in the subnet.
400	INVALID_PARAMETER_TRAFFIC_PACKAGE_EXCEED	Size of data transfer package exceeds the maximum limit.
400	INVALID_PARAMETER_TRAFFIC_PACKAGE	Invalid data transfer package size. The size should be multiples of 0.1 TB or 1 TB.
403	INVALID_REGION_SECURITY_GROUP_NOT_SUPPORT	Security groups not supported in the zone.

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.

403

OPERATION_FILED_INTERNET_CHARGE_TYPE_NOT_SUPPORT

Network billing method not supported in current zone.

404

INVALID_IMAGE_NOT_FOUND

Image not found.

404

INVALID_ZONE_NOT_FOUND

Zone does not exist.

404

INVALID_INSTANCE_TYPE_NOT_FOUND

Instance model not found.

403

INVALID_PARTITION_IMAGE_NOT_SET

Custom partition are only supported for specific operating system.

403

OPERATION_DENIED_INSTANCE_QUOTA_EXCEED

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

400

INVALID_BANDWIDTH_VALUE_EXCEED_MAXIMUM

Bandwidth exceeds the maximum limit.

400

INVALID_PARAMETER_VALUE_PASSWORD_MALFORMED

Invalid password.

400

RESOURCE_INSUFFICIENT_PRODUCT_SOLD_OUT

Resources not for sale.

403

OPERATION_DENIED_CHARGE_TYPE_NOT_SUPPORT

Pricing model not supported in current zone.

400

RESOURCES_SOLDOUT_INSTANCE_TYPE

Instance models sold out.

400

INVALID_DISK_SIZE_LESS_MINIMUM

Data disk size should be larger than the minimum limit.

400

INVALID_DISK_SIZE_EXCEED_MAXIMUM

Data disk size exceeds the maximum limit.

403

OPERATION_DENIED_SUBNET_ZONE_MISMATCH

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

400

INVALID_SYSTEM_DISK_SIZE

Invalid system disk size. The size should be multiples of 10 GB.

400

INVALID_SYSTEM_DISK_EXCEED_LIMIT

System disk size exceeds the maximum limit.

400

INVALID_INSTANCE_TYPE_ZONE_NO_SELL

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

400

INVALID_DISK_ZONE_NO_SELL

Data disks sold out or not for sale in the current zone. You cannot create a data disk for now.

403

OPERATION_DENIED_INTERNET_CHARGE_TYPE_NOT_SUPPORT

Public network billing model not supported in current zone.

400

INVALID_PASSWORD_MALFORMED

Invalid password format. Please check the specified restrictions again.

400

INVALID_PARAMETER_BANDWIDTH_EXCEED

Public bandwidth exceeds the maximum limit.

403

OPERATION_DENIED_SUBNET_IP_INSUFFICIENT

Insufficient private IP addresses in the subnet.

400

INVALID_PARAMETER_TRAFFIC_PACKAGE_EXCEED

Size of data transfer package exceeds the maximum limit.

400

INVALID_PARAMETER_TRAFFIC_PACKAGE

Invalid data transfer package size. The size should be multiples of 0.1 TB or 1 TB.

403

INVALID_REGION_SECURITY_GROUP_NOT_SUPPORT

Security groups not supported in the zone.

Last updated 23 days ago