【旧版】创建实例 CreatePod--云手机-火山引擎

文档中心

立即注册

导航

【旧版】创建实例 CreatePod

最近更新时间：2025.11.03 17:18:49首次发布时间：2024.03.04 19:40:01

根据已购入的实例套餐规格，创建一个或多个新的云手机实例。

使用说明

本接口支持单实例创建和多实例创建两种模式。PodSpecList 参数仅应用于多实例创建模式。
- 单实例创建：如需对该实例进行自定义配置，请直接使用请求体中最外层的参数进行配置，无需在请求体中包含 PodSpecList 参数。
- 多实例创建：在批量创建模式中，请使用 PodSpecList 参数。该参数系多个 PodSpec 对象组成的数组。每个 PodSpec 对象用于定义一个或多个实例的具体配置。因 PodSpec 中的配置具有更高的优先级，意味着将覆盖外层的设置，因此，若对批量创建的实例有自定义配置需求，请在对应的 PodSpec 对象内指定实例的配置，而无需在外层请求体中重复填写相同的参数。
调用本接口仅执行实例创建。如果您的业务场景需要在实例创建完成的同时自动安装一系列应用程序，推荐使用 CreatePodOneStep 接口，但请注意 CreatePodOneStep 单次调用仅能创建 1 个实例。

注意事项

PodSpec 中暂不支持机型库配置。批量创建的实例如需使用预设机型参数，仅可通过外层请求体中的 UsePropertyRule 和 PropertyRuleName 参数进行配置，即同批次创建的多个实例仅可以使用机型库中的一条机型参数规则。
若传入的业务 ID（即 ProductId）对应本地存储方案，则无论创建单个实例还是批量创建多个实例，ResourceType 参数必填，取值为 200。
本接口的单用户 QPS 限制为 50 次/秒。超过限制，API 调用会被限流。

请求说明

请求方式：POST
请求地址：https://open.volcengineapi.com?Action=CreatePod&Version=2023-10-30

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

Query

参数	类型	是否必选	示例值	描述
Action	String	是	`CreatePod`	接口名称。当前 API 的名称为 `CreatePod`。
Version	String	是	`2023-10-30`	接口版本。当前 API 的版本为 `2023-10-30`。

Body

