help-icon
icon

Public API 利用ガイド

helpDetails-time-icon2026-09-23T15:37:56+08:00

個人 API キーで端末、プロキシ、アプリを取得し、リセット、既存プロキシ関連付け、インストールを依頼します。公開対象の六つの API は https://api.foxphone.com、基本パス /public_api/v1 です。

API 一覧

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 キーの準備

アバターメニューの Settings から個人センターの API Key を開きます。有効キーは一つで、再生成すると旧キーは即時無効、全文表示は一度だけです。毎回 X-API-Key、POST は Content-Type: application/json を送ります。Web JWT、Cookie、Device-ID、hash、platform は不要で、Bearer は代替できません。

X-API-Key: <your_api_key>

キーはサーバー環境変数や秘密管理に保存し、フロント、公開リポジトリ、クライアントに入れません。URL、本文、ログ、問い合わせに記載しないでください。例は API_KEY を使います。漏えい時は即時再生成/無効化し全呼び出し元を更新します。

export API_KEY="<your_api_key>"

共通規則と応答

HTTPS を使います。成功 HTTP 200 の本文は data、失敗は 4xx/5xx と文字列 reason です。message だけでなく状態、reason、個別結果を確認します。エラー 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 数値で、大整数は精度を損なわない方法で処理してください。ゼロと空文字は保持され、空リストは [] または null です。

{
  "request_id": "example-request-id",
  "code": 200,
  "data": {
    "total": 0,
    "phones": []
  },
  "message": "success"
}

端末一覧

自分の端末を名前や pod_id の search で検索します。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。ポートは文字列、認証情報や更新 URL は返しません。状態は 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 は送信のみ。結果取得 API やリセット/関連付け同様の全体状態事前検査形式はありません。

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 キーの安全管理

キーはサーバー環境変数や秘密管理に保存し、フロント、公開リポジトリ、クライアントに入れません。URL、本文、ログ、問い合わせに記載しないでください。例は API_KEY を使います。漏えい時は即時再生成/無効化し全呼び出し元を更新します。

検証とサポート

問い合わせに request_id、パス、HTTP、reason、日時、機密情報を除いた引数を添え、キーは送らないでください。読み取りから検証し、許可されたテスト端末で書き込み、結果確認後に規模を増やします。

関連記事

Email contact
Cookie notification iconCookieに関するお知らせ
このウェブサイトはユーザー体験を向上させるためにCookieを使用しています。Cookieポリシーの詳細または同意の撤回については、プライバシーポリシーおよびCookieポリシーをご確認ください。