公共API使用指南

FoxPhone 公共 API 可用于查询当前账号下的云手机和代理，并批量执行一键新机、绑定已有代理。当前版本提供以下四个接口。

一、准备 API Key

点击页面右上角的头像，在菜单中选择 Settings，进入个人中心后打开 API Key 页面。

在 API Key 页面生成 Key。每个账号只允许一个有效 Key：

• 重新生成 Key 后，旧 Key 立即失效。
• 禁用 Key 后，所有公共 API 请求立即被拒绝。
• 完整 Key 只在生成时展示一次，请将其保存到受控的密钥管理系统。

调用公共 API 时，通过请求头传递 Key：

X-API-Key: <your_api_key>

安全提示：不要将 API Key 放入 URL、请求体、源代码、日志或工单。本文示例中的资源 ID 和 Key 均为占位符。

二、通用规则

• 生产环境基础路径：https://api.foxphone.com/public_api/v1
• 四个接口共用每个 API Key 每分钟 60 次的限流额度。
• 列表参数 page_num 默认值为 1；page_size 默认值为 20，最大值为 100；search 为可选参数。
• 批量写入支持 1 至 100 个 pod_ids，服务端会自动去重。
• 只能访问 API Key 所属账号的资源，不能通过参数指定其他账号。
• 批量预检发现任一资源无效或正在执行冲突操作时，整批请求不会提交。
• 远端任务开始提交后若出现部分失败，已受理任务不会回滚；响应会分别列出成功项和失败项。

三、查询云手机

使用以下接口分页查询当前账号下的云手机：

GET /public_api/v1/phones?page_num=1&page_size=20&search=pod-example

search 支持按云手机名称或 pod_id 查询。

请求示例：

curl --fail-with-body 
  -H "X-API-Key: $API_KEY" 
  "https://api.foxphone.com/public_api/v1/phones?page_num=1&page_size=20&search=pod-example"

响应示例：

{
  "total": 1,
  "phones": [
    {
      "pod_id": "pod-example-001",
      "name": "automation-phone",
      "online_status": 1,
      "operating_status": 0,
      "proxy_id": "42"
    }
  ]
}

proxy_id 为 0 时，表示该云手机当前未绑定代理。

四、查询代理

使用以下接口分页查询当前账号下已有的代理：

GET /public_api/v1/proxies?page_num=1&page_size=20&search=42

search 支持按代理名称或 proxy_id 查询。接口不会返回代理用户名或密码。

请求示例：

curl --fail-with-body 
  -H "X-API-Key: $API_KEY" 
  "https://api.foxphone.com/public_api/v1/proxies?page_num=1&page_size=20&search=42"

响应示例：

{
  "total": 1,
  "proxies": [
    {
      "proxy_id": "42",
      "name": "us-residential",
      "proxy_type": "http",
      "proxy_ip": "203.0.113.42",
      "proxy_port": "10000",
      "check_status": "available"
    }
  ]
}

五、批量一键新机

调用以下接口批量提交一键新机任务：

POST /public_api/v1/phones/actions/reset
Content-Type: application/json

请求体：

{
  "pod_ids": ["pod-example-001", "pod-example-002"]
}

当前限制：一键新机接口不支持在请求体中指定 proxy_id 或其他代理参数。如需更换代理，请等待一键新机完成后，再调用“批量绑定已有代理”接口。

请求示例：

curl --fail-with-body 
  -X POST 
  -H "Content-Type: application/json" 
  -H "X-API-Key: $API_KEY" 
  --data '{"pod_ids":["pod-example-001","pod-example-002"]}' 
  "https://api.foxphone.com/public_api/v1/phones/actions/reset"

同一台云手机已有一键新机任务时，新请求会在预检阶段返回 RESET_IN_PROGRESS，不会重复提交任务。

六、批量绑定已有代理

先通过代理列表接口取得 proxy_id，再调用以下接口：

POST /public_api/v1/proxies/{proxy_id}/bind
Content-Type: application/json

请求体：

{
  "pod_ids": ["pod-example-001", "pod-example-002"]
}

请求示例：

curl --fail-with-body 
  -X POST 
  -H "Content-Type: application/json" 
  -H "X-API-Key: $API_KEY" 
  --data '{"pod_ids":["pod-example-001","pod-example-002"]}' 
  "https://api.foxphone.com/public_api/v1/proxies/42/bind"

代理和所有云手机必须属于当前账号。关机状态的云手机也可以绑定代理；正在一键新机、开关机、重启或进行其他代理操作的云手机会在预检阶段被拒绝。

七、批量响应

一键新机和代理绑定使用相同的响应结构：

{
  "successful_pod_ids": ["pod-example-001"],
  "failed_items": [
    {
      "pod_id": "pod-example-002",
      "code": "PROVIDER_REJECTED",
      "message": "provider rejected the operation"
    }
  ]
}

预检失败会返回 HTTP 409 和错误码 BATCH_PRECHECK_FAILED。错误元数据中的 failed_items 会列出具体的 pod_id、code 和 message，此时整批请求不会提交。

远端开始受理后发生的失败，则通过业务响应中的 successful_pod_ids 和 failed_items 表示实际结果。

八、常见错误

收到 HTTP 429 时，应使用退避策略稍后重试。收到 HTTP 409 时，应先根据 failed_items 修复资源状态，不要立即重复提交相同请求。