You need to enable JavaScript to run this app.
导航
云手机
  • 文档首页
    • /云手机/服务端 OpenAPI 文档/实例管理/创建实例 CreatePod
创建实例 CreatePod
最近更新时间：2025.10.29 16:13:57首次发布时间：2025.10.28 15:01:09
复制全文
我的收藏
有用
有用
无用
无用

创建指定套餐规格配置的实例，支持单个实例创建及批量实例创建。

使用说明

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

注意事项

  • 若传入的业务 ID（即 ProductId）对应本地存储方案，则无论创建单个实例还是批量创建多个实例，ResourceType 参数必填，取值为 200。
  • 本接口的单用户 QPS 限制为 50 次/秒。超过限制，API 调用会被限流。

请求说明

  • 请求方式：POST
  • 请求地址：https://open.volcengineapi.com?Action=CreatePod&Version=2025-05-01

请求参数

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

Query

参数类型是否必选示例值描述
ActionString是CreatePod接口名称。当前 API 的名称为 CreatePod。
VersionString是2025-05-01接口版本。当前 API 的版本为 2025-05-01。

Body

参数类型是否必选示例值描述
ProductIdString是1591495366954xxxxxx业务 ID，管理云手机资源、开展云手机业务的标识。可登录云手机控制台，在已创建的业务卡片中获取。

PodName

String

否

pod-xxxxxx

实例名称，可自定义。如不指定，则默认与返回的实例 ID 一致。

说明

本参数为创建单实例时使用，创建多实例请使用 PodSpecList 参数。

ImageId

String

否

gdsz-ctcucm-01-9axxxxxx

自定义镜像 ID，如不指定，则默认使用平台提供的官方标准镜像。

说明

本参数为创建单实例时使用，创建多实例请使用 PodSpecList 参数。

ConfigurationCode

String

否

ultimate

运行实例的套餐规格 ID，即购买资源时选择或创建的实例规格。
当前业务下已购入的实例可选规格可以通过 ListPodResource 接口查询。
更多规格信息参看本地存储实例规格列表或云盘存储实例规格列表。

说明

本参数创建单实例时必填，创建多实例请使用 PodSpecList 参数。

DataSize

String

否

8Gi

单个实例预期占用的存储容量，取值范围为 1Gi～128 Gi，且必须为整数。请结合实际业务情况，按需填写存储大小。

说明

本参数仅适用于云盘存储方案。本地存储方案中，DataSize 为默认固定值，不支持自定义。

Dc

String

否

gdsz-ctcucm-01-xxxxxxxx

机房 ID。

说明

本参数为创建单实例时必填，创建多实例请使用 PodSpecList 参数。

DisplayLayoutId

String

否

single-display-landscape

屏幕布局 ID，用于指定云手机实例的屏幕显示配置。
您可以选择系统提供的屏幕布局，也可以使用通过 CreateDisplayLayoutMini 接口创建的自定义屏幕布局。

  • 若使用系统屏幕布局，可选项包括：
    • single-display-landscape：1080p 横屏，分辨率 1920*1080 像素，像素密度 320 dpi，帧率 60fps；
    • single-display-portrait：1080p 竖屏，分辨率 1080*1920 像素，像素密度 320 dpi，帧率 60fps；
    • single-display-portrait-720p：高清竖屏，分辨率 720*1080 像素，像素密度 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

否

true

创建完成后是否立即开机。取值如下：

  • true：是；
  • false：（默认）否。

说明

本参数为创建单实例时使用，创建多实例请使用 PodSpecList 参数。

TagId

String

否

7658996557xxxxxx

标签 ID，已调用 CreateTag 接口创建标签后，可使用本参数为实例添加分组标签。
可选的标签 ID 可通过 ListTag 接口查询。

说明

本参数为创建单实例时使用，创建多实例请使用 PodSpecList 参数。

UpBandwidthLimit

Integer

否

100

实例上行带宽上限，用于控制云手机发送数据的流量，单位：Mbps。
如需设置上行带宽限速，为确保顺畅的浏览和使用体验，建议限速值不低于 5Mbps。
默认为 0，即不限速。

说明

本参数为创建单实例时使用，创建多实例请使用 PodSpecList 参数。

DownBandwidthLimit