参数	类型	是否必选	示例值	描述
ProductId	String	是	`1591495366954xxxxxx`	业务 ID，管理云手机资源、开展云手机业务的标识。可登录云手机控制台，在已创建的业务卡片中获取。
ResourceType	Integer	否	`100`	实例所属业务对应的存储方案类型。本参数默认为云盘存储方案，取值为 `100`。若当前业务（`ProductId`）对应本地存储方案，则本参数必填，取值为 `200`。说明无论创建单实例还是多实例，只要使用本地存储方案，本参数必填 `200`。
PodSpecList	Array of PodSpec	否	`-`	多实例配置项，用于在创建多实例时，指定实例的自定义配置。说明创建多实例时必填。
Dc	String	否	`gdsz-ctcucm-01-xxxxxxxx`	机房 ID。说明本参数为创建单实例时必填，创建多实例请使用 `PodSpecList` 参数。
ConfigurationCode	String	否	`enhanced`	运行实例的套餐规格 ID，即购买资源时选择或创建的实例规格。当前业务下已购入的实例可选规格可以通过 ListPodResource 接口查询。更多规格信息参看本地存储实例规格列表或云盘存储实例规格列表。说明本参数创建单实例时必填，创建多实例请使用 `PodSpecList` 参数。
HostId	String	否	`h-7340161778808xxxxxx`	云机 ID，用于指定实例所归属的云机。当前业务下的可用云机可通过 ListHost 接口查询。若本参数传空，系统将自动分配空余云机。说明本参数仅适用于本地存储方案，即仅当 `ResourceType` 为 `200` 时生效。本参数为创建单实例时使用，创建多实例请使用 `PodSpecList` 参数。
PodName	String	否	`新建实例`	实例名称，可自定义。如不指定，则默认与返回的实例 ID 一致。说明本参数为创建单实例时使用，创建多实例请使用 `PodSpecList` 参数。
ImageId	String	否	`img-76xxxxxx`	自定义镜像 ID，如不指定，则默认使用平台提供的官方标准镜像。说明本参数为创建单实例时使用，创建多实例请使用 `PodSpecList` 参数。
DataSize	String	否	`4Gi`	创建的实例预期占用的存储容量，取值范围为 1Gi～128Gi，且必须为整数。请结合实际业务情况，按需填写存储大小。说明本参数为创建单实例时使用，创建多实例请使用 `PodSpecList` 参数。本参数仅适用于云盘存储方案。本地存储方案中，DataSize 为默认固定值，不支持自定义。
DisplayLayoutId	String	否	`single-display-portrait`	屏幕布局 ID，用于指定云手机实例的屏幕显示配置。您可以选择系统提供的屏幕布局，也可以使用通过 CreateDisplayLayoutMini 接口创建的自定义屏幕布局。若使用系统屏幕布局，可选项包括： `single-display-landscape`：1080p 横屏，分辨率 19201080 像素，像素密度 320 dpi，帧率 60fps； `single-display-portrait`：1080p 竖屏，分辨率 10801920 像素，像素密度 320 dpi，帧率 60fps； `single-display-portrait-720p`：高清竖屏，分辨率 7201080 像素，像素密度 320 dpi，帧率 30fps。若使用自定义屏幕布局，可选项可通过 ListDisplayLayoutMini 接口获取。说明本参数为创建单实例时使用，创建多实例*请使用 `PodSpecList` 参数。若本参数传空，则各规格实例将使用默认的系统屏幕布局。以下规格实例使用 `single-display-portrait` 1080p 竖屏布局： `common`/`commonPlus`/`commonPro` `enhanced`/`enhancedPlus`/`enhancedPro` `ultimate`/`ultimatePlus`/`ultimatePro` 以下规格实例使用 `single-display-portrait-720p` 高清竖屏布局： `basic`/`basicPlus`/`basicPro` `elementary`/`elementaryPlus`/`elementaryPro` `sample`/`samplePlus`/`samplePro`
OverlaySettings	Array of Settings	否	`-`	实例初始化系统偏好设置。说明本参数为创建单实例时使用，创建多实例请使用 `PodSpecList` 参数。
OverlayProperty	Array of SystemProperty	否	`-`	非持久化系统属性设置，仅在当次实例运行期间有效，重启实例后不予保留。说明本参数为创建单实例时使用，创建多实例请使用 `PodSpecList` 参数
OverlayPersistProperty	Array of SystemProperty	否	`-`	持久化系统属性设置，长期有效，重启实例后仍旧保留。说明本参数为创建单实例时使用，创建多实例请使用 `PodSpecList` 参数。适用于只读系统属性，或 AOSP 原生非持久化的系统属性的修改，如 ro.product.model。
Start	Boolean	否	`false`	创建完成后是否立即开机。取值如下： `true`：是； `false`：（默认）否。说明本参数为创建单实例时使用，创建多实例请使用 `PodSpecList` 参数。
TagId	String	否	`01`	标签 ID，已调用 CreateTag 接口创建标签后，可使用本参数为实例添加分组标签。可选的标签 ID 可通过 ListTag 接口查询。说明本参数为创建单实例时使用，创建多实例请使用 `PodSpecList` 参数。
UpBandwidthLimit	Integer	否	`0`	实例上行带宽上限，用于控制云手机发送数据的流量，单位：Mbps。如需设置上行带宽限速，为确保顺畅的浏览和使用体验，建议限速值不低于 5Mbps。默认为 0，即不限速。说明本参数为创建单实例时使用，创建多实例请使用 `PodSpecList` 参数。
DownBandwidthLimit	Integer	否	`0`	实例下行带宽上限，用于控制云手机接收数据的流量，单位：Mbps。如需设置下行带宽限速，为确保顺畅的浏览和使用体验，建议限速值不低于 5Mbps。默认为 0，即不限速。说明本参数为创建单实例时使用，创建多实例请使用 `PodSpecList` 参数。
CustomRouteId	String	否	`cr-xxxx`	自定义路由规则 ID，已调用 AddCustomRoute 接口创建自定义路由规则后，可使用本参数为实例匹配规则。可选的自定义路由规则 ID 可通过 ListCustomRoute 接口查询。说明本参数为创建单实例时使用，创建多实例请使用 `PodSpecList` 参数。需保证为实例匹配的自定义路由规则归属 Zone 与实例所在 Zone 一致。
DNSId	String	否	`dns-7417808334511xxxxxx`	自定义 DNS 规则 ID，已调用 CreateDNSRule 接口创建自定义 DNS 解析规则后，可使用本参数为实例匹配 DNS 规则。可选的 DNS 规则 ID 可通过 ListDNSRule 接口查询。说明本参数为创建单实例时使用，创建多实例请使用 `PodSpecList` 参数。需保证为实例匹配的 DNS 规则归属 Dc 与实例所在 Dc 一致。
PortMappingRuleIdList	Array of String	否	`["7338891742281xxxxxx"]`	端口映射规则 ID 列表，已调用 CreatePortMappingRule 接口创建端口映射规则后，可使用本参数为实例匹配端口映射规则。可选的端口映射规则 ID 可通过 ListPortMappingRule 接口查询。说明本参数为创建单实例时使用，创建多实例请使用 `PodSpecList` 参数。
UsePropertyRule	Integer	否	`1`	是否使用预设的机型参数，已调用 AddPropertyRule 接口创建机型参数规则后，可使用本参数选择是否使用预设机型参数。包含以下取值： 1：使用，此时可以通过 `PropertyRuleName` 参数指定想要使用的机型参数规则。 2：（默认）不使用。
PropertyRuleName	String	否	`HW`	机型参数规则名称。当 `UserPropertyRule` 设置为 1 时，即可使用本参数指定一条预设机型参数规则；若本参数置空，则从机型库中随机选择一条规则。说明对于同一属性，通过 `OverlaySettings`、`OverlayProperty`、`OverlayPersistProperty` 设置的值优先级高于本参数中预设的值。

