アカウント・カタログ API

いずれのエンドポイントも課金されず、残高がゼロでも呼び出せます。

モデル一覧

GET /v1/models は Authorization: Bearer sk-… と x-api-key: sk-… のどちらも受け付けます。GET /v1/usage は Authorization: Bearer sk-… のみです。

curl https://api.hop-base.com/v1/models \
  -H "Authorization: Bearer sk-your-key"

一覧にはキーに含まれるグループのモデルだけが含まれ(複数グループのキーではすべてのグループの和集合)、1 回のレスポンスで全件が返ります(ページングなし)。OpenAI 互換グループのキーでは OpenAI 形式の一覧が返ります。

{
  "object": "list",
  "data": [
    {
      "id": "gpt-6-astra",
      "object": "model",
      "created": 1790222400,
      "owned_by": "hopbase",
      "capabilities": ["chat", "reasoning"],
      "context_window": 1050000,
      "context_length": 1050000,
      "max_input_tokens": 1050000,
      "max_output_tokens": 128000
    }
  ]
}

Claude グループのキーでは Anthropic 形式が返ります。

{
  "object": "list",
  "data": [
    {
      "id": "claude-sonnet-5-5",
      "object": "model",
      "type": "model",
      "display_name": "Claude Sonnet 5.5",
      "created_at": "2026-09-28T00:00:00Z"
    }
  ],
  "has_more": false,
  "first_id": "claude-sonnet-5-5",
  "last_id": "claude-haiku-4-5-20251001"
}

has_more、first_id、last_id は SDK 互換のためだけに含まれます。一覧はページングされないため、これらでページ送りしないでください。id 以外のフィールドはモデルによって欠けることがあります。未知のフィールドは任意項目として扱ってください。

残高と課金の通貨:USD

2026-10-01 から、アカウント残高、キーのクォータ、課金額、使用記録はすべて米ドル(USD)建てです。モデルは公式の米ドル価格にグループの倍率を掛けて課金され、コンソールと GET /v1/usage はいずれも米ドルの金額を表示します。

• 既存の残高:切り替え時に固定の比率で米ドルに換算しました。使える量は変わりません。グループの料金とキーも変わりません。
• リクエストごとの課金額:既存の連携がそのまま動くよう、レスポンスの cost と X-HopBase-Cost は引き続き同じ課金額の人民元額(小数点以下最大 6 桁)で、currency は常に CNY です。残高から実際に差し引かれた米ドル額は cost_usd と X-HopBase-Cost-USD にあり、「使用記録」と一致します。課金額を参照してください。
• チャージ:支払通貨、手数料、入金額は、支払い前に「チャージ」ページに表示される内容が正となります。手数料は別行で表示され、入金額には含まれません。人民元での法人振込やオフラインのチャージで入金される米ドル額は、サポートの確認内容が正となります。

残高とクォータ

curl https://api.hop-base.com/v1/usage \
  -H "Authorization: Bearer sk-your-key"

$10 のクォータを持ち、そのうち $2 を使用済みのキーの例:

{
  "is_active": true,
  "balance": 8,
  "remaining": 8,
  "unit": "USD",
  "ledger_currency": "USD",
  "balance_cny": 54.4,
  "balance_usd": 8,
  "quota": {
    "remaining": 8,
    "api_key_remaining": 8,
    "total": 10,
    "used": 2,
    "unlimited": false,
    "remaining_cny": 54.4,
    "remaining_usd": 8,
    "api_key_remaining_cny": 54.4,
    "api_key_remaining_usd": 8,
    "total_cny": 68,
    "total_usd": 10,
    "used_cny": 13.6,
    "used_usd": 2
  }
}

balance の決まり方:

• キーにクォータがない場合はアカウント残高です。
• クォータがある場合はキーの残りクォータです。
• チームメンバーや部門のキーは、さらにメンバー・部門の当期残りクォータで上限がかかります。