Integer

否

100

实例下行带宽上限，用于控制云手机接收数据的流量，单位：Mbps。
如需设置下行带宽限速，为确保顺畅的浏览和使用体验，建议限速值不低于 5Mbps。
默认为 0，即不限速。

说明

本参数为创建单实例时使用，创建多实例请使用 PodSpecList 参数。

CustomRouteId

String

否

7658996557xxxxxx

自定义路由规则 ID，已调用 AddCustomRoute 接口创建自定义路由规则后，可使用本参数为实例匹配规则。
可选的自定义路由规则 ID 可通过 ListCustomRoute 接口查询。

说明

  1. 本参数为创建单实例时使用，创建多实例请使用 PodSpecList 参数。
  2. 需保证为实例匹配的自定义路由规则归属 Zone 与实例所在 Zone 一致。

DNSId

String

否

dns-xxxxxx

自定义 DNS 规则 ID，已调用 CreateDNSRule 接口创建自定义 DNS 解析规则后，可使用本参数为实例匹配 DNS 规则。
可选的 DNS 规则 ID 可通过 ListDNSRule 接口查询。

说明

  • 本参数为创建单实例时使用，创建多实例请使用 PodSpecList 参数。
  • 需保证为实例匹配的 DNS 规则归属 Dc 与实例所在 Dc 一致。

PodSpecList

Array of PodSpec

否

-

多实例配置项，用于在创建多实例时，指定实例的自定义配置。

说明

创建多实例时必填。

PortMappingRuleIdList

Array of String

否

["7338891742281xxxxxx"]

端口映射规则 ID 列表，已调用 CreatePortMappingRule 接口创建端口映射规则后，可使用本参数为实例匹配端口映射规则。
可选的端口映射规则 ID 可通过 ListPortMappingRule 接口查询。

说明

本参数为创建单实例时使用，创建多实例请使用 PodSpecList 参数。

IPWhiteList

String

否

10.xx.xx.02,10.xx.xx.03

私有参数。支持配置白名单 IP，对白名单 IP 不限速。同时对 pod 访问的其他 IP 进行整体限速。以 ',' 分割。

说明

本参数为创建单实例时使用，创建多实例请使用 PodSpecList 参数。

ResourceType

Integer

否

200

实例所属业务对应的存储方案类型。
本参数默认为云盘存储方案，取值为 100。若当前业务（ProductId）对应本地存储方案，则本参数必填，取值为 200。

说明

无论创建单实例还是多实例，只要使用本地存储方案，本参数必填 200。

HostId

String

否

7337159054625xxxxxx

云机 ID，用于指定实例所归属的云机。
当前业务下的可用云机可通过 ListHost 接口查询。若本参数传空，系统将自动分配空余云机。

说明

  • 本参数仅适用于本地存储方案，即仅当 ResourceType 为 200 时生效。
  • 本参数为创建单实例时使用，创建多实例请使用 PodSpecList 参数。

UsePhoneTemplate

Integer

否

1

是否使用预设的机型库，已调用 AddPhoneTemplate 接口创建机型库后，可使用本参数选择是否使用预设机型参数。包含以下取值：

  • 1：使用，此时可以通过 PhoneTemplateId 参数指定想要使用的机型库。
  • 2：（默认）不使用。

PhoneTemplateId

String

否

7658996557xxxxxx

机型库 ID。当 UsePhoneTemplate 设置为 1 时，即可使用本参数指定已发布的机型库；若本参数置空，则从已发布的机型库中随机选择一个使用。
您可以调用 ListPhoneTemplate 接口查询已发布（Status 参数传值 1 表示已发布）的机型库列表。

说明

对于同一属性，通过 OverlaySettings、OverlayProperty、OverlayPersistProperty 设置的值优先级高于本参数中预设的值。

Settings

参数类型是否必选示例值描述
SettingsNameString是locale_language属性名称，已可修改的 Settings 属性及属性值，参考 Settings 属性列表。

SettingsType

String

是

global

设置类型，取值如下：

  • global
  • secure
  • system

SettingsValue

String

是

zh-CN

属性值数据类型，取值如下：

  • int
  • long
  • string
  • float
  • bool

SettingsValueType

String

是

string