PodSpec

参数	类型	是否必选	示例值	描述
ApplyNum	Long	是	`1`	创建实例数量。
Dc	String	否	`gdsz-ctcucm-01-9axxxxxx`	机房 ID。说明创建多实例时必填。
ConfigurationCode	String	否	`ultimate`	运行实例的套餐规格 ID，即购买资源时选择或创建的实例规格。当前业务下已购入的实例可选规格可以通过 ListPodResource 接口查询。更多规格信息参看本地存储实例规格列表或云盘存储实例规格列表。说明创建多实例时必填。
HostId	String	否	`h-734016177880xxxxxx`	云机 ID，用于指定实例所归属的云机。当前业务下的可用云机可通过 ListHost 接口查询。若本参数传空，系统将自动分配空余云机。说明本参数仅适用于本地存储方案，即仅当 `ResourceType` 为 `200` 时生效。
PodName	String	否	`新建实例`	实例名称，可自定义。如不指定，则默认与返回的实例 ID 一致。说明创建多实例，此处传值将作为实例名称前缀。
ImageId	String	否	`img-xxxxxx`	自定义镜像 ID，如不指定，则默认使用平台提供的官方标准镜像。
DataSize	String	否	`4Gi`	单个实例预期占用的存储容量，取值范围为 1Gi～128 Gi，且必须为整数。请结合实际业务情况，按需填写存储大小。说明本参数仅适用于云盘存储方案。本地存储方案中，DataSize 为默认固定值，不支持自定义。
DisplayLayoutId	String	否	`single-display-portrait`	屏幕布局 ID，用于指定云手机实例的屏幕显示配置。您可以选择系统提供的屏幕布局，也可以使用通过 CreateDisplayLayoutMini 接口创建的自定义屏幕布局。若使用系统屏幕布局，可选项包括： `single-display-landscape`：1080p 横屏，分辨率 19201080 像素，像素密度 320 dpi，帧率 60fps； `single-display-portrait`：1080p 竖屏，分辨率 10801920 像素，像素密度 320 dpi，帧率 60fps； `single-display-portrait-720p`：高清竖屏，分辨率 7201080 像素，像素密度 320 dpi，帧率 30fps。若使用自定义屏幕布局*，可选项可通过 ListDisplayLayoutMini 接口获取。说明若本参数传空，则各规格实例将使用默认的系统屏幕布局。以下规格实例使用 `single-display-portrait` 1080p 竖屏布局： `common`/`commonPlus`/`commonPro` `enhanced`/`enhancedPlus`/`enhancedPro` `ultimate`/`ultimatePlus`/`ultimatePro` 以下规格实例使用 `single-display-portrait-720p` 高清竖屏布局： `basic`/`basicPlus`/`basicPro` `elementary`/`elementaryPlus`/`elementaryPro` `sample`/`samplePlus`/`samplePro`
OverlaySettings	Array of Settings	否	`-`	实例初始化系统偏好设置。
OverlayProperty	Array of SystemProperty	否	`-`	非持久化系统属性设置，仅在当次实例运行期间有效，重启实例后不予保留。
OverlayPersistProperty	Array of SystemProperty	否	`-`	持久化系统属性设置，长期有效，重启实例后仍旧保留。
Start	Boolean	否	`true`	创建完成后是否立即开机。取值如下： `true`：是； `false`：（默认）否。
TagId	String	否	`tag_01`	标签 ID，已调用 CreateTag 接口创建标签后，可使用本参数为实例添加分组标签。可选的标签 ID 可通过 ListTag 接口查询。
UpBandwidthLimit	Integer	否	`0`	实例上行带宽上限，用于控制云手机发送数据的流量，单位：Mbps。如需设置上行带宽限速，为确保顺畅的浏览和使用体验，建议限速值不低于 5Mbps。默认为 0，即不限速。
DownBandwidthLimit	Integer	否	`0`	实例下行带宽上限，用于控制云手机接收数据的流量，单位：Mbps。如需设置下行带宽限速，为确保顺畅的浏览和使用体验，建议限速值不低于 5Mbps。默认为 0，即不限速。
CustomRouteId	String	否	`cr-****`	自定义路由规则 ID，已调用 AddCustomRoute 接口创建自定义路由规则后，可使用本参数为实例匹配规则。可选的自定义路由规则 ID 可通过 ListCustomRoute 接口查询。说明需保证为实例匹配的自定义路由规则归属 Zone 与实例所在 Zone 一致。
DNSId	String	否	`dns-7417808334511xxxxxx`	自定义 DNS 规则 ID，已调用 CreateDNSRule 接口创建自定义 DNS 解析规则后，可使用本参数为实例匹配 DNS 规则。可选的 DNS 规则 ID 可通过 ListDNSRule 接口查询。说明需保证为实例匹配的 DNS 规则归属 Dc 与实例所在 Dc 一致。
PortMappingRuleIdList	Array of String	否	`["7332794723853xxxxxx","7332794723851xxxxxx"]`	端口映射规则 ID 列表，已调用 CreatePortMappingRule 接口创建端口映射规则后，可使用本参数为实例匹配端口映射规则。可选的端口映射规则 ID 可通过 ListPortMappingRule 接口查询。

