> For the complete documentation index, see [llms.txt](https://docs.console.zenlayer.com/api-reference/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.console.zenlayer.com/api-reference/cn/legacy/vm/virtual-machine-instance/createinstances.md). # CreateInstances ## 1. 接口描述 本接口(CreateInstances)用于创建一个或多个指定配置的虚拟机实例。 #### 准备工作 * 查询机型规格：调用[`DescribeZoneInstanceConfigInfos`](/api-reference/cn/legacy/vm/virtual-machine-instance/describezoneinstanceconfiginfos.md) 可以查询到规格信息。 * 查询镜像：调用[`DescribeImages`](/api-reference/cn/legacy/vm/image/describeimages.md)可以查询到镜像信息。 * 查询密钥对：调用 [`DescribeKeyPairs`](https://github.com/zenlayer/zenlayercloud-api-doc-cn/tree/main/security/key-service/key-pair/describekeypairs.md)可以查询到密钥对ID信息。 {% hint style="info" %} **注意事项** * 实例创建成功后将自动开机启动，实例状态变为`RUNNING`(运行中)。 * 预付费实例的购买会预先扣除本次实例购买所需金额，如果余额不足，请求将会失败。后付费实例购买时需要确保账户账号状态正常。 * 调用本接口创建实例，支持代金券自动抵扣，详情请参考代金券选用规则。 * 本接口为异步接口，当创建实例请求下发成功后会返回一个实例`ID`列表，此时创建实例操作并未立即完成。在此期间实例的状态将会处于`PENDING`或`DEPLOYING`，实例创建结果可以通过调用`DescribeInstances` 接口查询，如果实例状态(instanceStatus)由`CREATING`(创建中)或`PENDING`(等待创建）变为`RUNNING`(运行中)，则代表实例创建成功，如果未查询到任何实例，则代表创建失败，创建过程中不可对实例进行任何操作。 * 单次最多能创建**100**台实例。 {% endhint %} ## 2. 请求参数 以下请求参数列表仅列出了接口中需要的请求参数 | 参数名称 | 必选 | 类型 | 描述 | | ----------------------- | -- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | zoneId | 是 | String | 实例所在节点ID。 | | imageId | 是 | String | 指定有效的镜像ID。 | | instanceType | 是 | String | 实例机型。 | | instanceChargeType | 是 | [ChargeType](/api-reference/cn/legacy/vm/datastructure.md#chargetype) |

付费类型。

PREPAID：预付费，即包年包月。

POSTPAID：后付费。

| | internetChargeType | 是 | [InternetChargeType](/api-reference/cn/legacy/vm/datastructure.md#internetchargetype) | 网络计费类型。 | | instanceCount | 是 | Integer |

指定创建实例的数量。

可选值范围：\[1, 100]

默认值：1

| | subnetId | 是 | String | 私有网络子网ID。 | | instanceName | 否 | String | 实例显示名称。 | | password | 否 | String | 实例的密码。 | | keyId | 否 | String | 密钥ID。 | | resourceGroupId | 否 | String | 实例所在的资源组ID。 | | instanceChargePrepaid | 否 | [ChargePrepaid](/api-reference/cn/legacy/vm/datastructure.md#chargeprepaid) |

预付费模式，即包年包月相关参数设置。

若指定实例的付费模式为预付费则该参数必传。

| | instanceChargePostpaid | 否 | [ChargePostpaid](/api-reference/cn/legacy/vm/datastructure.md#chargepostpaid) | 后付费模式相关参数设置。 | | trafficPackageSize | 否 | Float |

流量包订购大小，单位TB。

可选值范围：\[0.0, +)

| | internetMaxBandwidthOut | 否 | Integer |

公网出带宽上限，单位Mbps。

可选值范围：\[1, +)

默认值：1

| | systemDisk | 否 | [SystemDisk](/api-reference/cn/legacy/vm/datastructure.md#systemdisk) | 实例系统盘配置信息。 | | dataDisks | 否 | Array of [DataDisk](/api-reference/cn/legacy/vm/datastructure.md#datadisk) | 实例数据盘配置信息。 | | enableIpv6 | 否 | Boolean | 是否开启公网IPv6。 | | enableIpv4 | 否 | Boolean | 是否开启公网IPv4。 | | cpuPassThrough | 否 | Boolean |

是否开启CPU穿透。

默认不开放该权限，如需开放请联系Zenlayer Support。

| | initScript | 否 | String | 初始化脚本，需进行Base64编码后传入，脚本内容大小不超过32KB。 | | networkMode | 否 | [NetworkMode](/api-reference/cn/legacy/vm/datastructure.md#networkmode) |

网卡模式。

Vf：物理直通模式。

Virtio：软件模拟模式。

| | diskPreAllocated | 否 | Boolean | 硬盘数据预分配。 | | nic | 否 | [Nic](/api-reference/cn/legacy/vm/datastructure.md#nic) | 网卡配置。 | | securityGroupId | 否 | String | 安全组ID。 | | clusterId | 否 | String | 带宽组ID。 | | cidrBlockId | 否 | String |

CIDR 地址块ID。

指定该字段将从CIDR 地址块里分配公网IP。

| | startCidrIpv4 | 否 | String |

CIDR地址段内的起始IP地址。

该字段需要配额cidrBlockId一起使用，该字段代表将从该地址起始从地址段中给机器分配公网IP。

| | marketingOptions | 否 | [MarketingInfo](/api-reference/cn/legacy/vm/datastructure.md#marketinginfo) | 市场营销活动相关信息。 | | tags | 否 | [TagAssociation](/api-reference/cn/legacy/vm/datastructure.md#tagassociation) |

创建实例时关联的标签。

注意：关联标签键不能重复。

| ## 3. 响应结果 | 参数名称 | 类型 | 描述 | | ------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | requestId | String |

唯一请求 ID。

每次请求都会返回。定位问题时需要提供该次请求的 requestId。

| | orderNumber | String | 订单编号。 | | instanceIdSet | Array of String |

虚拟机实例ID列表。

当通过本接口来创建实例时会返回该参数，表示一个或多个实例ID。

返回实例ID列表并不代表实例创建成功，可根据 DescribeInstances 接口查询返回的dataSet中对应实例的状态来判断创建是否完成：如果实例状态由DEPLOYING(部署中)或PENDING（待创建）变为RUNNING(运行中)，则为创建成功；如果实例找不到或状态变为CREATE\_FAILED，表示创建失败。

| | instances | Array of [DiskWithInstance](/api-reference/cn/legacy/vm/datastructure.md#diskwithinstance) |

随机器创建的数据盘ID集合。

如果请求中没有指定数据盘，返回空数组。

| ## 4. 代码示例 {% tabs %} {% tab title="示例" %} **1. 用最简单的参数创建一台后付费的实例** ```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", "cidrBlockId": "" } 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":[]}] } } ``` **2. 在1的基础上附带一块大小为40GB的标准数据盘** ```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", "dataDisks": [ { "diskSize": 40, "diskCategory": "STANDARD" } ] } 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":["diskId1"]}] } } ``` **3. 创建2台预付费的实例** ```json POST /api/v2/vm HTTP/1.1 Host: console.zenlayer.com Content-Type: application/json X-ZC-Action: CreateInstances 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", "instances": [ { "instanceId": "instanceId3", "diskIdSet": [] }, { "instanceId": "instanceId4", "diskIdSet": [] } ] } } ``` **4. 创建2台预付费的实例，其网络计费方式为流量包** ```json POST /api/v2/vm HTTP/1.1 Host: console.zenlayer.com Content-Type: application/json X-ZC-Action: CreateInstances 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", "instances": [ { "instanceId": "instanceId5", "diskIdSet": [] }, { "instanceId": "instanceId6", "diskIdSet": [] } ] } } ``` **5. 创建一台实例，并指定初始化脚本** ```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", "cidrBlockId": "", "initScript": "IyEvYmluL2Jhc2gKZWNobyAiaGVsbG8gemVubGF5ZXIiID4gL3RtcC9pbml0LmxvZwo=" } Response: { "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D5", "response": { "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D5", "instanceIdSet": ["instanceId7"], "orderNumber" : "the id of order number", "instances":[{"instanceId":"instanceId7","diskIdSet":[]}] } } ``` {% endtab %} {% endtabs %} ## 5. 开发者工具 Zenlayer Cloud API 2.0 提供了配套的[开发工具集（SDK）](/api-reference/cn/api-introduction/toolkit.md)，未来会陆续支持更多开发语言，方便快速接入和使用Zenlayer的产品和服务。 ## 6. 错误码 下面包含业务逻辑中遇到的错误码，其他错误码见[公共错误码](/api-reference/cn/api-introduction/instruction/commonerrorcode.md) | HTTP状态码 | 错误码 | 说明 | | ------- | ------------------------------------------------------- | --------------------------------------------- | | 400 | INVALID\_PARAMETER\_INSTANCE\_NAME\_EXCEED | 参数instanceName超过了长度限制，请注意模式串中的bits总和不要超过指定长度。 | | 400 | INVALID\_PARAMETER\_INSTANCE\_NAME\_MALFORMED | 参数instanceName格式不正确，请注意输入值在规定的字符内。 | | 403 | OPERATION\_FILED\_INTERNET\_CHARGE\_TYPE\_NOT\_SUPPORT | 指定的网络计费类型在当前区域不支持。 | | 404 | INVALID\_IMAGE\_NOT\_FOUND | 未找到指定的镜像。 | | 404 | INVALID\_ZONE\_NOT\_FOUND | 指定的可用区不存在。 | | 404 | INVALID\_INSTANCE\_TYPE\_NOT\_FOUND | 未找到指定的实例规格。 | | 400 | INVALID\_PARTITION\_IMAGE\_NOT\_SET | 自定义分区必须指定操作系统才可以进行。 | | 403 | OPERATION\_DENIED\_INSTANCE\_QUOTA\_EXCEED | 机器创建数量超过了当前Team的总配额。 | | 400 | INVALID\_BANDWIDTH\_VALUE\_EXCEED\_MAXIMUM | 指定的带宽大小超过了机型允许的最大范围限制。 | | 400 | INVALID\_PARAMETER\_VALUE\_PASSWORD\_MALFORMED | 无效密码。指定的密码不符合密码复杂度限制。例如密码长度不符合限制等。 | | 400 | RESOURCE\_INSUFFICIENT\_PRODUCT\_SOLD\_OUT | 所选资源未售卖。 | | 403 | OPERATION\_DENIED\_CHARGE\_TYPE\_NOT\_SUPPORT | 该区域所选择的付费类型不支持。 | | 400 | RESOURCES\_SOLDOUT\_INSTANCE\_TYPE | 指定的实例机型已售罄。 | | 400 | INVALID\_DISK\_SIZE\_LESS\_MINIMUM | 数据盘大小小于了最小值。 | | 400 | INVALID\_DISK\_SIZE\_EXCEED\_MAXIMUM | 数据盘大小超过了最大限制。 | | 403 | OPERATION\_DENIED\_SUBNET\_ZONE\_MISMATCH | 创建虚拟机实例加入的子网和所选可用区不一致。 | | 400 | INVALID\_SYSTEM\_DISK\_SIZE | 无效系统盘大小，必须是10的倍数。 | | 400 | INVALID\_SYSTEM\_DISK\_EXCEED\_LIMIT | 指定的系统盘大小超过了指定限制。 | | 400 | INVALID\_INSTANCE\_TYPE\_ZONE\_NO\_SELL | 所选规格在所选区域已售罄或未开售。 | | 400 | INVALID\_DISK\_ZONE\_NO\_SELL | 当前区域数据盘不可用或已售罄，无法创建数据盘。 | | 403 | OPERATION\_DENIED\_INTERNET\_CHARGE\_TYPE\_NOT\_SUPPORT | 指定的区域不支持对应的公网网络计费方式。 | | 400 | INVALID\_PASSWORD\_MALFORMED | 输入的密码格式错误，请检查字符都包含在规定的字符里。 | | 400 | INVALID\_PARAMETER\_BANDWIDTH\_EXCEED | 设置的公网带宽出口超过最大限制。 | | 403 | OPERATION\_DENIED\_SUBNET\_IP\_INSUFFICIENT | 指定的子网内无足够可用的私有IP。 | | 400 | INVALID\_PARAMETER\_TRAFFIC\_PACKAGE\_EXCEED | 设定的流量包大小超过最大限制。 | | 400 | INVALID\_PARAMETER\_TRAFFIC\_PACKAGE | 设定的流量包大小值不合法，必须是0.1或1的倍数。 | | 403 | INVALID\_REGION\_SECURITY\_GROUP\_NOT\_SUPPORT | 区域不支持安全组。 | | 404 | OPERATION\_DENIED\_IPV4\_CIDR\_NOT\_FOUND | CIDR Block不存在。 | | 403 | OPERATION\_DENIED\_IPV4\_CIDR\_IP\_NOT\_ENOUGH | CIDR Block IPv4不足够。 |