管理 API - GPT-Load

管理画面自体がこれらのエンドポイントを使います。Groupやキーの管理を自動化する場合は、これらを直接利用できます。

認証§

/api配下の保護されたエンドポイントでは Bearer 認証を使用します：

リクエストヘッダー

Authorization: Bearer AUTH_KEY または AccessKey

AUTH_KEY——管理権限です。設定を読み書きでき、Reveal などの機密操作も実行できます
AccessKey——自身の範囲内にあるホーム、モデル、使用量、マスキング済みリクエストログのみを参照できます。設定の変更やアップストリーム認証情報の表示はできません

書き込みまたはルート確認を行う場合はAUTH_KEYを使用してください。

AccessKey が現在読み取れるのは /api/auth/session、/api/home、/api/home/statistics、/api/models、/api/usage、/api/logs、/api/logs/{request_id} だけです。その他の管理ルートは 403 を返します。

認証失敗のロックアウト§

スクリプトから誤ったキーを繰り返し再試行しないでください

同じ直接接続先アドレスから 30 分以内に管理認証を 5 回連続で失敗すると、30 分間ロックされます。ロック中は 429 と Retry-After が返されます。正しい AUTH_KEY で認証に成功すると失敗回数は消去されます。

レスポンス規約§

レスポンスは統一形式で、成功と失敗をcodeで区別します：

成功

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

失敗

{
  "code": "エラー識別子",
  "message": "人間が読める説明"
}

成功時、codeは数値の0です。失敗時は文字列識別子です。型を確認してください。

data は成功応答でもエラー応答でも省略可能です。返すデータがない場合はフィールド自体が省略されるため、常に存在する、または常にオブジェクトであるとは仮定しないでください。message は Accept-Language に従ってローカライズされます。

プログラムは code と構造化された data を判断し、ローカライズされた message を解析しないでください。完全なコードと復旧方法はエラーと復旧を参照してください。

書き込みの前提条件§

リクエストヘッダー	必要な API	契約
Idempotency-Key	`POST /api/groups` `POST /api/groups/{group_id}/credentials/import` `POST /api/groups/{group_id}/credentials/connect` `POST /api/groups/{group_id}/credentials/{credential_id}/reset-credits/consume` `POST /api/access-keys` `POST /api/access-keys/{id}/rotate`	値は必ず 1 つだけで、正規の小文字 UUID v4 形式にします。同じ論理操作を再試行するときは元の値を再利用します
If-Match	`PUT /api/settings`	設定応答の `ETag` を読み、そのまま送り返します。競合時は最新設定を再取得してマージしてください。

JSON リクエスト本文は厳密な契約に従います

JSON 本文を宣言するエンドポイントは単一のオブジェクトだけを受け付けます。未知フィールド、重複フィールド、末尾の 2 個目の JSON 値は拒否されます。空オブジェクト契約を使う引数なし操作は、空の本文または {} だけを受け付けます。

主要資源§

パス	用途
/api/auth/session	現在の Bearer プリンシパル種別を確認
/api/home	ホームの概要、統計、サブスクリプションアカウント一覧
/api/health	実行時のヘルス状態
/api/logs	リクエストログの一覧と詳細
/api/usage	使用量およびコスト統計
/api/settings	グローバル実行時設定
/api/system	デプロイ情報とバージョン更新確認
/api/route/inspect	読み取り専用のルート検査
/api/channels	チャネルの記述子、フィールド、機能
/api/models	プロジェクトモデル一覧とアップストリームモデル検出
/api/model-prices	モデル価格の照会、同期、更新、リセット、削除
/api/groups	Group の一覧、作成、詳細、設定、モデル、削除
/api/groups/{group_id}/credentials	認証情報管理、バッチインポート、実際の値の表示、ダウンロードを含む
/api/credential-stages	サブスクリプション認証情報の認可、インポート、ポーリング、一時状態
/api/access-keys	AccessKey、上限と実値の確認を含む

自動化ではバージョンを固定してください

この表は安定したリソース境界だけを記録し、変化中の全エンドポイントフィールドは複製しません。現在のバージョンの完全なルート契約はコード内の internal/control/http_routes.go で定義されます。自動化では GPT-Load の正確なバージョンを固定し、アップグレード後に実際の呼び出しを回帰確認してください。

いくつかの例§

すべてのGroupを列挙

curl http://127.0.0.1:3001/api/groups \
  -H "Authorization: Bearer $AUTH_KEY"

ヘルス状態を確認

curl http://127.0.0.1:3001/api/health \
  -H "Authorization: Bearer $AUTH_KEY"

ルーティングチェック：このリクエストはどこに行くか

curl -X POST http://127.0.0.1:3001/api/route/inspect \
  -H "Authorization: Bearer $AUTH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"protocol":"openai-completions","external_model":"gpt-4o","access_key_id":1}'

access_key_idは管理画面に表示される AccessKey の数値 ID です。ルート確認は現在の設定に基づく候補だけを計算し、アップストリームへ実際のリクエストを送信しません。

冪等キー付きで認証情報をインポート

curl -X POST http://127.0.0.1:3001/api/groups/1/credentials/import \
  -H "Authorization: Bearer $AUTH_KEY" \
  -H "Idempotency-Key: 7f6a7f86-3f58-4ae3-a1a1-46d3b8d17b71" \
  -H "Content-Type: application/json" \
  -d '{"credentials":"sk-example"}'

注意事項§

公開ネットワークにさらさないでください

管理 API ではすべてのチャネル認証情報の実値を読み取れます（/revealのようなエンドポイントが該当します）。AUTH_KEYが漏洩するとすべてのアップストリームキーが漏洩します。
アクセス元を制限してください。設定方法はセキュリティと本番運用を参照してください。

スクリプトに AUTH_KEY をハードコードしない — 環境変数またはシークレット管理ツールを使います。
インターフェースはバージョンに応じて調整される — 自動化スクリプトを更新したら再検証します。
冪等キーを独自に変更しない ——結果が不明なときは元の値を再利用し、新しい論理操作には新しい値を生成します。