使用個人 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。每個帳號僅一個有效金鑰;重新產生立即使舊金鑰失效,完整值只顯示一次。每次帶 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_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"
}依名稱或 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,不能視為未執行證據。
| 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。洩漏請立即輪換或停用並更新所有呼叫端,舊金鑰輪換後失效。
提供 request_id、路徑、HTTP 狀態、reason、時間及遮蔽參數,勿提供金鑰。先用唯讀清單驗證,再於已授權測試裝置執行寫入,核對結果後擴大批次。