XProxy REST API：IP ローテーション・ステータス・プロキシ一覧
XProxy の REST API を使うと、自分のコードからシンプルな HTTP リクエストで、モバイルプロキシの一覧取得、IP のローテーション、ステータスの確認、モデムの再起動ができます。box のアドレスを呼び出し、必要な場面でダッシュボードのログインを付けるだけです。
必要なもの：Basic プラン以上（料金。Free プランには IP ローテーションがありません）と box のアドレス。ネットワークの外から使う場合は、ダッシュボードのユーザー名とパスワードも必要です。
ひとことで言うと
box のアドレスです（例：http://192.168.1.100）。別の API サーバーはありません。
ダッシュボードのユーザー名とパスワード（HTTP Basic）を使います。ローテーションとステータスの呼び出しは、Force API Auth をオンにしない限りログイン不要です。
info_list でモデムを一覧し、rotate_ip で新しい IP を取得し、status で準備ができたかを確認します。
XProxy API のベース URL は？
ベース URL は XProxy box のアドレスです。ダッシュボードのポートが 80 以外なら、そのポートも付けます：
| 呼び出し元 | ベース URL |
|---|---|
| ローカルネットワーク | http://192.168.1.100（box のアドレス） |
| ダッシュボードのポートを変更している場合 | http://192.168.1.100:8080（ダッシュボードを保護するを参照） |
| インターネット | http://myproxy.duckdns.org、公開アドレス、または VPS のアドレス。box へは NAT Forwarding、VPS Forwarding、Tailscale で接続します。 |
https:// は、ドメインが HTTPS に対応している場合だけ使ってください。リンクと API 呼び出し用のドメインは Proxy Settings → Address で別に設定できます。
REST API にログインするには？
別の API キーはありません。ログインが必要な呼び出しでは、ダッシュボードのユーザー名とパスワードを HTTP Basic 認証で送ります。ダッシュボードを保護するで設定したものと同じログインです。
| 呼び出し | ログイン |
|---|---|
ローテーション、ステータス、再起動：/api/v1/rotate_ip/…、/api/v1/status/…、/api/v1/reboot/…、および旧形式の /reset、/status リンク | Force API Auth をオンにするまでは不要。オンにすると HTTP Basic。 |
一覧やその他すべて：/api/v1/info_list、/api/v1/proxy_list/…、/proxy_list、/reset_all、/reset_by_port、/status_by_port | ローカルネットワークの外からは HTTP Basic。 |
| ローカルネットワーク上のデバイス、ホワイトリストに登録した IP、Tailscale のデバイス（許可している場合） | ログイン不要。Force LAN Auth と Force API Auth でこれを変更できます。 |
| 専用トークンを持つ顧客のプロキシ（Business プラン） | リンク内のトークン。Selling Platform の使い方を参照してください。 |
API トークンはありますか？
パネル自体は POST /v2/auth/login でログインします。返ってくるトークンは、ユーザー名とパスワードを Base64 で書いただけのものなので、パスワードと同じように秘密にしてください。スクリプトからは、毎回 HTTP Basic で同じログインを送れば十分です。
# optional: check a login (answer: status true and a token)
curl -X POST 'http://192.168.1.100/v2/auth/login' \
--header 'Content-Type: application/json' \
--data '{"username": "admin", "password": "YOUR_PASSWORD"}'パネルのどこに API がありますか？
サイドバーの API Reference を開きます。apidocs.xproxy.io の完全なドキュメントへのリンクと、最初によく使われる 3 つの呼び出しが載っています。
info_list、rotate_ip/position、status/position。どのエンドポイントを呼び出せますか？
特に記載がなければ、すべて GET です。<position> はモデムの番号（1 = 最初のモデム）、<proxy> はそのプロキシの host:port です。
| エンドポイント | 機能 | ログインが必要？ |
|---|---|---|
/api/v1/info_list?page=&limit= | モデムの一覧：ポート、公開 IP、最後のローテーション、デバイス情報。レスポンス：data と total。 | はい |
/api/v1/proxy_list/<type> | プレーンテキストで 1 行に 1 プロキシ。種類：proxy、socks5、proxy_ipv6、socks5_ipv6、vless、vless_ipv6、ss。 | はい |
/api/v1/rotate_ip/position/<position> | そのモデムの IP を新しくします。 | いいえ* |
/api/v1/rotate_ip/proxy/<proxy> | 同じ操作をプロキシで指定します。 | いいえ* |
/api/v1/status/position/<position>/api/v1/status/proxy/<proxy> | モデムの公開 IP と状態。 | いいえ* |
/api/v1/reboot/position/<position>/api/v1/reboot/proxy/<proxy> | モデムを再起動します。 | いいえ* |
/reset?proxy=<proxy>、/status?proxy=<proxy> | 旧形式のローテーション・ステータスのリンク。パネルの LINK ボタンでコピーできます。 | いいえ* |
/reset_all | すべてのモデムをローテーションします。 | はい |
POST /reset_by_port（{"port": 4001} を送信） | そのプロキシポートのモデムをローテーションします。 | はい |
/status_by_port?port=4001 | プロキシポートでステータスを取得します。 | はい |
はい = ローカルネットワークの外からはダッシュボードのログインが必要。いいえ* = Force API Auth をオンにするまではログイン不要。すべてのパラメーターを含む完全な一覧は API ドキュメントにあります。
API でプロキシを一覧するには？
# all modems, first page of 20
curl -u admin:YOUR_PASSWORD 'http://192.168.1.100/api/v1/info_list?page=1&limit=20'
# every modem at once (leave page and limit out)
curl -u admin:YOUR_PASSWORD 'http://192.168.1.100/api/v1/info_list'自分のローカルネットワーク、またはホワイトリストに登録した IP からなら、-u を省略できます。
レスポンス（一部省略）：
{
"data": [
{
"position": 1,
"host": "192.168.1.100",
"proxy_port": 4001,
"socks5_port": 5001,
"public_ip": "203.0.113.25",
"public_ip_ipv6": null,
"device_manufacture": "XProxy-Hilink",
"device_rebooting": false,
"device_resetting": false
}
],
"total": 1
}各項目のその他のフィールド：proxy_port_v6、socks5_port_ipv6、vless_port、vless_port_v6、ss_port、ss_port_v6、last_updated_ip、device_imei、device_number、device_ip、device_extra_info。
API で IP をローテーションするには？
rotate_ip を呼び出し、モデムが新しい IP で MODEM_READY になるまで status を確認します。同じ呼び出し、タイマー、ローテーションリンクについては IP を変更する方法にあります。
# by position (1 = first modem)
curl 'http://192.168.1.100/api/v1/rotate_ip/position/1'
# or by proxy (host:port)
curl 'http://192.168.1.100/api/v1/rotate_ip/proxy/192.168.1.100:4001'
# the box answers at once:
# {"status": true, "msg": "command_sent"}
# check on the new IP a few seconds later
curl 'http://192.168.1.100/api/v1/status/position/1'
# {"status": true, "public_ip": "203.0.113.77", "public_ip_v6": null,
# "last_public_ip": "203.0.113.25", "msg": "MODEM_READY"}Force API Auth がオンでなければログインは不要です。オンの場合は -u admin:YOUR_PASSWORD を追加します。
ツール用にプロキシをテキストで一覧するには？
# plain text, one host:port per line
curl -u admin:YOUR_PASSWORD 'http://192.168.1.100/api/v1/proxy_list/proxy'
curl -u admin:YOUR_PASSWORD 'http://192.168.1.100/api/v1/proxy_list/socks5'
# 192.168.1.100:4001
# 192.168.1.100:4002ほかの種類：proxy_ipv6、socks5_ipv6、vless、vless_ipv6、ss。VLESS と Shadowsocks は共有リンクを返し、Premium プラン以上が必要です。
API にログインを求めるには？
General Settings → System Setting → Security を開き、Force API Auth をオン ① にして保存 ③ します。呼び出し時に送るログインが必要なので、先にユーザー名とパスワードを保存 ② しておいてください。
レスポンスの意味は？
| レスポンス | 意味 |
|---|---|
{"status": true, "msg": "command_sent"} | ローテーションが始まりました。新しい IP は数秒後に割り当てられます。 |
need_upgrade | ご利用のプランには IP ローテーションがありません。サブスクリプションの管理を参照してください。 |
modem_resetting または MODEM_RESETTING | そのモデムですでにローテーションが実行中です。 |
MODEM_STOPPED | モデムが停止しているため、ローテーションできません。 |
slot_not_found、MODEM_NOT_FOUND | そのポートまたは位置にモデムがありません。 |
invalid_format_proxy | プロキシは host:port の形式で指定してください。 |
MODEM_DISCONNECTED | モデムの電源が切れているか、外れています。 |
COLLISION_IP | ローテーション前と同じ IP です（IP unchanged detect がオンの場合のみ）。 |
HTTP 401、{"message": "Unauthorized…"} | ダッシュボードのログインが必要です。ログインを付けるか、ホワイトリストに登録した IP から呼び出してください。 |
| HTTP 403、Access Denied | Domain Only がオンです。IP アドレスではなくドメイン名で呼び出してください。 |
よくある質問
XProxy の API キーはどこで取得できますか？
API キーはありません。ダッシュボードのユーザー名とパスワードを HTTP Basic のログインとして使うか、ローカルネットワークからログインなしで呼び出してください。ローテーションとステータスのリンクでは、Force API Auth をオンにした後だけログインが必要です。
コードからモバイルプロキシの IP をローテーションするには？
box に GET /api/v1/rotate_ip/position/1 を送ります。すぐに command_sent が返ります。その後、msg が MODEM_READY になり public_ip が変わるまで /api/v1/status/position/1 を呼び出します。
どのくらいの頻度でローテーションできますか？
同じモデムで別のローテーションが実行中のときは拒否されます（modem_resetting）。ポートの 2 回のローテーションの最短間隔は ローテーション設定でも設定できます。
ネットワークの外から API を呼び出せますか？
はい。外部から box にアクセスできるようにすれば可能です。ベース URL にドメインまたは公開アドレスを使い、ダッシュボードのログインを付けます。ローテーションリンクでもログインが求められるよう、Force API Auth をオンにしてください。
顧客も API を使えますか？
顧客には、自分のプロキシ用のトークン付きリンクが発行されます（Business プラン）。そのため、あなたのダッシュボードのログインは必要ありません。Selling Platform の使い方を参照してください。
次はどうする？
タイマーでローテーションする、呼び出しを保護する、プロキシをツールに組み込む。