使用个人 API Key 查询云手机、代理及应用,并提交一键新机、绑定已有代理和安装应用。本文覆盖六个客户接口;正式服务地址为 https://api.foxphone.com,基础路径为 /public_api/v1。
| HTTP | /public_api/v1 | 说明 |
|---|---|---|
| GET | /phones | 查询云手机 |
| GET | /proxies | 查询代理 |
| POST | /phones/actions/reset | 批量一键新机 |
| POST | /proxies/{proxy_id}/bind | 批量绑定已有代理 |
| GET | /apps | 查询应用及版本 |
| POST | /phones/actions/install-app | 批量安装应用 |
在控制台右上角头像菜单进入 Settings,然后打开个人中心的 API Key 页面生成密钥。每个账号仅一个有效 Key;重新生成后旧 Key 立即失效,完整 Key 仅生成时展示一次。所有请求使用 X-API-Key;POST 另加 Content-Type: application/json。不需要网页登录 JWT、Cookie、Device-ID、hash 或 platform;Bearer Token 不能代替此请求头。
X-API-Key: <your_api_key>将密钥保存在服务端的环境变量或密钥管理系统,不嵌入前端、公开仓库或客户端。不要写入 URL、请求体、日志或工单;示例用环境变量 API_KEY。在可信环境生成和保存,泄露时立即轮换或禁用,并更新所有调用方。轮换后旧 Key 无效,禁用后请求被拒绝。
export API_KEY="<your_api_key>"使用 HTTPS。成功时 HTTP 200,业务数据位于 data 内;失败使用 HTTP 4xx/5xx 和字符串 reason。按 HTTP 状态、reason 及逐项结果判断,不能只检查 message。错误的 data 可以为 null,排查保留 request_id。个人 Key 与合作方 /open_api/v1 凭证体系不同,不能混用。
同一个 Key 的请求共用每分钟 60 次额度。分页 page_num/page_size 未传或非正数按 1/20;page_size 最大 100,超出返回 400。手机、代理用 search,应用用 app_name。批量 pod_ids 为字符串数组,去空、去首尾空白和去重后须为 1–100 项;返回顺序不保证相同,按 pod_id 匹配。
pod_id 始终按字符串处理。proxy_id、total、版本 id 与 version_code 当前返回 JSON 数字;大整数应采用无损解析,避免 JavaScript 精度丢失。响应保留零和空字符串;空列表可能为 [] 或 null,客户端应兼容。
{
"request_id": "example-request-id",
"code": 200,
"data": {
"total": 0,
"phones": []
},
"message": "success"
}查询当前账号手机,search 可按名称或 pod_id 模糊匹配。data.phones 包含 pod_id、name、online_status、operating_status、proxy_id;data.total 为总数。proxy_id=0 表示未关联代理;关联值不能证明云端绑定已完成。
online_status:0 启动中、1 运行中、2 已关机、3 关机中、4 重启中、5 推流中、6 推流就绪。operating_status:0 启动中、1 运行中、2 已关机、3 关机中、4 重启中、5 重置中;6 未定义。两个字段不要混用。
| 字段 | 类型 |
|---|---|
| pod_id | string |
| name | string |
| online_status | integer |
| operating_status | integer |
| proxy_id | number |
curl --fail-with-body "https://api.foxphone.com/public_api/v1/phones?page_num=1&page_size=20&search=example" \
-H "X-API-Key: ${API_KEY}"{
"request_id": "example-request-id",
"code": 200,
"data": {
"total": 1,
"phones": [
{
"pod_id": "pod-example-001",
"name": "test-phone",
"online_status": 1,
"operating_status": 1,
"proxy_id": 42
}
]
},
"message": "success"
}search 按名称或代理 ID 查询当前账号代理。data.proxies 包含 proxy_id、name、proxy_type、proxy_ip、proxy_port、check_status。proxy_port 是字符串;不返回用户名、密码或刷新链接。check_status 为 unchecked、success、failed,历史值可能为空。最近检测成功不保证此刻可用。
curl --fail-with-body "https://api.foxphone.com/public_api/v1/proxies?page_num=1&page_size=20&search=example" \
-H "X-API-Key: ${API_KEY}"{
"request_id": "example-request-id",
"code": 200,
"data": {
"total": 1,
"proxies": [
{
"proxy_id": 42,
"name": "example-proxy",
"proxy_type": "socks5",
"proxy_ip": "203.0.113.42",
"proxy_port": "1080",
"check_status": "success"
}
]
},
"message": "success"
}此操作会清除手机数据,调用前备份并确认实例。仅提交 pod_ids;手机须运行中、可操作且属于当前账号。已关机、重置中或冲突状态会被拒绝。phone_template_mode(含 0)与 phone_template_id(含空串)均不支持,返回 400 / PHONE_TEMPLATE_PARAMETER_NOT_SUPPORTED。随机选择可用机型;无其他机型时不指定模板,保留仿真设置并尝试恢复原代理,恢复仍会检测可用性。不会为未绑定手机选择或购买代理。
curl --fail-with-body "https://api.foxphone.com/public_api/v1/phones/actions/reset" \
-H "X-API-Key: ${API_KEY}" \
-H "Content-Type: application/json" \
--data '{"pod_ids":["pod-example-001"]}'路径 proxy_id 为代理列表返回的正整数,请求体只需 pod_ids。代理及手机须属于当前账号,代理须有效、未过期并通过绑定前检测。关机手机保存配置并保持关机,下次开机再下发;运行中手机异步下发,可能重启。重置、开关机、重启或代理冲突流程会拒绝提交。代理不可用时,外层 409 / BATCH_PRECHECK_FAILED,明细 PRECHECK_FAILED。
curl --fail-with-body "https://api.foxphone.com/public_api/v1/proxies/42/bind" \
-H "X-API-Key: ${API_KEY}" \
-H "Content-Type: application/json" \
--data '{"pod_ids":["pod-example-001"]}'仅重置与绑定使用 successful_pod_ids 和 failed_items。整批预检失败返回 409,明细位于 data.failed_items,不是顶层 metadata。远端受理后可能部分成功,已受理项不能跨系统回滚。successful_pod_ids 表示受理或配置保存,不等于完成;无成功项时可能为 null。不能直接重放整批。
{
"request_id": "example-request-id",
"code": 200,
"data": {
"successful_pod_ids": [
"pod-example-001"
],
"failed_items": [
{
"pod_id": "pod-example-002",
"code": "PROVIDER_REJECTED",
"message": "provider rejected the operation"
}
]
},
"message": "success"
}{
"request_id": "example-request-id",
"code": 409,
"data": {
"failed_items": [
{
"pod_id": "pod-example-002",
"code": "PHONE_NOT_RUNNING",
"message": "phone is not running"
}
]
},
"message": "batch precheck failed",
"reason": "BATCH_PRECHECK_FAILED"
}| 字段 | 说明 |
|---|---|
| RESOURCE_NOT_OWNED | 资源不属于当前账号 |
| RESET_IN_PROGRESS | 手机正在执行一键新机 |
| OPERATION_IN_PROGRESS | 存在冲突中的操作 |
| PHONE_NOT_RUNNING | 手机未处于运行状态 |
| RESOURCE_UNAVAILABLE | 资源不存在或不可用 |
| PRECHECK_FAILED | 代理检查或其它预检失败 |
| PROVIDER_REJECTED | 云端拒绝请求或提交失败 |
查询时 source 必填:official 为官方应用,user 为当前账号上传应用。app_name 按名称筛选,app_type 为可选整数;分页同通用约定。按 package_name 聚合,total 是应用数而非版本数;包名升序,versions 按 version_code 降序。安装用 package_name 与 version_code,不用 version_id 或 version_name。此列表不是设备已安装应用列表。
curl --fail-with-body "https://api.foxphone.com/public_api/v1/apps?source=official&page_num=1&page_size=20&app_name=example" \
-H "X-API-Key: ${API_KEY}"{
"request_id": "example-request-id",
"code": 200,
"data": {
"total": 1,
"apps": [
{
"app_id": "app-example",
"app_name": "Example App",
"package_name": "com.example.app",
"app_type": 1,
"icon_url": "",
"source": "official",
"versions": [
{
"id": 101,
"version_id": "version-example",
"version_name": "1.0.0",
"version_code": 100
}
]
}
]
},
"message": "success"
}package_name 必填非空,version_code 为正整数,pod_ids 遵循批量规则。请选择自己的已开机可用手机。建议显式传 source=official 或 user;省略或空值先查个人应用,再查官方;指定来源后不跨源兜底,不支持 APK 下载 URL。返回 data.items 中 pod_id/job_id,只代表任务提交;本组接口没有安装结果查询接口,也不使用重置/绑定的整批状态预检响应约定。
curl --fail-with-body "https://api.foxphone.com/public_api/v1/phones/actions/install-app" \
-H "X-API-Key: ${API_KEY}" \
-H "Content-Type: application/json" \
--data '{"source":"official","package_name":"com.example.app","version_code":100,"pod_ids":["pod-example-001"]}'{
"request_id": "example-request-id",
"code": 200,
"data": {
"items": [
{
"pod_id": "pod-example-001",
"job_id": "job-example-001"
}
]
},
"message": "success"
}400 修正参数;401/403 检查密钥或账号;409 修复资源或等待冲突结束;429 退避重试。查询可在额度内重试。写操作无对外幂等键约定:超时或 500 后是否受理可能不确定,先核实再决定是否重试。安装应用不存在、版本不匹配或云端提交失败目前也可能返回 500 / PUBLIC_API_INTERNAL_ERROR,不能当作未执行的证明。
| HTTP | reason |
|---|---|
| 400 | INVALID_ARGUMENT |
| 400 | PHONE_TEMPLATE_PARAMETER_NOT_SUPPORTED |
| 401 | INVALID_API_KEY |
| 403 | API_KEY_DISABLED |
| 403 | USER_ACCOUNT_UNAVAILABLE |
| 409 | BATCH_PRECHECK_FAILED |
| 429 | RATE_LIMIT_EXCEEDED |
| 500 | PUBLIC_API_INTERNAL_ERROR |
| 500 | PUBLIC_API_AUTH_ERROR |
将密钥保存在服务端的环境变量或密钥管理系统,不嵌入前端、公开仓库或客户端。不要写入 URL、请求体、日志或工单;示例用环境变量 API_KEY。在可信环境生成和保存,泄露时立即轮换或禁用,并更新所有调用方。轮换后旧 Key 无效,禁用后请求被拒绝。
提交问题时提供 request_id、接口路径、HTTP 状态、reason、发生时间及脱敏参数;不要提交 API Key。先用只读列表验证接入,再在明确授权的测试设备上执行写操作,确认结果后再扩大批次。