help-icon
icon

公共 API 使用指南

helpDetails-time-icon2026-09-23T13:09:05+08:00

使用个人 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批量安装应用

准备 API Key

在控制台右上角头像菜单进入 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_idstring
namestring
online_statusinteger
operating_statusinteger
proxy_idnumber
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,不能当作未执行的证明。

HTTPreason
400INVALID_ARGUMENT
400PHONE_TEMPLATE_PARAMETER_NOT_SUPPORTED
401INVALID_API_KEY
403API_KEY_DISABLED
403USER_ACCOUNT_UNAVAILABLE
409BATCH_PRECHECK_FAILED
429RATE_LIMIT_EXCEEDED
500PUBLIC_API_INTERNAL_ERROR
500PUBLIC_API_AUTH_ERROR

API Key 安全管理

将密钥保存在服务端的环境变量或密钥管理系统,不嵌入前端、公开仓库或客户端。不要写入 URL、请求体、日志或工单;示例用环境变量 API_KEY。在可信环境生成和保存,泄露时立即轮换或禁用,并更新所有调用方。轮换后旧 Key 无效,禁用后请求被拒绝。

接入验证与支持

提交问题时提供 request_id、接口路径、HTTP 状态、reason、发生时间及脱敏参数;不要提交 API Key。先用只读列表验证接入,再在明确授权的测试设备上执行写操作,确认结果后再扩大批次。

相关文档

Email contact
Cookie notification iconCookie 提示
本网站使用 Cookie 以改善用户体验。要了解更多关于我们的 Cookie 政策或撤回您的同意,请查看我们的 隐私政策 和 Cookie 政策。