HopBase ドキュメントアカウント・カタログ API
GET /v1/models、GET /v1/usage、公開エンドポイント GET /api/v1/models/pricing の認証方法、レスポンス例、フィールドの型と単位、HopBase が返すレスポンスヘッダー。
3 つの読み取り専用エンドポイントで、キーが呼び出せるモデル、キーの残り利用可能額、各モデルの定価を取得できます。いずれも課金されず、残高がゼロでも呼び出せます。
| エンドポイント | 認証 | 返す内容 |
|---|---|---|
GET /v1/models | キー:Authorization: Bearer sk-… または x-api-key: sk-… | このキーのグループが提供するモデル |
GET /v1/usage | キー:Authorization: Bearer sk-… のみ | このキーの残り利用可能額とクォータ |
GET /api/v1/models/pricing | 不要 | 定価付きの公開モデルカタログ |
モデル一覧
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-opus-5-5",
"object": "model",
"type": "model",
"display_name": "Claude Opus 5.5",
"created_at": "2026-09-22T00:00:00Z"
}
],
"has_more": false,
"first_id": "claude-opus-5-5",
"last_id": "claude-haiku-4-5-20251001"
}| フィールド | 型 | 意味 |
|---|---|---|
data[].id | string | リクエストで指定するモデル ID。依存してよいのはこのフィールドだけです |
data[].capabilities | string[] | 例:chat、reasoning、image_generation |
data[].image_only | boolean | 画像モデルでは true。それ以外では省略 |
data[].context_window、context_length、max_input_tokens | integer、トークン | クライアント互換のため同じ値を 3 つの名前で返します。非公開の場合は省略 |
data[].max_output_tokens | integer、トークン | 非公開の場合は省略 |
data[].created | integer、Unix 秒 | このレスポンスの時刻で、リリース日ではありません |
data[].display_name、created_at | string | Claude グループのみ。created_at はモデルのリリース日(RFC 3339) |
has_more、first_id、last_id は SDK 互換のためだけに含まれます。一覧はページングされないため、これらでページ送りしないでください。id 以外のフィールドはモデルによって欠けることがあります。未知のフィールドは任意項目として扱ってください。
残高とクォータ
curl https://api.hop-base.com/v1/usage \
-H "Authorization: Bearer sk-your-key"{
"is_active": true,
"balance": 125.4,
"remaining": 125.4,
"unit": "USD",
"quota": {
"remaining": 125.4,
"api_key_remaining": 125.4,
"total": 0,
"used": 3.12,
"unlimited": true
}
}| フィールド | 型 | 意味 |
|---|---|---|
balance | number | このキーで今使える金額。キーにクォータがない場合はアカウント残高、ある場合はキーの残りクォータ。チームメンバーや部門のキーは、さらにメンバー・部門の当期残りクォータで上限がかかります |
remaining | number | balance と同じ値 |
is_active | boolean | balance が 0 より大きいとき true |
unit | string | 常に "USD"。通貨を示すものではありません。下の注記を参照 |
quota.remaining | number | balance と同じ値 |
quota.api_key_remaining | number | このキーの残りクォータ。キーにクォータがない場合はアカウント残高と同じ |
quota.total | number | キーのクォータ。0 はキーのクォータなし |
quota.used | number | このキーでこれまでに課金された合計 |
quota.unlimited | boolean | キーに独自のクォータがないとき true |
金額は残高の通貨です
すべての金額は、アカウント残高を管理している通貨で表されます。コンソールの残高や「使用記録」に表示される数字と同じです。unit から通貨を判断しないでください。
クォータを設定したキーも、アカウント残高から差し引かれます。アカウント残高が先に尽きると、ここでの balance にクォータが残っていてもリクエストは 402 になります。
このエンドポイントは標準のエラー形式を使いません。失敗時は次のとおりです。
| ケース | ステータス | ボディ |
|---|---|---|
キーなし、または sk- で始まらないキー | 401 | {"is_active": false, "balance": 0, "message": "missing or invalid api key"} |
| 存在しない、または無効化されたキー | 401 | "message": "invalid api key" |
| 期限切れのキー | 200 | "is_active": false、"message": "api key expired" |
| チームメンバーが無効化されている | 200 | "is_active": false、"message": "member disabled" |
HTTP ステータスだけでなく is_active で判定してください。課金の明細はコンソールの「使用記録」で確認できます。
公開モデルカタログ
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"
}
]
}
]
}| フィールド | 型 | 意味 |
|---|---|---|
code | integer | 成功時は 0 |
data[].platform | string | モデルを提供する接続ファミリー(例:openai、claude、gemini、kling)。モデルの開発元ではありません。開発元は vendor を参照 |
models[].id | string | 指定するモデル ID |
models[].name | string | 表示名 |
models[].vendor | string | モデルの開発元(例:openai、google)。省略されることがあります |
models[].series | string | コンソールで複数バージョンをまとめる系列。省略されることがあります |
models[].category | string | chat、image、video、audio、embedding のいずれか |
models[].capabilities | string[] | 例:chat、reasoning、image_generation、image_edit、video_generation、tts |
models[].context_window | integer、トークン | 非公開の場合は省略 |
models[].price_unit | string | このエントリーのすべての価格の単位:token = 100 万トークンあたり、second = 動画 1 秒あたり、image = 画像 1 枚あたり、character = 課金文字 100 万文字あたり |
models[].input、cached_input、output | number、米ドル / price_unit | キャッシュが適用されない場合 cached_input は省略。音声モデルは input のみ使用 |
models[].long_context | object | 長文コンテキストの段階がある場合に返ります。入力トークンが threshold を超えると、リクエスト全体が input_multiplier / cached_multiplier / output_multiplier で課金されます |
models[].image | object | 解像度段階ごとの 1 枚あたり価格。例:{"1k": …, "2k": …, "4k": …} |
models[].video_tokens | object | 区分(解像度、音声の有無、参照素材の有無)ごとの動画価格。単位は price_unit に従い、token なら動画トークン 100 万あたり、second なら 1 秒あたり。キー名は過去の名残です |
同じモデルが複数のグループで提供されている場合、複数の platform の下に現れることがあります。フィールドは今後追加される可能性があります。未知のフィールドは無視してください。
レスポンスヘッダー
| ヘッダー | 返るタイミング | 意味 |
|---|---|---|
x-request-id | すべてのレスポンス | このリクエストの ID。問題を報告するときに添えてください |
Retry-After | 同時実行数の上限による 429、待ち時間が分かっている 429 と 503 | 再試行までに待つ秒数 |
Retry-After-Ms | 同時実行数の上限による 429、および待ち時間が分かっているその他の 429 | 同じ待ち時間(ミリ秒) |
HopBase は、同時実行数の上限、処理中のリクエスト数、残高をレスポンスヘッダーで返しません。残高は GET /v1/usage で確認し、上限は同時実行数・タイムアウト・課金を参照してください。一部のモデルのレスポンスには独自のレート制限ヘッダー(x-ratelimit-*、anthropic-ratelimit-*)が含まれますが、アカウントやキーの上限を示すものではないため、これに基づいてスロットリングしないでください。