Settings

参数	类型	是否必选	示例值	描述
SettingsName	String	是	`locale_language`	属性名称，参考 Settings 属性列表中“属性（key）”一栏。
SettingsType	String	是	`global`	属性类别，取值如下： `global`：全局设置 `secure`：安全设置 `system`：系统设置
SettingsValueType	String	是	`string`	属性参数类型，取值如下： `int` `long` `string` `float` `bool`
SettingsValue	String	是	`on`	属性值，参考 Settings 属性列表中“属性值（value）”一栏中与 `SettingsName` 对应的值。

SystemProperty

参数	类型	是否必选	示例值	描述
SystemPropertyName	String	是	`ro.product.name`	属性名称，参考 System Properties 属性列表中“属性（key）”一栏。
SystemPropertyValue	String	是	`samsung`	属性值，参考 System Properties 属性列表中“属性值（value）”一栏中与 `SystemPropertyName` 对应的值。
SystemPropertyValueType	String	是	`string`	属性参数类型，仅支持 string 类型。

返回参数

下表仅列出本接口特有的返回参数。更多信息请参见返回结构。

参数	类型	示例值	描述
PodId	String	`7294107154305xxxxxx`	创建成功的实例 ID。
PodIdList	Array of String	`[]`	创建成功的实例 ID 列表。

请求示例

POST https://open.volcengineapi.com?Action=CreatePod&Version=2023-10-30
{
    "ProductId": "1696347522856xxxxxx",
    "PodName": "",
    "ConfigurationCode": "sample",
    "ImageId": "img-10xxxxxx",
    "Dc": "tjtj-xxxxxx",
    "DataSize": "8Gi",
    "DisplayLayoutId": "single-display-portrait",
    "OverlaySettings": [
        {
            "SettingsType": "global",
            "SettingsName": "hide_sim_switch",
            "SettingsValue": "1",
            "SettingsValueType": "int"
        }
    ],
    "OverlayProperty": [
        {
            "SystemPropertyName": "ro.product.device",
            "SystemPropertyValue": "xxxxxx",
            "SystemPropertyValueType": "string"
        }
    ],
    "OverlayPersistProperty": [
        {
            "SystemPropertyName": "ro.product.brand",
            "SystemPropertyValue": "xxxxxxx",
            "SystemPropertyValueType": "string"
        }
    ],
    "TagId": "7296180990720xxxxxx",
    "UpBandwidthLimit": 0,
    "DownBandwidthLimit": 0,
    "PortMappingRuleIdList": [
        "7338891742281xxxxxx"
    ],
    "Start": true
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "2023060411042***32280022D31",
        "Action": "CreatePod",
        "Version": "2023-10-30",
        "Service": "ACEP",
        "Region": "cn-north-1"
    },
    "Result": {
        "PodId": "7294107154305xxxxxx",
        "PodIdList": []
    }
}

错误码

您可访问公共错误码，获取更多错误码信息。