# CreateInstances
## 1. API Description
This API (CreateInstances) is used to create one or more virtual machine instances with a specified configuration.
#### Prerequisites
* Query instance model: call [`DescribeZoneInstanceConfigInfos`](/api-reference/compute/vm/virtual-machine-instance/describezoneinstanceconfiginfos.md) to check specifications.
* Query image: call [`DescribeImages`](/api-reference/compute/vm/image/describeimages.md) to check information on image.
{% hint style="info" %} **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](https://docs.console.zenlayer.com/welcome/platform/billing-center/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.
{% endhint %}
## 2. Input Parameters
The following request parameter list only provides API request parameters.
| Parameter Name | Required | Type | Description |
| ----------------------- | -------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| zoneId | Yes | String | Zone ID to which the instances belong. |
| 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 model ID.
To view specific values, you can call
DescribeZoneInstanceConfigInfos.
|
| instanceChargeType | Yes | [ChargeType](/api-reference/compute/vm/datastructure.md#chargetype) | Instance pricing model.
PREPAID: subscription
POSTPAID: pay-as-you-go.
|
| internetChargeType | Yes | [InternetChargeType](/api-reference/compute/vm/datastructure.md#internetchargetype) | Public network pricing model.
See InternetChargeType for details.
|
| 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. |
| 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].
|
| password | No | String | Instance password.
The parameter must be 8-16 characters, including:lowercase letters: \[a-z]uppercase letters: \[A-Z]digits: 0-9special 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.
|
| 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.
|
| instanceChargePrepaid | No | [ChargePrepaid](/api-reference/compute/vm/datastructure.md#chargeprepaid) | Details of the monthly subscription, including the purchase period, auto-renewal. It is required if the instanceChargeType is PREPAID. |
| instanceChargePostpaid | No | [ChargePostpaid](/api-reference/compute/vm/datastructure.md#chargepostpaid) | Postpaid mode parameter settings. |
| 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.
Value range: \[0.0, +)
|
| 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.
Value range: \[1, +)
Default value: 1
|
| systemDisk | No | [SystemDisk](/api-reference/compute/vm/datastructure.md#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](/api-reference/compute/vm/datastructure.md#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.
|
| enableIpv6 | No | Boolean | Whether enable public IPv6 or not. |
| enableIpv4 | No | Boolean | Whether to enable public IPv4. |
| cpuPassThrough | No | Boolean | Whether CPU passthrough is enabled. |
| initScript | No | String | Initialize the script. The string's byte size must not exceed 32 KB. |
| networkMode | No | [NetworkMode](/api-reference/compute/vm/datastructure.md#networkmode) | Network interface mode.Vf: VFIO ModeVirtio: Virtio-net Mode |
| diskPreAllocated | No | Boolean | Pre allocate disk performance |
| nic | No | [Nic](/api-reference/compute/vm/datastructure.md#nic) | Name of network interface configuration. |
| securityGroupId | No | String | Security group ID.
To obtain security group ID, you can call DescribeSecurityGroups , and find sgId in the response.
|
| clusterId | No | String | Bandwidth cluster ID. |
| cidrBlockId | No | String | CIDR Address Block ID. This field specifies the public IP address to be assigned from the CIDR address block. |
| startCidrIpv4 | No | String | The starting IP address within the CIDR address range.
This field requires the quota cidrBlockId to be used together, and it represents the public IP address to be assigned to the machine from the address range starting at this address.
|
| marketingOptions | No | [MarketingInfo](/api-reference/compute/vm/datastructure.md#marketinginfo) | Information on marketing campaigns. |
| tags | No | [TagAssociation](/api-reference/compute/vm/datastructure.md#tagassociation) | Tags associated when creating resources.
Note: The associated tag key cannot be duplicated.
|
## 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. 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.
|
| instances | Array of [DiskWithInstance](/api-reference/compute/vm/datastructure.md#diskwithinstance) | Set of data disk IDs created along with the instances. If no data disk is specified, the value is empty. |
## 4. Code Example
{% tabs %} {% tab title="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.
```json
POST /api/v2/vm HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateInstances
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",
"instances":[{"instanceId":"instanceId1","diskIdSet":[]}]
}
}
```
## 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\_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 not found. |
| 404 | INVALID\_INSTANCE\_TYPE\_NOT\_FOUND | Instance model not found. |
| 400 | 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 model not available in the 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 | Only operations on instance whose [`internetChargeType`](/api-reference/compute/vm/datastructure.md#internetchargetype) is `ByTrafficPackage` are supported. |
| 400 | INVALID\_PASSWORD\_MALFORMED | Invalid password format. Please check the specified restrictions again. |
| 400 | INVALID\_PARAMETER\_BANDWIDTH\_EXCEED | Bandwidth size exceeds the maximum limit. |
| 403 | OPERATION\_DENIED\_SUBNET\_IP\_INSUFFICIENT | Insufficient private IP addresses in the subnet. |
| 400 | INVALID\_PARAMETER\_TRAFFIC\_PACKAGE\_EXCEED | Data transfer package size exceeds the upper limit. |
| 400 | INVALID\_PARAMETER\_TRAFFIC\_PACKAGE | Invalid data transfer package size. |
| 403 | INVALID\_REGION\_SECURITY\_GROUP\_NOT\_SUPPORT | Security groups not supported in the zone. |
| 404 | OPERATION\_DENIED\_IPV4\_CIDR\_NOT\_FOUND | CIDR Block not found. |
| 403 | OPERATION\_DENIED\_IPV4\_CIDR\_IP\_NOT\_ENOUGH | CIDR Block IPv4 is not sufficient. |
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.console.zenlayer.com/api-reference/compute/vm/virtual-machine-instance/createinstances.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.