属性值。各类型属性取值示例如下：

  • bool: "true"、"false"
  • int\long: "21312"
  • float: "2131.09"
  • string: "safehg"

SystemProperty

参数类型是否必选示例值描述
SystemPropertyNameString是ro.product.name属性名称，已可修改的系统属性及属性值，参考 System Properties 属性列表。
SystemPropertyValueString是samsung属性值。

SystemPropertyValueType

String

是

string

属性值数据类型。取值如下：

  • int
  • long
  • string
  • float
  • bool

PodSpec

参数类型是否必选示例值描述

Dc

String

否

gdsz-ctcucm-01-9axxxxxx

机房 ID。

说明

创建多实例时必填。

DNSId

String

否

dns-xxxxxx

自定义 DNS 规则 ID，已调用 CreateDNSRule 接口创建自定义 DNS 解析规则后，可使用本参数为实例匹配 DNS 规则。
可选的 DNS 规则 ID 可通过 ListDNSRule 接口查询。

说明

需保证为实例匹配的 DNS 规则归属 Dc 与实例所在 Dc 一致。

Start

Boolean

否

true

创建完成后是否立即开机。取值如下：

  • true：是；
  • false：（默认）否。

TagId

String

否

7658996557xxxxxx

标签 ID，已调用 CreateTag 接口创建标签后，可使用本参数为实例添加分组标签。
可选的标签 ID 可通过 ListTag 接口查询。

HostIdString否7658996557xxxxxx云机 ID，用于指定实例所归属的云机。当前业务下的可用云机可通过 ListHost 接口查询。若本参数传空，系统将自动分配空余云机。
ImageIdString否img-xxxxxx自定义镜像 ID，如不指定，则默认使用平台提供的官方标准镜像。

PodName

String

否

新建实例

实例名称，可自定义。如不指定，则默认与返回的实例 ID 一致。

说明

创建多实例，此处传值将作为实例名称前缀。

ApplyNumLong是1创建实例数量。

DataSize

String

否

100Gi

单个实例预期占用的存储容量，取值范围为 1Gi～128 Gi，且必须为整数。请结合实际业务情况，按需填写存储大小。

说明

本参数仅适用于云盘存储方案。本地存储方案中，DataSize 为默认固定值，不支持自定义。

IPWhiteListString否10.xx.xx.02,10.xx.xx.03私有参数。支持配置白名单 IP，对白名单 IP 不限速。同时对 pod 访问的其他 IP 进行整体限速。以 ',' 分割。

CustomRouteId

String

否

r-xxxxxx

自定义路由规则 ID，已调用 AddCustomRoute 接口创建自定义路由规则后，可使用本参数为实例匹配规则。
可选的自定义路由规则 ID 可通过 ListCustomRoute 接口查询。

说明

需保证为实例匹配的自定义路由规则归属 Zone 与实例所在 Zone 一致。

DisplayLayoutId

String

否

single-display-portrait

屏幕布局 ID，用于指定云手机实例的屏幕显示配置。
您可以选择系统提供的屏幕布局，也可以使用通过 CreateDisplayLayoutMini 接口创建的自定义屏幕布局。

  • 若使用系统屏幕布局，可选项包括：
    • single-display-landscape：1080p 横屏，分辨率 1920*1080 像素，像素密度 320 dpi，帧率 60fps；
    • single-display-portrait：1080p 竖屏，分辨率 1080*1920 像素，像素密度 320 dpi，帧率 60fps；
    • single-display-portrait-720p：高清竖屏，分辨率 720*1080 像素，像素密度 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
OverlayPropertyArray of SystemProperty否-非持久化系统属性设置，仅在当次实例运行期间有效，重启实例后不予保留。
OverlaySettingsArray of Settings否-实例初始化系统偏好设置。
PhoneTemplateIdString否7658996557xxxxxx机型库 ID。

UpBandwidthLimit

Integer

否

100

实例上行带宽上限，用于控制云手机发送数据的流量，单位：Mbps。
如需设置上行带宽限速，为确保顺畅的浏览和使用体验，建议限速值不低于 5Mbps。
默认为 0，即不限速。

ConfigurationCode

String

否

ultimate

