# 创建云手机

购买并开通一台或多台云手机。
- **前置条件**：套餐必须有剩余额度，且当日创建配额未用尽。`country`、`timezone`、`language` 会按所选机型支持的列表校验，不支持的组合会被拒绝而不是被静默调整。经度限 ±180、纬度限 ±90。所选 SKU 不支持手机号时，传入的手机号会被丢弃。包月 SKU 可通过 API 创建，但必须是 [`/cloudphone/monthly/skus`](./open-api.yaml#operation/listMonthlyCloudPhoneSkus) 返回的商品；当前周期为 30 天。
- **副作用**：创建云手机记录。按量计费的 SKU 完成开通后可用；包月 SKU 创建后处于未激活状态。创建操作本身不扣费；包月云手机仅在调用 [`/cloudphone/monthly/activate`](./open-api.yaml#operation/activateMonthlyCloudPhones) 时扣费，按量云手机则在开机后开始消耗余额或额度。
- **完成信号**：**已受理，未完成。** 此时云手机实例尚未就绪，过早开机会被拒绝。请轮询 [`/cloudphone/info`](./open-api.yaml#operation/infoUsingPOST) 或 [`/cloudphone/page`](./open-api.yaml#operation/pageUsingPOST) 直到 `envStatus` 变为已关机。对于包月 SKU，还必须先完成 [`/cloudphone/monthly/activate`](./open-api.yaml#operation/activateMonthlyCloudPhones) 才能开机。
- **重试**：不幂等，且没有串行化。没有幂等键。超时后不要盲目重试，先查询状态。

已记录的业务错误码：`19064`, `20018`, `33338`, `33339`, `33340`, `33341`, `33342`, `33343`, `33344`, `33345`, `33398`, `33399`, `33400`, `33408`。 各错误码的含义见 [Error Codes](../Getting%20Started/error-codes.md)。任何接口还可能返回通用错误码。

Endpoint: POST /cloudphone/create
Version: 2026-09-05
Security: Authorization

## Security:

  - `Authorization` (unknown)
    http bearer JWT

## Request fields (application/json):

  - `skuId` (string, required)
    云手机机型
skuId:10002 model:Android 12
skuId:10013 model:Android 13
skuId:10005 model:Android 14
skuId:10004 model:Android 15
skuId:10014 model:Android 15A
skuId:10015 model:Android 16
支持的地区与时区映射见[国家与时区对照表](/api-reference/appendix/country-time-zone)

  - `quantity` (integer, required)
    创建的云手机数量。取值范围：[1-10]

  - `envRemark` (string)
    备注（长度上限 1500 字符）

  - `groupId` (string)
    分组 ID。未分组填 `"0"`。

  - `groupName` (string)
    已有分组名称；若没有匹配的分组，则按该名称新建。

  - `automaticGeo` (boolean)
    是否自动匹配地理位置。默认：true

  - `automaticLanguage` (boolean)
    是否自动匹配语言。默认：true

  - `automaticLocation` (boolean)
    是否自动匹配位置（时区、国家）。默认：true

  - `country` (string)
    国家代码（例如 `us`）。完整清单见[国家与时区对照表](/api-reference/appendix/country-time-zone)

  - `timezone` (string)
    时区，例如 America/New_York

  - `language` (string)
    语言，例如 en-US

  - `altitude` (number)
    海拔

  - `latitude` (number)
    纬度。示例：22.309182

  - `longitude` (number)
    经度。示例：114.176817

  - `speed` (number)
    移动速度

  - `bearing` (number)
    移动方向

  - `accuracy` (number)
    水平精度

  - `phoneNumber` (string)
    自定义手机号。格式要求：必须以 + 号开头，国家代码为 1-3 位数字（不含 86），总长度 8-14 位，且只能包含 + 与数字。

  - `brand` (string)
    设备品牌，可通过 https://guide.morelogin.com/api-reference/open-api/open-api/cloud-phone/paths/~1cloudphone~1brand~1models/post 接口查询。

  - `modelId` (number)
    设备型号 ID，可通过 https://guide.morelogin.com/api-reference/open-api/open-api/cloud-phone/paths/~1cloudphone~1brand~1models/post 接口查询。

  - `proxyId` (string)
    代理 ID

  - `tags` (array)
    标签名称。空值会被忽略。

## Response 200:

  - `200` (unknown)
    好的

## Response 200 fields (application/json):

  - `code` (integer, required)

  - `msg` (string | null, required)

  - `data` (array)
    这是云手机IDS

  - `requestId` (string, required)

  - `error` (object)