> 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/compute/zec/instance/createzecinstances.md).
# CreateZecInstances
## 1. 接口描述
本接口(CreateZecInstances)用于创建一台或多台虚拟机实例。
#### 准备工作
* 查询普通机型规格：调用[`DescribeZoneInstanceConfigInfos`](/api-reference/cn/compute/zec/instance/describezoneinstanceconfiginfos.md) 可以查询到规格信息。
* 查询 GPU 机型规格：调用[`DescribeZoneGpuInstanceConfigInfos`](/api-reference/cn/compute/zec/instance/describezonegpuinstanceconfiginfos.md) 可以查询到 GPU 规格信息。
* 查询镜像：调用[`DescribeImages`](/api-reference/cn/compute/zec/image/describeimages.md)可以查询到镜像信息。
* 查询密钥对：调用 [`DescribeKeyPairs`](/api-reference/cn/security/ccs/key-pair/describekeypairs.md)可以查询到密钥对ID信息。
{% hint style="info" %}
**注意事项**
* 实例创建成功后将自动开机启动，实例状态变为`RUNNING`, 如果创建失败，状态会变为`CREATE_FAILED`。
* 购买时需要确保账户账号状态正常。
* 调用本接口创建实例，支持代金券自动抵扣，详情请参考代金券选用规则。
* 本接口为异步接口，当创建实例请求下发成功后会返回一个实例`ID`列表，此时创建实例操作并未立即完成。在此期间实例的状态将会处于`DEPLOYING`，实例创建结果可以通过调用[`DescribeInstances`](/api-reference/cn/compute/zec/instance/describeinstances.md) 接口查询，如果实例状态由`DEPLOYING`变为`RUNNING`则代表创建成功，如果变为`CREATE_FAILED`则代表创建失败，创建过程中不可对实例进行任何操作。
* 单次最多能创建**100**台实例。
* 保底流量包大小仅对计费周期为月有效。
{% endhint %}
## 2. 请求参数
以下请求参数列表仅列出了接口中需要的请求参数
| 参数名称 | 必选 | 类型 | 描述 |
| ------------------ | -- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| zoneId | 是 | String | 可用区ID。 |
| imageId | 是 | String | 指定有效的镜像ID。
可以通过DescribeImages取返回信息中的imageId字段。
|
| instanceType | 是 | String | 实例机型。普通实例取值可通过[DescribeZoneInstanceConfigInfos](/api-reference/cn/compute/zec/instance/describezoneinstanceconfiginfos.md)获得；GPU 实例取值可通过[DescribeZoneGpuInstanceConfigInfos](/api-reference/cn/compute/zec/instance/describezonegpuinstanceconfiginfos.md)获得。 |
| instanceCount | 是 | Integer | 要创建的实例数量。
可选值范围：\[1, 100]
默认值：1
|
| subnetId | 是 | String | 子网ID。 |
| timeZone | 否 | String | 设置操作系统的时区。
如果未指定，将使用区域所在的时区。
|
| instanceName | 否 | String | 实例显示名称。
范围2到63个字符。
仅支持输入字母、数字、-和英文句点(.)。
且必须以数字或字母开头和结尾。
购买多台实例，可以指定模式串\[begin\_number,bits]。
begin\_number：有序数值的起始值，取值支持\[0,99999]，默认值为0。
bits：有序数值所占的位数，取值支持\[1,6]，默认值为6。
注意模式串中不得有空格。
购买1台时，例如server-\[3,3]实例显示为server003；购买2台时，实例显示名分别为server003，server004。
支持指定多个模式串，如server-\[3,3]-\[1,1]。
默认值为 instance。
|
| password | 否 | String | 实例的密码。
与keyId必须指定其中的一种（Windows和Generic类型的镜像无法指定密码和key）。
必须包含以下3种格式的字符：大小写字母: \[a-zA-Z]数字: 0-9特殊字符: \~!@$^\*-\_=+。
|
| keyId | 否 | String | 密钥ID。
与password必须指定其中的一种（Windows和Generic类型的镜像无法指定密码和key）。
可调用接口DescribeKeyPairs来获得最新的密钥对信息。
关联密钥后，就可以通过对应的私钥来访问实例；密钥与密码不能同时指定，同时Windows操作系统不支持指定密钥。
示例值：key-YWD2QFOl。
|
| nicNetworkType | 否 | [NicNetworkType](/api-reference/cn/compute/zec/datastructure.md#nicnetworktype) | 网卡模式。
默认值：Auto
|
| systemDisk | 否 | [SystemDisk](/api-reference/cn/compute/zec/datastructure.md#systemdisk) | 实例系统盘配置信息。
若不指定该参数，则按照系统默认值进行分配。
即操作系统要求的最小大小。
|
| dataDisks | 否 | Array of [DataDisk](/api-reference/cn/compute/zec/datastructure.md#datadisk) | 实例数据盘配置信息。若不指定该参数，则默认不额外购买数据盘。列表中每一项对应一块独立的数据盘，数据盘总数量受团队配额限制。 |
| securityGroupId | 否 | String | 要配置在实例主网卡的安全组ID。
目前只能关联1个安全组。
如果未指定，会默认用VPC关联的安全组。
|
| lanIp | 否 | String | 分配的内网起始IP。
如果内网IP被使用,则会往后分配。
|
| enableAgent | 否 | Boolean | 是否安装启动Agent。
默认值：true
|
| enableIpForward | 否 | Boolean | 是否开启IP转发。
默认值：false
|
| internetChargeType | 否 | [InternetChargeType](/api-reference/cn/compute/zec/datastructure.md#internetchargetype) | 公网IP的网络计费类型。
如果不指定，则不会分配公网IP地址。
|
| trafficPackageSize | 否 | Float | 流量包订购大小。
单位为TB。
该值必须在internetChargeType = ByTrafficPackage时才会生效。
当IpStackType = IPv4\_IPv6时，流量包大小作用于IPv4。
可选值范围：\[0.0, +)
|
| bandwidth | 否 | Integer | 公网出带宽上限。
单位：Mbps。
当分配公网IP时需要指定。
可选值范围：\[1, +)
|
| eipBindType | 否 | [BindType](/api-reference/cn/compute/zec/datastructure.md#bindtype) | 公网IP的绑定模式。
当分配公网IP时需要指定。
默认值：FullNat
|
| eipIds | 否 | Array of String | 分配已有的EIP到实例上。
IP数量必须和创建的实例数量一致。
如果指定该字段，则不会新建EIP, 相关字段将无效（networkLineType)。
请确保创建的网卡ipStackType 包含IPv4。
|
| eipV4Type \[已废弃] | 否 | [EipNetworkType](/api-reference/cn/compute/zec/datastructure.md#eipnetworktype) | 公网IPv4的线路类型。
当分配公网IP时需要指定。
请确保所选子网的堆栈类型支持IPv4。
已废弃，请使用networkLineType。
|
| ipStackType | 否 | [SubnetStackType](/api-reference/cn/compute/zec/datastructure.md#subnetstacktype) | 设置IP堆栈类型。
如果不指定，当子网堆栈类型IPv4或IPv4\_IPv6时，默认使用IPv4。
|
| networkLineType | 否 | [NetworkLineType](/api-reference/cn/compute/zec/datastructure.md#networklinetype) | 公网IPv4的线路类型。
当分配公网IP时需要指定。
请确保所选子网的堆栈类型支持IPv4。
|
| clusterId | 否 | String | 公网IPv4/IPv6加入的共享带宽包ID。
当网络计费方式是共享带宽包计费(BandwidthCluster)时需要指定。
|
| ipv6ClusterId | 否 | String | 公网IPv6加入的共享带宽包ID。
网络计费方式是共享带宽包计费(BandwidthCluster)时且ipStackType设定为IPv4\_IPv6时需要指定。
如果不指定，则默认使用clusterId。
该字段一般用于IPv4/IPv6所属不同共享带宽包。
|
| resourceGroupId | 否 | String | 创建后实例所在的资源组ID，如不指定则放入默认资源组。 |
| marketingOptions | 否 | [MarketingInfo](/api-reference/cn/compute/zec/datastructure.md#marketinginfo) | 市场营销的相关选项。 |
| tags | 否 | [TagAssociation](/api-reference/cn/compute/zec/datastructure.md#tagassociation) | 创建实例时关联的标签。
注意：·关联标签键不能重复。
|
| userData | 否 | String | 初始化命令。 |
| instanceOptions | 否 | [InstanceOptions](/api-reference/cn/compute/zec/datastructure.md#instanceoptions) | 实例选项配置。 |
## 3. 响应结果
| 参数名称 | 类型 | 描述 |
| ------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| requestId | String | 唯一请求 ID。
每次请求都会返回。定位问题时需要提供该次请求的 requestId。
|
| orderNumber | String | 订单编号。 |
| instanceIdSet | Array of String | 虚拟机实例ID列表。 |
| instances | Array of [DiskWithInstance](/api-reference/cn/compute/zec/datastructure.md#diskwithinstance) | 随机器创建的数据盘id集合。
如果请求中没有指定数据盘，返回空数组。
|
## 4. 代码示例
{% tabs %}
{% tab title="示例" %}
**1. 使用最简单的参数创建实例。不分配公网IP地址。**
```json
POST /api/v2/zec HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateZecInstances
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": [
""
],
"instances": [
],
"orderNumber": ""
}
}
```
**2. 创建2台实例，分配公网IP。线路类型为BGP, 网络计费使用共享带宽包。带宽限速为10Mbps。**
```json
POST /api/v2/zec HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateZecInstances
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": "",
"networkLineType": "PremiumBGP"
}
Response:
{
"requestId": "TA471524B-84E1-467B-AB77-75387BBD190B",
"response": {
"requestId": "TA471524B-84E1-467B-AB77-75387BBD190B",
"instanceIdSet": [
""
],
"instances": [
],
"orderNumber": ""
}
}
```
**4. 创建1台实例，配置多块数据盘。**
```json
POST /api/v2/zec HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateZecInstances
Request：
{
"zoneId": "asia-east-1a",
"instanceType": "z2a.cpu.1",
"imageId": "ubuntu2404_20240712",
"instanceName": "Test-InstanceName",
"keyId": "key-rcfljdP5",
"subnetId": "1272168087751233112",
"nicNetworkType": "Auto",
"dataDisks": [
{
"diskSize": 100,
"diskCategory": "Standard NVMe SSD"
},
{
"diskSize": 200,
"diskCategory": "Standard NVMe SSD"
}
]
}
Response:
{
"requestId": "TA471524B-84E1-467B-AB77-75387BBD190B",
"response": {
"requestId": "TA471524B-84E1-467B-AB77-75387BBD190B",
"instanceIdSet": [
""
],
"instances": [
],
"orderNumber": ""
}
}
```
{% 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\_DISK\_CATEGORY\_TYPE | 云盘的类型不合法。 |
| 404 | INVALID\_EIP\_NOT\_FOUND | EIP不存在。 |
| 404 | INVALID\_GPU\_INSTANCE\_TYPE\_NOT\_FOUND | GPU实例规格不存在。 |
| 400 | INVALID\_IMAGE\_AGENT\_NOT\_SUPPORT | 镜像不支持Agent。 |
| 400 | INVALID\_IMAGE\_IPV6\_NOT\_SUPPORT | 镜像不支持IPv6 Only。 |
| 400 | INVALID\_IMAGE\_KEY\_PAIR\_NOT\_SUPPORT | 镜像不支持ssh密钥对。 |
| 404 | INVALID\_IMAGE\_NOT\_FOUND | 镜像不存在。 |
| 400 | INVALID\_IMAGE\_PASSWORD\_NOT\_SUPPORT | 操作系统不支持指定密码。 |
| 400 | INVALID\_IMAGE\_SIZE\_EXCEED | 镜像大小超过指定系统盘的大小。 |
| 400 | INVALID\_IMAGE\_SPEC\_NOT\_SUPPORT | 镜像所需最低规格超过当前实例规格。 |
| 400 | INVALID\_INSTANCE\_COUNT\_LIMITATION | 实例的数量超过配额限制。 |
| 404 | INVALID\_INSTANCE\_TYPE\_NOT\_FOUND | 实例规格不存在。 |
| 400 | INVALID\_IP\_BROADCAST\_ADDRESS | IP为广播地址不可用。 |
| 400 | INVALID\_IP\_FIRST\_ADDRESS | IP为网关地址不可用。 |
| 400 | INVALID\_IP\_NETWORK\_ADDRESS | IP为网络地址不可用。 |
| 400 | INVALID\_IP\_OUT\_OF\_RANGE | IP地址不合法，不属于CIDR范围。 |
| 404 | INVALID\_KEY\_PAIR\_NOT\_FOUND | SSH密钥对不存在。 |
| 400 | INVALID\_LOGIN\_SETTING\_CONFLICT | 密码和密钥对不能同时设置。 |
| 409 | INVALID\_NIC\_INSTANCE\_REGION\_MISMATCH | 实例和网卡不在同一个节点。 |
| 400 | INVALID\_PARAMETER\_INSTANCE\_NAME\_EXCEED | 实例名称超过长度限制。 |
| 400 | INVALID\_PARAMETER\_INSTANCE\_NAME\_EXCEED\_MINIMUM\_LENGTH | 实例名称长度小于最小限制。 |
| 400 | INVALID\_PARAMETER\_INSTANCE\_NAME\_MALFORMED | 实例名称的格式不合法。 |
| 400 | INVALID\_PARAMETER\_USER\_DATA\_EXCEED | 实例命令超过长度限制。 |
| 404 | INVALID\_PASSWORD\_KEY\_PAIR\_MISSING | 未指定密码或密钥对。 |
| 400 | INVALID\_PASSWORD\_MALFORMED | 密码格式错误。 |
| 404 | INVALID\_REGION\_NOT\_FOUND | 指定的可用区不存在。 |
| 400 | INVALID\_REGION\_ZONE\_MISMATCH | 指定的Zone不在指定的Region下。 |
| 404 | INVALID\_SECURITY\_GROUP\_NOT\_FOUND | 安全组不存在。 |
| 409 | INVALID\_SUBNET\_IPV4\_INSUFFICIENT | Subnet下可用的IPv4数量不足。 |
| 409 | INVALID\_SUBNET\_IPV6\_INSUFFICIENT | Subnet下可用的IPv6数量不足。 |
| 404 | INVALID\_SUBNET\_NOT\_FOUND | 子网不存在。 |
| 400 | INVALID\_SYSTEM\_DISK\_EXCEED\_LIMIT | 系统盘大小超过限制。 |
| 404 | INVALID\_ZONE\_NOT\_FOUND | 可用区不存在。 |
| 400 | OPERATION\_DENIED\_CPU\_ILLEGAL | 规格的CPU数量非法。 |
| 400 | OPERATION\_DENIED\_DISK\_IO\_BURST | 未开启云盘性能突发功能。 |
| 400 | OPERATION\_DENIED\_EIP\_INSTANCE\_NOT\_ADAPTER | 指定的实例数量与需要创建的EIP数量不一致。 |
| 400 | OPERATION\_DENIED\_EIP\_INSUFFICIENT | 公网IP的库存不足，无法操作。 |
| 400 | OPERATION\_DENIED\_EIP\_IS\_DEFAULT | 默认公网IP无法解绑。 |
| 400 | OPERATION\_DENIED\_EIP\_IS\_NOT\_UN\_ASSIGN | EIP状态未解绑。 |
| 400 | OPERATION\_DENIED\_EIP\_NOT\_ASSIGNED | EIP状态未绑定。 |
| 400 | OPERATION\_DENIED\_EIP\_QUOTA\_LIMIT\_EXCEEDED | EIP数量超过配额限制。 |
| 400 | OPERATION\_DENIED\_EIP\_UNSUPPORTED\_NETWORK\_TYPE | EIP网络计费方式不支持。 |
| 400 | OPERATION\_DENIED\_MEMORY\_AMOUNT\_ILLEGAL | 规格的MEMORY数量非法。 |
| 400 | OPERATION\_DENIED\_NIC\_NETWORK\_TYPE\_NOT\_SUPPORT | 网卡模式不支持。 |
| 400 | OPERATION\_DENIED\_STACK\_TYPE\_NOT\_SUPPORT | 堆栈类型不支持。 |
| 400 | OPERATION\_DENIED\_SUBNET\_TYPE\_NOT\_SUPPORT | 子网堆栈类型不支持。 |
| 400 | OPERATION\_DENIED\_SUBNET\_TYPE\_NOT\_SUPPORT\_IPV4 | 子网堆栈类型不包括IPv4。 |
| 400 | OPERATION\_DENIED\_SUBNET\_ZONE\_MISMATCH | 子网的区域和可用区的区域不一致。 |
| 400 | INSTANCE\_STOCK\_INSUFFICIENT | 实例库存不足。 |
| 400 | UNSUPPORTED\_SUBNET\_TYPE\_FOR\_INTERNET\_CHARGE\_TYPE | 子网堆栈类型不支持公网。 |
| 400 | INVALID\_IP\_STACK\_TYPE\_NOT\_SUPPORT | IP堆栈类型不支持。 |
| 400 | INVALID\_NESTED\_VIRTUALIZATION\_NOT\_ALLOWED | 嵌套虚拟化配置不被允许。 |
| 400 | INVALID\_PARAMETER\_FLOW\_PACKAGE\_NOT\_SUPPORTED\_FOR\_PATH\_BASED | PathBasedBandwidthIP 不支持自定义流量包大小，需传 0 或不传。 |
| 400 | OPERATION\_DENIED\_FIXED\_BANDWIDTH\_NOT\_SUPPORTED\_FOR\_PATH\_BASED | 多路径带宽IP不支持固定带宽计费。 |
| 400 | OPERATION\_DENIED\_INTERNET\_CHARGE\_TYPE\_NOT\_SUPPORT | IP网络计费方式不支持。 |
| 409 | INVALID\_INSTANCE\_EIP\_REGION\_MISMATCH | 实例和EIP不在同一个节点。 |
| 400 | OPERATION\_DENIED\_FLOW\_PACKAGE\_NOT\_SUPPORTED\_HOUR\_PERIOD | 当前产品周期为小时计费，不支持设置保底流量包大小。 |