运行实例的套餐规格 ID，即购买资源时选择或创建的实例规格。
当前业务下已购入的实例可选规格可以通过 ListPodResource 接口查询。
更多规格信息参看本地存储实例规格列表或云盘存储实例规格列表。

说明

创建多实例时必填。

DownBandwidthLimit

Integer

否

100

实例下行带宽上限，用于控制云手机接收数据的流量，单位：Mbps。
如需设置下行带宽限速，为确保顺畅的浏览和使用体验，建议限速值不低于 5Mbps。
默认为 0，即不限速。

PortMappingRuleIdList

Array of String

否

["7332794723853xxxxxx","7332794723851xxxxxx"]

端口映射规则 ID 列表，已调用 CreatePortMappingRule 接口创建端口映射规则后，可使用本参数为实例匹配端口映射规则。
可选的端口映射规则 ID 可通过 ListPortMappingRule 接口查询。

OverlayPersistPropertyArray of SystemProperty否-持久化系统属性设置，长期有效，重启实例后仍旧保留。

返回参数

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

参数类型示例值描述
PodIdString7294107154305xxxxxx创建成功的实例 ID。
PodIdListArray of String[]创建成功的实例 ID 列表。

请求示例

POST https://open.volcengineapi.com?Action=CreatePod&Version=2025-05-01
{
    "ProductId": "1591495366954xxxxxx",
    "PodName": "pod-xxxxxx",
    "ImageId": "gdsz-ctcucm-01-9axxxxxx",
    "ConfigurationCode": "ultimate",
    "DataSize": "8Gi",
    "Dc": "gdsz-ctcucm-01-xxxxxxxx",
    "DisplayLayoutId": "single-display-landscape",
    "OverlaySettings": [
        {
            "SettingsName": "locale_language",
            "SettingsType": "global",
            "SettingsValue": "zh-CN",
            "SettingsValueType": "string"
        }
    ],
    "OverlayProperty": [
        {
            "SystemPropertyName": "ro.product.name",
            "SystemPropertyValue": "samsung",
            "SystemPropertyValueType": "string"
        }
    ],
    "OverlayPersistProperty": [
        {
            "SystemPropertyName": "ro.product.name",
            "SystemPropertyValue": "samsung",
            "SystemPropertyValueType": "string"
        }
    ],
    "Start": true,
    "TagId": "7658996557xxxxxx",
    "UpBandwidthLimit": 100,
    "DownBandwidthLimit": 100,
    "CustomRouteId": "7658996557xxxxxx",
    "DNSId": "dns-xxxxxx",
    "PodSpecList": [
        {
            "Dc": "gdsz-ctcucm-01-9axxxxxx",
            "DNSId": "dns-xxxxxx",
            "Start": true,
            "TagId": "7658996557xxxxxx",
            "HostId": "7658996557xxxxxx",
            "ImageId": "img-xxxxxx",
            "PodName": "新建实例",
            "ApplyNum": 1,
            "DataSize": "100Gi",
            "IPWhiteList": "10.xx.xx.02,10.xx.xx.03",
            "CustomRouteId": "r-xxxxxx",
            "DisplayLayoutId": "single-display-portrait",
            "OverlayProperty": [],
            "OverlaySettings": [],
            "PhoneTemplateId": "7658996557xxxxxx",
            "UpBandwidthLimit": 100,
            "ConfigurationCode": "ultimate",
            "DownBandwidthLimit": 100,
            "PortMappingRuleIdList": [
                "7332794723853xxxxxx",
                "7332794723851xxxxxx"
            ],
            "OverlayPersistProperty": []
        }
    ],
    "PortMappingRuleIdList": [
        "7338891742281xxxxxx"
    ],
    "IPWhiteList": "10.xx.xx.02,10.xx.xx.03",
    "ResourceType": 200,
    "HostId": "7337159054625xxxxxx",
    "UsePhoneTemplate": 1,
    "PhoneTemplateId": "7658996557xxxxxx"
}

返回示例

{
    "ResponseMetadata": {
        "Action": "CreatePod",
        "Region": "cn-north-1",
        "Service": "ACEP",
        "Version": "2025-05-01",
        "RequestId": "20230604110420****100232280022D31"
    },
    "Result": {
        "PodId": "7294107154305xxxxxx",
        "PodIdList": []
    }
}

错误码

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