# Cloud Phone Management

Cloud Phone Management 相关 API。

 - [POST /cloudphone/setTags/batch](https://guide.morelogin.com/zh/api-reference/cloud-phone/open-api/cloud-phone-management/setcloudphonetagsopen.md): 覆盖所选资源的标签。需要标签管理权限及目标资源访问权限。按团队内的精确名称匹配标签：不存在则创建，已存在则复用并更新颜色；颜色变化也会影响使用同一标签的其他资源。请求中的标签名称不能重复。`tags` 传空数组仅清空标签关联，保留标签定义与分组。同步完成，`data` 为 null。超时后先查询目标资源及 `/envtag/all` 再决定是否重试；接口没有幂等键。 已记录的业务错误码：`1500
 - [POST /cloudphone/page](https://guide.morelogin.com/zh/api-reference/cloud-phone/open-api/cloud-phone-management/pageusingpost.md): 分页列出团队可见的云手机。 - **副作用**：无。只读。可带退避安全重试。 - **说明**：会返回所有设备类型的云手机。托管代理与动态代理的密码会从响应中移除。 - **用途**：本接口与 `/cloudphone/info` 是开关机、一键新机和开通这几个异步操作的完成信号。
 - [POST /cloudphone/link](https://guide.morelogin.com/zh/api-reference/cloud-phone/open-api/cloud-phone-management/createcloudphoneremotelink.md): 创建云手机临时网页访问链接（仅 Open API）。 - **前提**：云手机须属于当前团队，调用成员具有资源权限，已开机且未被其他成员占用。本接口不会自动开机。 - **效果**：每次调用生成新链接，不申请连接凭证，也不改变当前连接。在浏览器打开 `data.url`，或将完整 URL 生成二维码使用。 - **有效期**：从生成起固定 5 分钟，重复访问不消耗链接、不续期；到期后重新调用本接口
 - [POST /cloudphone/create](https://guide.morelogin.com/zh/api-reference/cloud-phone/open-api/cloud-phone-management/createusingpost.md): 购买并开通一台或多台云手机。 - **前置条件**：套餐必须有剩余额度，且当日创建配额未用尽。`country`、`timezone`、`language` 会按所选机型支持的列表校验，不支持的组合会被拒绝而不是被静默调整。经度限 ±180、纬度限 ±90。所选 SKU 不支持手机号时，传入的手机号会被丢弃。包月 SKU 可通过 API 创建，但必须是 [`/cloudphone/monthly/
 - [POST /cloudphone/powerOn](https://guide.morelogin.com/zh/api-reference/cloud-phone/open-api/cloud-phone-management/poweronusingpost.md): 启动云手机。 - **前置条件**：云手机当前必须处于已关机状态。以下情况会被拒绝：SKU 已下架或处于维护、云手机被其他成员占用、代理仍在检测中、账户欠费或云手机已停用、包月已到期，以及免费时长、并发额度、正余额三者都不可用。部分机型还要求使用最新版 Windows 客户端。 - **副作用**：把云手机标记为启动中、占用给调用成员，并预留一个并发额度或开始消耗时长。响应会说明用的是哪一种。 -
 - [POST /cloudphone/restart](https://guide.morelogin.com/zh/api-reference/cloud-phone/open-api/cloud-phone-management/restartcloudphone.md): 重启整台云手机。终止正在执行的 AI 任务，并清理进行中的应用安装记录。 通过 `id` 操作单台云手机。调用方须有该手机的操作权限；手机须已激活、未释放、不在转移中、处于开机状态（`envStatus=4`），且未被其他成员占用。成功返回 `data: null`，不返回任务 ID，仅表示提交成功，不表示操作完成。限时轮询 `/cloudphone/info` 或 `/cloudphone/pa
 - [POST /cloudphone/reset](https://guide.morelogin.com/zh/api-reference/cloud-phone/open-api/cloud-phone-management/resetcloudphone.md): **数据清理警告：** 重置会清理手机数据和应用安装记录，并终止正在执行的 AI 任务。请先备份所需数据；该操作不同于一键新机。 通过 `id` 操作单台云手机。调用方须有该手机的操作权限；手机须已激活、未释放、不在转移中、处于开机状态（`envStatus=4`），且未被其他成员占用。成功返回 `data: null`，不返回任务 ID，仅表示提交成功，不表示操作完成。限时轮询 `/cloudp
 - [POST /cloudphone/powerOff](https://guide.morelogin.com/zh/api-reference/cloud-phone/open-api/cloud-phone-management/poweroffusingpost.md): 关闭云手机。 - **前置条件**：云手机必须处于启动中或已开机。被其他成员占用时，或正在一键新机、重启、重置时，无法关机。 - **副作用**：停止计费、释放并发额度、结算用量，并让本次会话签发的连接凭据失效。对仍在启动中的云手机执行关机，会改为中断启动。 - **完成信号**：计费与本地状态在同步事务内结算完成；设备关机随后进行，请用 `/cloudphone/info` 确认。 - **重试
 - [POST /cloudphone/edit/batch](https://guide.morelogin.com/zh/api-reference/cloud-phone/open-api/cloud-phone-management/editbatchusingpost.md): 更新一台或多台云手机的配置。 - **前置条件**：云手机必须属于你的团队。地区、语言和坐标会按机型校验，规则与创建时一致。把云手机移入你没有权限的分组会被拒绝。 - **副作用**：覆盖云手机设置并刷新 GPS 配置；可能创建标签绑定。不扣费，不影响并发额度。 - **完成信号**：同步，相同请求体幂等。
 - [POST /cloudphone/setProxy](https://guide.morelogin.com/zh/api-reference/cloud-phone/open-api/cloud-phone-management/setproxy.md): 为一台或多台云手机绑定代理。 - **前置条件**：`ids` 与 `uniqueIds` 至少提供一个。云手机必须属于你的团队，**不需要**已开机。传入的 `proxyId` 必须存在，否则调用被拒绝。 - **副作用**：当 `proxyId` 省略或为 `0` 时，会复用连接信息完全相同的已有代理；**若没有匹配项，则在你的团队中新建一条代理记录**。代理检测状态会被重置，上一个代理会被记
 - [POST /cloudphone/delete/batch](https://guide.morelogin.com/zh/api-reference/cloud-phone/open-api/cloud-phone-management/deleteusingpost.md): 释放一台或多台云手机。 - **前置条件**：云手机不能处于转移中，且团队对它们没有未支付订单。云手机不需要先关机。 - **副作用**：云手机实例立即释放。从未激活的云手机会被直接删除；已激活的会保留为已停用记录，因此仍会出现在列表里并带有停用状态。 - **完成信号**：同步。 - **重试**：云手机逐台处理，遇到第一个失败即中止，因此批量可能部分生效。重试前请重新读取 `/cloudpho
 - [POST /cloudphone/newMachine](https://guide.morelogin.com/zh/api-reference/cloud-phone/open-api/cloud-phone-management/onenewusingpost.md): 原地更换云手机的设备标识（一键新机）。 - **前置条件**：云手机必须已开机且未被其他成员占用。传入的品牌与机型必须是该云手机 SKU 支持的。**本操作会消耗当日云手机创建配额**，与 `/cloudphone/create` 用的是同一个配额。 - **副作用**：向设备下发新的品牌与机型、清空该机的已安装应用记录、重置手机号、并中止正在运行的 AI 任务。具体重新生成的标识范围取决于设备类
 - [POST /cloudphone/info](https://guide.morelogin.com/zh/api-reference/cloud-phone/open-api/cloud-phone-management/infousingpost.md): 返回单台云手机的完整详情，含分组名与标签名。 - **副作用**：无。只读。可带退避安全重试。 - **用途**：异步操作的主要状态查询接口。`envStatus` 区分新建、创建失败、已关机、启动中、已开机、重置中、重启中、一键新机中；异步操作失败时，原因由 `errorCode` 与 `errorMsg` 给出。
 - [POST /cloudphone/queryByAndroidId](https://guide.morelogin.com/zh/api-reference/cloud-phone/open-api/cloud-phone-management/querybyandroidid.md): 通过设备上报的 Android ID 查找云手机。 - **副作用**：无。只读。可带退避安全重试。 云手机不需要已开机。 - **返回**：与 `/cloudphone/info` 相同的详情结构。 - **边界情况**：`androidId` 为空时返回成功但 `data` 为 null，而不是参数校验错误；若多台云手机共用同一个 Android ID，则任意返回其中一台。
 - [POST /cloudphone/enableRoot](https://guide.morelogin.com/zh/api-reference/cloud-phone/open-api/cloud-phone-management/enableroot.md): 打开或关闭云手机的全局 ROOT 开关。 - **前置条件**：云手机必须已开机且未被其他成员占用。仅兼容机型支持；不兼容机型调用成功但无效果。 - **副作用**：与 `/cloudphone/app/openRoot` 不同，这个设置**会被持久化**到云手机的设置记录，然后作为设备级开关下发给设备服务。 - **完成信号**：同步。MoreLogin 不会重启云手机；变更何时在设备上生效由设
 - [POST /cloudphone/screenCap](https://guide.morelogin.com/zh/api-reference/cloud-phone/open-api/cloud-phone-management/screencap.md): 截取云手机屏幕并返回下载地址。 - **前置条件**：云手机必须已开机且未被其他成员占用。仅兼容机型支持，不兼容机型会拒绝该调用。 - **副作用**：在部分机型上，截图文件在拍摄后会从设备中删除。 - **完成信号**：同步。响应包含临时图片下载地址。 - **注意**：在部分机型上返回的过期时间是响应时刻起固定一小时、`success` 恒为 true——它不是真实的签名有效期。请及时下载，不
 - [POST /cloudphone/screenCapBase64](https://guide.morelogin.com/zh/api-reference/cloud-phone/open-api/cloud-phone-management/screencapbase64.md): 截取云手机屏幕并以 base64 内联返回图片。 - **前置条件**：云手机必须已开机且未被其他成员占用。**仅兼容机型支持**——不兼容机型都会拒绝该调用。 - **完成信号**：同步。失败时响应携带错误信息而不是图片数据，所以解码前请先检查 `success`。 - **机型支持**：文档记载仅 Android 12 与 Android 15 镜像可用。 - **用途**：当你不想依赖设备服
 - [POST /cloudphone/brand/models](https://guide.morelogin.com/zh/api-reference/cloud-phone/open-api/cloud-phone-management/cloudphonebrandmodelspost.md): 列出某个云手机 SKU 支持的设备品牌与机型。 - **副作用**：无。只读。可带退避安全重试。 不涉及具体云手机。 - **用途**：在调用 `/cloudphone/create` 或 `/cloudphone/newMachine` 之前选一个合法的 `brand` 与 `modelId`——这两个接口都会拒绝本接口未返回的组合。 - **说明**：未知的 `skuId` 返回空列表而不是报