help-icon
icon

公共 API 使用指南

helpDetails-time-icon2026-09-23T15:37:56+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。每個帳號僅一個有效金鑰;重新產生立即使舊金鑰失效,完整值只顯示一次。每次帶 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。洩漏請立即輪換或停用並更新所有呼叫端,舊金鑰輪換後失效。

export API_KEY="<your_api_key>"

通用約定與回應

使用 HTTPS。成功為 HTTP 200,資料在 data;失敗為 4xx/5xx 及字串 reason。請檢查狀態、reason 與逐項結果,勿只看 message。錯誤 data 可為 null,保存 request_id。個人金鑰與合作方 /open_api/v1 憑證不可混用。

同金鑰共用每分鐘 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"
}

查詢代理

依名稱或 ID 查詢代理。data.proxies 有 proxy_id、name、proxy_type、proxy_ip、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。提交後可能部分成功,已受理項無法跨系統回復。成功清單只代表受理或配置儲存,無項目可為 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;省略或空值先查個人再官方,指定後不跨來源。不接受 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。洩漏請立即輪換或停用並更新所有呼叫端,舊金鑰輪換後失效。

接入驗證與支援

提供 request_id、路徑、HTTP 狀態、reason、時間及遮蔽參數,勿提供金鑰。先用唯讀清單驗證,再於已授權測試裝置執行寫入,核對結果後擴大批次。

相關文件

Email contact
Cookie notification iconCookie 提示
本網站使用 Cookie 以改善用戶體驗。要了解更多關於我們的 Cookie 政策或撤回您的同意,請查看我們的 隱私政策 和 Cookie 政策。