接尾辞のない金額とは balance、remaining、quota.remaining、quota.api_key_remaining、quota.total、quota.used です。

各金額には人民元と米ドルの接尾辞付きフィールドもあります。

クォータを設定したキーも、アカウント残高から差し引かれます。アカウント残高が先に尽きると、ここでの balance にクォータが残っていてもリクエストは 402 になります。

このエンドポイントは標準のエラー形式を使いません。失敗時は次のとおりです。

最初の 401 のボディ全体:

{"is_active": false, "balance": 0, "message": "missing or invalid api key"}

この 2 つの 200 レスポンスにも ledger_currency と balance_cny / balance_usd(いずれも 0)が含まれます。

HTTP ステータスだけでなく is_active で判定してください。課金の明細はコンソールの「使用記録」で確認できます。

リクエスト単位・タスク単位・記録単位の課金額

同期リクエストと非同期タスクは、課金額を 2 つの通貨で返します。cost_usd は残高から実際に差し引かれた米ドル額で、コンソールの「使用記録」のこの 1 件と同じです。cost は同じ課金額の人民元額で、既存の連携がそのまま動くよう常に人民元のため、currency は常に CNY です。cost_usd は小数点以下最大 8 桁、cost は 6 桁に丸めます。

同期リクエスト(チャット・画像・音声)

課金された同期リクエストは、今回の実際の課金額を 3 つのレスポンスヘッダーで返します。

ストリーミングでない JSON レスポンスは、ルートの usage にも同じ cost・cost_usd・currency を含みます。

{
  "id": "chatcmpl-abc",
  "object": "chat.completion",
  "model": "gpt-5.6-sol",
  "choices": [{ "index": 0, "message": { "role": "assistant", "content": "ok" }, "finish_reason": "stop" }],
  "usage": { "prompt_tokens": 9, "completion_tokens": 1, "total_tokens": 10, "cost": 0.001197, "cost_usd": 0.000176, "currency": "CNY" }
}

• レスポンスに usage がない場合は追加されます(音声合成 POST /v1/t2a_v2 の JSON レスポンスなど)。usage に元からあるフィールド(xAI の cost_in_usd_ticks など)は変わりません。
• usage にすでに cost・cost_usd・currency のいずれかがある場合や、usage がオブジェクトでない場合、ボディはそのままです。ヘッダーを読んでください。
• バイナリのレスポンス(音声合成の音声データなど)はヘッダーのみです。
• ストリーミング(SSE)のレスポンスはいずれも含みません。ヘッダーは生成開始前に送信済みで、最後の使用量イベントもそのまま送られます。ストリーミングリクエストの課金額はコンソールの「使用記録」で確認してください。
• 画像生成が約 40 秒を超える場合、サーバーは先に 200 のヘッダーを送り、キープアライブの空白を書き込むため、ヘッダーには課金額が入りません。ボディの usage.cost / usage.cost_usd を読んでください。
• 課金のないレスポンス(モデル一覧、課金されなかったエラーなど)はいずれも含みません。失敗したリクエストでも課金が発生した場合、エラーレスポンスにはヘッダーが付き、エラーボディは変わりません。
• HopBase が自動で再試行した場合、課金されるのは最後に完了した 1 回だけで、返るのもその金額です。複数グループのキーは、実際に処理したグループの料金で課金されます。
• 販売倍率を設定したキーでは、返る金額はあなたの残高から実際に差し引かれた額で、上乗せ分は含みません。
• レスポンスが届く前にクライアントが切断しても、使用した分は課金され、「使用記録」に表示されます。

非同期タスクの照会(画像と動画)

タスクが終了すると、トップレベルの usage に cost_usd(このタスクで残高から実際に差し引かれた米ドル額)、cost(同じ課金額の人民元額)、currency(cost の通貨。常に CNY)が含まれます。0 は課金されなかった失敗です。単一タスクの照会では、これらのフィールドはタスクを作成したキーでのみ確認できます。

