说明：当前页面接口为旧版 API，未来可能停止维护，目前不展示在左侧导航。云服务器 API 3.0 版本接口定义更加规范，访问时延下降显著，建议使用 云服务器 API 3.0。
1. 接口描述
本接口 (RunInstances) 用于创建一台或多台指定配置的包年包月实例。
接口请求域名：cvm.api.qcloud.com
- API创建的实例遵循 CVM 实例购买限制 文档所描述的数量限制，和官网所创建的实例共用配额。
- CPU 与内存具体的配比限制参见 CVM 实例配置。
- 实例的创建需要一定时间，本接口不会立刻返回实例结果。而是返回一个 InstanceId，在此期间可以通过 DescribeInstances 接口查询该实例的状态。如果状态由“创建中”变为“正在运行”，则为创建成功。
- 本接口暂时只支持预付费的用户，在调用API前请确认余额充足。
- 实例创建成功后为“正在运行”的状态，无需再次调用 StartInstances 来启动。
- 如需要更改带宽，请在实例创建成功后，使用接口 UpdateInstanceBandwidth 更改，公网带宽不指定默认为0。
- 本接口暂不支持在创建实例的同时绑定安全组，所创建的实例默认所有端口都放通，建议用户在创建实例之后使用ModifySecurityGroupsOfInstance 接口给对应云服务器关联的安全组。
- 支持的实例类型：
机型 系列1 系列2 标准型 CVM.S1 CVM.S2 高IO型 CVM.I1 CVM.I2 内存型 CVM.M1 CVM.M2 计算型 － CVM.C2
2. 输入参数
以下请求参数列表仅列出了接口请求参数，其它参数见 公共请求参数 页面。
| 参数名称 | 是否必选 | 类型 | 描述 |
|---|---|---|---|
| cpu | 是 | Int | CPU（核数）。 |
| mem | 是 | Int | 内存（GB）。 |
| imageId | 是 | String | 镜像ID。可通过 DescribeImages 接口(链接包含公共镜像名称ID对应表)返回字段中的 unImgId 获取。 |
| period | 是 | Int | 购买时长(月)。至少1个月，最多36个月。 |
| storageSize | 是 | Int | 数据盘大小（GB）。最小调整步长为10G，此参数默认值为0，表示不购买数据盘。其所分配数据盘的类型与 storageType 所指定的一致。关于不同类型数据盘的特性与容量限制请参考硬盘产品简介。 |
| zoneId | 否 | Int | 可用区ID，默认为每个地区的第一个可用区。 |
| instanceType | 否 | String | 实例类型（例如高IO机型等）。默认为CVM.S1。更多实例类型，可在上文查看“实例类型”一节。 |
| imageType | 否 | Int | 镜像类型。1：私有镜像、2：公有镜像、3：镜像市场、4：共享镜像。默认为2。如果您指定非公有镜像的ImageId，则必须指定ImageType，如使用公有镜像，则无需ImageType参数。 |
| bandwidthType | 否 | String | 带宽的类型。PayByTraffic：按流量计费； PayByBandwidth：按带宽计费；默认是按带宽计费。关于各个网络计费模式之间的区别可以参考购买网络带宽。 |
| bandwidth | 否 | Int | 公网带宽(Mbps)，当按流量计费时为公网带宽峰值，默认为0。 |
| wanIp | 否 | Int | 是否开通公网IP。1：开通，0：不开通。bandwidth大于0，可自由选择开通与否，默认为开通；bandwidth为0，则不分配公网IP。 |
| vpcId | 否 | String | 私有网络 ID。私有网络下为必填，不填则为基础网络。 |
| subnetId | 否 | String | 子网 ID，私有网络下为必填（必须保证此subnetId在本可用区内）。 |
| isVpcGateway | 否 | Int | 是否是公网网关。0：非公网网关；1：公网网关；默认为0。公网网关只有在实例拥有公网IP并处于私有网络下时才能正常使用。 |
| storageType | 否 | Int | 硬盘类型。1:本地硬盘、2:普通云硬盘、3:本地 SSD 硬盘；默认为1。关于硬盘类型的选择请参考硬盘产品简介，可选硬盘类型受到实例类型（InstanceType）限制。另外允许购买的最大容量也因硬盘类型的不同而有所差异。 |
| rootSize | 否 | Int | 系统盘大小（GB）。 Linux/BSD 系统调整范围为20~50G，最小调整步长为10G，默认免费分配20G。Windows 不可调整，默认为免费分配50G。系统盘类型须与 storageType 所指定的一致。 |
| password | 否 | String | 实例密码。未设置则为随机产生，并通过站内信下发。Linux 实例密码必须是8至16位，至少包括以下三项中的两项。[a-z，A-Z]、[0-9] 和 [( ) ~ ! @ # $ % ^ & * - + = | { } [ ] : ; ' , . ? / ]中的特殊符号。Windows 实例密码必须是12至16位，至少包括以下四项中的三项。[a-z]，[A-Z]，[0-9] 和 [( ) ~ ! @ # $ % ^ & * - + = { } [ ] : ; ' , . ? /]中的特殊符号。 |
| keyId | 否 | String | 密钥ID。关联密钥后可使用密钥登录实例，keyId 可通过接口DescribeKeyPairs获取，密钥与密码不能同时指定，同时 Windows 操作系统不支持指定密钥。 |
| needSecurityAgent | 否 | Int | 开启 云安全服务。开通：1，不开通：0。默认开通。 |
| needMonitorAgent | 否 | Int | 开启 腾讯云可观测平台服务。开通：1，不开通：0。默认开通。 |
| projectId | 否 | Int | 项目 ID，不填为默认项目。 |
| instanceName | 否 | String | 实例名称，可任意命名，但不得超过60个字符。默认为“未命名”。 |
| goodsNum | 否 | Int | 购买实例的数量。默认为1，最大为100。 |
| clientToken | 否 | String | 保证此API幂等的Token，最多64字符。不同的API请求携带相同的 Token 视为同一请求，可以防止客户端请求API时因为网络异常而重试，导致多次创建实例的情况。 |
| privateIpAddresses.n | 否 | array of Strings | 私有子网ip数组，目前只支持一个ip。在创建实例、修改实例vpc属性操作中可使用此参数。 |
3. 输出参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| code | Int | 公共错误码。0表示成功，其他值表示失败。 |
| message | String | 模块错误信息描述，与接口相关。 |
| dealIds | Array | 生成的订单号，可通过 DescribeDeals API 查询后续执行状况。 |
| unInstanceIds | Array | 系统自动生成实例的 ID，命名格式为“ins-xxxxxxxx”，可使用此 ID 通过 DescribeInstances API 查询实例的详细信息。 |
4. 错误码
以下错误码表仅列出了该接口的业务逻辑错误码，更多公共错误码详见 CVM 错误码 页面。
| 错误码 | 描述 |
|---|---|
| InvalidParameter.InvaildZoneId | zoneId不合法 |
| OperationFail.SystemBusy | 资源购买繁忙 |
| InvalidParameter.PasswordNotConformSpecs | 密码不合规范 |
| InvalidParameter.InvaildZoneId | zoneId不合法 |
| OperationConstraints.AccountBalanceNotEnough | 您的余额不足，请先充值 |
| InvalidParameter.InvalidIpFormat | ip格式不正确 |
| InvalidParameter.NotSupportReservedIp | 保留ip不可使用 |
| InvalidParameter.IpNotInCidrRange | ip不在子网内 |
| InvalidParameter.IpInUse | ip已经被使用 |
5. 示例
输入
https://cvm.api.qcloud.com/v2/index.php?Action=RunInstances &imageId=img-lkxqa4kj &imageType=2 &bandwidth=1 &cpu=1 &mem=2 &storageType=1 &storageSize=50 &period=12 &goodsNum=1 &<公共请求参数>
输出
{
"code" : 0,
"message" : "ok",
"dealIds":[
121
],
"unInstanceIds": {
"121": [
"ins-npphstest"
]
}
}