本文へスキップ
HopBase ドキュメント
ログイン

API リファレンス

HopBase API の Base URL、グループ単位のキー認証、リクエスト ID、エラー構造と同時実行数の制限、およびすべてのエンドポイント一覧。

HopBase はマルチモデルの API ゲートウェイです。チャット、画像、動画、音声はすべて同じドメイン https://api.hop-base.com で呼び出し、プロトコルは OpenAI と Anthropic の公式形式をそのまま使うため、既存の SDK は Base URL とキーを変えるだけで使えます。このセクションはエンドポイントごとに 1 ページで、パラメータ表と例はすべて OpenAPI 記述から生成しています。

エンドポイント一覧

Base URL

プロトコルBase URL用途
OpenAI 互換https://api.hop-base.com/v1チャット、Responses、画像、動画、音声、/v1/models、/v1/usage
Anthropichttps://api.hop-base.comClaude モデルの /v1/messages(SDK では /v1 を付けません)

プロトコルはクライアントとモデルの種類によって決まり、キーの形式では決まりません。シーン別の完全な対応表(Claude Code、Codex CLI、各モデルファミリー)は Base URL とプロトコルを参照してください。Wan / HappyHorse は ネイティブの動画パス /api/v1/services/aigc/video-generation/video-synthesis をそのまま使い、ドメインのルート直下に置かれています。

認証

すべてのエンドポイントは、コンソールの「API キー」で作成した sk- キーで認証します。次の 2 つのリクエストヘッダーのどちらかを使ってください:

Authorization: Bearer sk-あなたのキー
x-api-key: sk-あなたのキー

x-goog-api-key と URL パラメータ ?key= には対応していません。GET /v1/usage は Authorization: Bearer のみを受け付けます。

1 つのキーは 1 つのグループにのみ属します：

各キーは 1 つのグループ(例:「Codex Pro」「Claude Max(公式フル枠)」「GPT Image 全モデル」)に紐付き、そのグループが提供するモデルと、そのグループのプロトコルのエンドポイントしか呼び出せません。Claude のキーで /v1/chat/completions を呼ぶと 404「当前平台不支持该 API 路径」を、チャットグループのキーで画像モデルを呼ぶと 404 model_not_found を返します。同じプロジェクトでチャットと画像生成の両方を使う場合は、キーを 2 つ作成し、別々の環境変数に入れてください。利用できるモデルは、そのキーで GET /v1/models を呼んだ返り値が基準です。

キーは環境変数やデプロイ先プラットフォームから注入し、ソースコードに書いたり Git にコミットしたりしないでください。

リクエスト ID

すべてのレスポンスにはレスポンスヘッダー x-request-id が付き、そのリクエストを特定する一意の識別子です。問い合わせの際は x-request-id、発生時刻(タイムゾーン付き)、モデル ID、エラーメッセージの全文を添えてください。サーバー側の障害はコンソールに原文が表示されないため、調査は x-request-id をもとに行います。

curl -i https://api.hop-base.com/v1/models \
  -H "Authorization: Bearer $HOPBASE_API_KEY"
# HTTP/2 200
# x-request-id: …

一部のモデルのレスポンスには独自のレート制限ヘッダー(x-ratelimit-*、anthropic-ratelimit-*)が付きますが、これはあなたのアカウントやキーの上限を示すものではないため、流量制御の根拠にしないでください。

エラー

OpenAI プロトコルのエンドポイントは {"error": {"message", "type", "code"}} を返し、/v1/messages は Anthropic 形式の {"type": "error", "error": {"type", "message"}} を返します(code はありません)。メッセージの言語は Accept-Language に従い、指定がない場合は英語です。プログラムでは HTTP ステータスコードと code で判定し、メッセージ本文で照合しないでください。

ステータスコード意味再試行
400 / 413パラメータ不正 / リクエストボディが 60 MB 超不可。先にリクエストを修正
401キー未指定、キーが無効または期限切れ不可
402残高またはクォータ切れ。動画送信時に残高が処理中の引当に足りないチャージ後に可
403アカウントまたはメンバーが無効化されている、そのグループの利用権限がない不可
404モデルまたはパスがこのキーのグループに属さない不可
429アカウントまたはキーの同時実行数が上限に達した、またはサービスが混雑中Retry-After に従って再試行
502 / 503 / 504サービスが一時的に利用できない、またはタイムアウト間隔を空けて再試行

ストリーミングリクエストは出力が始まった時点で HTTP ステータスが 200 になり、以降のエラーはイベントとして通知されます。ストリーミングイベントを参照してください。エラーコードの完全な一覧と再試行のルールはエラーコードと再試行にあります。

同時実行数とレート制限

HopBase は 1 分あたりのリクエスト数ではなく、同時に処理中のリクエスト数で制限します。アカウントの既定値は同時 5 リクエストで、申請により引き上げられます。キーごとにもコンソールで上限を設定でき、両方ある場合は小さい方が適用されます。上限を超えたリクエストは即座に 429(user_concurrency_limit / apikey_concurrency_limit、Retry-After: 1 と Retry-After-Ms 付き)を返し、サーバー側で待機させることはありません。

チャット、画像生成、動画の送信、/v1/messages/count_tokens は同時実行数を消費し、タスクのポーリングと GET /v1/models は消費しません。タイムアウトの考え方とクライアントの読み取りタイムアウトの推奨値は同時実行数、タイムアウト、課金を参照してください。

課金

成功したリクエストはモデルの課金単位(トークン / 枚 / 秒 / 文字)で課金されます。失敗したリクエストは原則課金されず、ストリームが途中で中断した場合は生成済みの分だけ課金されます。非同期タスクの失敗は課金されません。残高の確認は GET /v1/usage で、公式の定価は公開カタログ GET /api/v1/models/pricing(フィールドの説明)で確認できます。

機械可読な記述

  • /openapi.json:このセクションの全エンドポイントの OpenAPI 3.1 記述。Postman、Apifox、SDK ジェネレーターにインポートできます。
  • /spec/models/index.json:画像生成モデルごとのリクエストボディの JSON Schema。数値はゲートウェイの検証コードに基づきます。
  • リクエストビルダー:ブラウザ上でモデルごとに正しい画像生成リクエストを組み立て、コードを生成します。

このページの内容

エンドポイント一覧Base URL認証リクエスト IDエラー同時実行数とレート制限課金機械可読な記述