{
  "id": "vt-1",
  "status": "completed",
  "usage": { "cost": 3.4, "cost_usd": 0.5, "currency": "CNY" }
}

タスク一覧(タスク ID を付けない GET /v1/video/tasks など)でも、終了済みの各タスクの usage に同じ cost・cost_usd・currency が含まれます。一覧はアカウント単位のため、同じアカウントの別のキーで作成したタスクにも金額が付きます。

コンソールの使用記録

「使用記録」ページは GET /api/v1/user/usage と GET /api/v1/user/usage/stats を読み取ります(コンソールのログインで認証し、sk- キーは使えません)。

各記録には ledger_currency(2026-10-01 からは USD)、cost_cny、cost_usd(その記録の課金額の人民元額と米ドル額)が含まれます。ページは米ドルで表示します。

統計には ledger_currency、total_charged_cny、total_charged_usd が含まれ、by_model、by_key、by_group、by_department、by_member の各項目に cost_cny / cost_usd が含まれます。

統計の従来の total_cost はグループの倍率を掛ける前の公式米ドル定価で、実際の課金額ではありません。課金額は total_charged_* を見てください。

公開モデルカタログ

curl https://api.hop-base.com/api/v1/models/pricing

キーは不要です。レスポンスはどのサイトからのクロスオリジン取得も許可し、最大 5 分間キャッシュされることがあります(Cache-Control: public, max-age=300)。価格はグループの料率を適用する前の米ドル定価です。各モデルの実際の支払額はサインイン後のモデル一覧に表示されます。

{
  "code": 0,
  "message": "ok",
  "data": [
    {
      "platform": "openai",
      "models": [
        {
          "id": "gpt-6-astra",
          "name": "GPT-6 Astra",
          "context_window": 1050000,
          "capabilities": ["chat", "reasoning"],
          "vendor": "openai",
          "category": "chat",
          "input": 10,
          "cached_input": 1,
          "output": 50,
          "long_context": {
            "threshold": 272000,
            "input_multiplier": 2,
            "cached_multiplier": 2,
            "output_multiplier": 1.5
          },
          "price_unit": "token"
        }
      ]
    },
    {
      "platform": "minimax",
      "models": [
        {
          "id": "speech-2.8-hd",
          "name": "MiniMax Speech 2.8 HD",
          "capabilities": ["tts"],
          "vendor": "minimax",
          "series": "minimax-speech",
          "category": "audio",
          "input": 100,
          "output": 0,
          "price_unit": "character"
        }
      ]
    }
  ]
}

platform の例は openai、claude、gemini、kling です。モデルの開発元は vendor を参照してください。

入力トークンが threshold を超えると、リクエスト全体が input_multiplier / cached_multiplier / output_multiplier で課金されます。

video_tokens の区分は解像度、音声の有無、参照素材の有無です。単位は token なら動画トークン 100 万あたり、second なら 1 秒あたりです。キー名は過去の名残です。

同じモデルが複数のグループで提供されている場合、複数の platform の下に現れることがあります。フィールドは今後追加される可能性があります。未知のフィールドは無視してください。

レスポンスヘッダー

HopBase は、同時実行数の上限、処理中のリクエスト数、残高をレスポンスヘッダーで返しません。残高は GET /v1/usage で確認し、上限は同時実行数・タイムアウト・課金を参照してください。一部のモデルのレスポンスには独自のレート制限ヘッダー(x-ratelimit-*、anthropic-ratelimit-*)が含まれますが、アカウントやキーの上限を示すものではないため、これに基づいてスロットリングしないでください。

次のステップ

• 同時実行数、タイムアウト、課金: 同時実行数の上限、タイムアウト、課金ルール
• エラーコードと再試行: 各エラーコードの意味と再試行の要否
• 利用可能なモデル: キーで使えるモデル ID を確認する