--- title: Gateway API リファレンス description: Gateway の /v1 エンドポイント、認証方法、Gateway が付けるリクエストヘッダーとレスポンスヘッダー、それらを記述した OpenAPI ドキュメントです。 url: https://agentlab.cresclab.com/docs/ja/gateway/api language: ja updated: 2026-10-28 --- # Gateway API リファレンス Gateway の /v1 エンドポイント、認証方法、Gateway が付けるリクエストヘッダーとレスポンスヘッダー、それらを記述した OpenAPI ドキュメントです。 ## OpenAPI ドキュメント 以下のエンドポイントは OpenAPI 3.1 ドキュメントに記述されており、ビルドのたびに Gateway のルートと照合されます。 ```text https://agentlab.cresclab.com/docs/openapi/gateway.json ``` ベース URL：`https://api.agentlab.cresclab.com`。エラーコードは[エラー](https://agentlab.cresclab.com/docs/ja/gateway/errors.md)に一覧があります。 ## エンドポイント | メソッドとパス | 内容 | | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `POST /v1/chat/completions` | OpenAI Chat Completions。ストリーミングの有無を問わず、ワークスペースで許可されたどのモデルでも使えます。 | | `POST /v1/messages` | Anthropic Messages。送られたとおりに Claude のモデルへ中継します。 | | `POST /v1/messages/count_tokens` | Anthropic のトークン数カウント。計量されません。 | | `POST /v1/responses` | OpenAI Responses。送られたとおりに OpenAI のモデルへ中継します。 | | `POST /v1/prompts/{prompt}/completions` | ワークスペースのプロンプトライブラリのプロンプトを変数付きで呼び出します。応答は Chat Completions と同じ形です。 | | `GET /v1/models` | `auto` と、このキーで指定できるモデル。OpenAI または Anthropic の一覧形式で返します。 | | `GET /v1/gateway/readiness` | この Gateway サーバーが処理できる状態かどうか。キーは不要です。 | ## 認証 Gateway のキーを `Authorization: Bearer ` として送ります。`/v1/chat/completions` 以外のエンドポイントでは `x-api-key: ` も使えます。両方を送る場合は同じキーでなければなりません。ブラウザからのリクエスト（`Origin` ヘッダー付き）は拒否されます。 ## リクエストヘッダー | ヘッダー | 対象 | 意味 | | ------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `X-AgentLab-Routing` | すべての推論エンドポイント | `auto`：本文でモデルを指定していても、Gateway にモデルを選ばせます。値は正確に `auto` である必要があります。 | | `Idempotency-Key` | すべての推論エンドポイント（任意） | 8～128 文字。同じキーで二重に課金されることはありません。別のリクエストに再利用すると拒否されます。 | | `X-AgentLab-Metadata` | すべての推論エンドポイント（任意） | 使用量レポート用のタグ。文字列値が最大 16 個の JSON オブジェクト。[タグ](https://agentlab.cresclab.com/docs/ja/gateway/usage.md#tags)を参照。 | | `anthropic-version`, `anthropic-beta` | `/v1/messages` | 送られたとおりにプロバイダーへ渡されます。 | ## レスポンスヘッダー | ヘッダー | 意味 | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `X-Request-Id` | リクエストの ID。使用量のページとエクスポートの `request_id` と同じです。 | | `X-Agentlab-Model` | 応答したモデル。 | | `X-Agentlab-Decision` | `requested_model`、または `auto` がどう判断したか。[auto](https://agentlab.cresclab.com/docs/ja/gateway/auto.md#headers) を参照。 | | `X-Agentlab-Assessment` | `auto` の場合のタスクの判断結果（`analysis/multi_step` など）。 | | `X-Agentlab-Prompt` | プロンプト呼び出しで回答したプロンプトのバージョン。`<プロンプト id>@<バージョン>`。 | | `Retry-After`, `X-Should-Retry` | 拒否時に、再試行するかどうかといつ再試行するか。[3 種類の 429](https://agentlab.cresclab.com/docs/ja/gateway/limits.md#429) を参照。 | ## Chat Completions 本文は OpenAI Chat Completions のリクエストです。`model` は `auto` か `GET /v1/models` の名前です。応答の `model` は応答したモデルで、`agentlab_decision.reason` は `auto` または `requested_model` です。`stream_options.include_usage` を指定すると、ストリームの最後のチャンクに使用量が含まれます。 任意の `agentlab` オブジェクトでリクエストに必要な機能を示すと、`auto` はその機能を持つモデルだけを選びます：`{"schema_version": 1, "tool_calling": true, "vision": false, "structured_output": false, "minimum_context_tokens": 0}`。 ## プロンプト オーナーと管理者は Gateway の「プロンプト」タブでワークスペースのプロンプトを管理します。`{{変数}}` を含むメッセージ、任意のモデル（または `auto`）とパラメーターです。保存するたびに新しいバージョンになり、1 つのバージョンが公開されます。呼び出しは Portkey のプロンプト API と同じ形です。 ```bash curl https:///v1/prompts/support-reply/completions \ -H "Authorization: Bearer $AGENTLAB_API_KEY" -H "Content-Type: application/json" \ -d '{"variables": {"company": "Acme", "question": "When does order 1042 ship?"}}' ``` - プロンプトは slug または id で指定します。`@<バージョン>`（例：`support-reply@3`）を付けるとバージョンを固定できます。付けなければ公開中のバージョンが回答します。 - `variables` はプロンプトの変数とちょうど一致し、値はすべて文字列である必要があります。不足や余分があれば、何も送信する前に `prompt_variables_mismatch` で拒否されます。 - その他の Chat Completions のメンバー（`model`、`stream`、`user` など）はプロンプトの設定を上書きします。`messages` は拒否されます。メッセージはプロンプトが持っています。 - 応答は Chat Completions の応答で、同じキー、上限、`auto`、使用量を通ります。使用量ページではプロンプト別に分けられ、各リクエストにプロンプトとバージョンが表示されます。送信した変数の値は保存されません。 ## Messages と Responses この 2 つは、`model` を Gateway が選んだモデルに置き換える以外は、送られたとおりにプロバイダーへ中継されます。使用量、fast モード、リージョン推論、サービスティア、1 時間のキャッシュ書き込み、Web 検索、コード実行時間は、プロバイダー自身の報告から計測し、カタログの価格で計算します。 一部のメンバーは、Gateway がワークスペースに帰属させられないものを読んだり実行したりするため、拒否されます。 - Messages：`fallbacks` と advisor ツール。1 回の呼び出しの中で別のモデルを実行します。 - Responses：`previous_response_id`、`conversation`、`prompt`、アイテム参照。プロバイダーのアカウントに保存された状態を読みます。また `file_search` と `image_generation` のツール。Gateway は `store: false` を送るので、プロバイダーは後から取得するための応答を保持しません。