# 云手机直播

可以通过开放 API 或本地 API 上传一个 MP4 文件、开始直播、查询状态并结束直播。

## 接口路径

| 操作 | 开放 API | 本地 API |
|  --- | --- | --- |
| 查询余额及余量 | `GET /balance` | `GET /api/balance` |
| 开始直播 | `POST /cloudphone/live/start` | `POST /api/cloudphone/live/start` |
| 查询直播状态 | `POST /cloudphone/live/status` | `POST /api/cloudphone/live/status` |
| 结束直播 | `POST /cloudphone/live/end` | `POST /api/cloudphone/live/end` |


## 前置条件

- 使用无印或小算云手机；其他供应商当前会返回 `33401`。
- 开始或结束直播前先将云手机开机。
- 获取 OAuth2 Bearer Token，并确保当前成员具有该云手机的操作权限。
- 直播文件必须是 MP4，并以 `uploadType=2` 上传。


## 开放 API 调用流程

1. 调用 `POST /cloudphone/uploadUrl`，再使用 HTTP `PUT` 将 MP4 内容上传到返回的 `presignedUrl`。
2. 调用 `POST /cloudphone/uploadFile`，传入文件地址、目标目录和 `uploadType: 2`。
3. 轮询 `POST /cloudphone/uploadFileResult`。如果 `data` 为 `null`，表示文件记录尚未可见，应继续轮询；当 `data.status` 为 `1`（成功）或 `2`（失败）时停止。
4. 保存字符串类型的 `data.fileId`，并将其精确数值作为 `int64` 传给 `POST /cloudphone/live/start`。JavaScript 等客户端应使用支持任意精度整数的序列化方式，不能先转换为 `Number`。


```json
{
  "phoneId": 190000000000000001,
  "fileId": 820000000000000001
}
```

使用 `POST /cloudphone/live/status` 查询直播状态，使用 `POST /cloudphone/live/end` 结束直播。这两个接口均接收 `{ "phoneId": 190000000000000001 }`。

## 本地 API 调用流程

1. 调用 `POST /api/cloudphone/upload/file/signedUrl`，再使用 HTTP `PUT` 将 MP4 内容上传到返回的 `presignedUrl`。
2. 调用 `POST /api/cloudphone/upload/file`，传入文件地址、目标目录和 `uploadType: 2`。
3. 轮询 `POST /api/cloudphone/upload/file/result`。如果 `data` 为 `null`，应继续轮询；当 `data.status` 为 `1` 或 `2` 时停止。
4. 将返回的 `data.fileId` 精确数值传给 `POST /api/cloudphone/live/start`；使用 `/api/cloudphone/live/status` 和 `/api/cloudphone/live/end` 查询或结束直播。


完整请求和响应结构参见[云手机开放 API](/zh/api-reference/cloud-phone/open-api)和[云手机本地 API](/zh/api-reference/cloud-phone/local-api)。

## 重试与错误处理

开始直播请求超时后，应先查询状态再决定是否重试，不能将超时直接视为启动失败。

| 错误码 | 含义 |
|  --- | --- |
| `33300` | 云手机不存在 |
| `33301` | 云手机未开机 |
| `33401` | 当前云手机不支持直播 |
| `33418` | 直播文件不存在或已失效 |
| `33419` | `/cloudphone/uploadFile` 拒绝了非 MP4 的直播文件 |
| `99002` | 当前成员无权操作该云手机 |