Gateway API 參考

Gateway 的 /v1 端點、驗證方式、它加上的請求與回應標頭，以及描述這些端點的 OpenAPI 文件。

最後更新 2026-10-28

OpenAPI 文件#

下面的端點都寫在一份 OpenAPI 3.1 文件裡，每次建置都會和 Gateway 的路由比對：

text

https://agentlab.cresclab.com/docs/openapi/gateway.json

Base URL：https://api.agentlab.cresclab.com。錯誤代碼列在錯誤代碼。

端點#

方法與路徑	作用
`POST /v1/chat/completions`	OpenAI Chat Completions，可串流或不串流，可用工作區允許的任何模型。
`POST /v1/messages`	Anthropic Messages，照原樣轉送給 Claude 模型。
`POST /v1/messages/count_tokens`	Anthropic 的 token 計算。不計量。
`POST /v1/responses`	OpenAI Responses，照原樣轉送給 OpenAI 模型。
`POST /v1/prompts/{prompt}/completions`	以變數呼叫工作區提示詞庫裡的提示詞，回應格式同 Chat Completions。
`GET /v1/models`	`auto` 和這把金鑰可以指定的模型，以 OpenAI 或 Anthropic 清單格式回傳。
`GET /v1/gateway/readiness`	這台 Gateway 伺服器是否已經可以服務。不需要金鑰。

驗證#

用 Authorization: Bearer <key> 送出 Gateway 金鑰。除了 /v1/chat/completions，其他端點也接受 x-api-key: <key>；兩個都送時必須是同一把金鑰。來自瀏覽器（帶有 Origin 標頭）的請求會被拒絕。

請求標頭#

標頭	適用於	意思
`X-AgentLab-Routing`	所有推論端點	`auto`：即使 body 指定了模型，也讓 Gateway 選模型。必須剛好是 `auto`。
`Idempotency-Key`	所有推論端點，選用	8 到 128 個字元。同一個 key 絕不會被收兩次費用；把它拿去用在另一個請求會被拒絕。
`X-AgentLab-Metadata`	所有推論端點，選用	用量報表用的標籤：一個最多 16 個字串值的 JSON 物件。見標籤。
`anthropic-version`, `anthropic-beta`	`/v1/messages`	照原樣轉給供應商。

回應標頭#

標頭	意思
`X-Request-Id`	請求的 id，和用量頁及匯出檔裡的 `request_id` 相同。
`X-Agentlab-Model`	實際回答的模型。
`X-Agentlab-Decision`	`requested_model`，或 `auto` 的判斷方式。見 auto。
`X-Agentlab-Assessment`	使用 `auto` 時對任務的判斷，例如 `analysis/multi_step`。
`X-Agentlab-Prompt`	呼叫提示詞時，實際回答的提示詞版本，格式為 `<提示詞 id>@<版本>`。
`Retry-After`, `X-Should-Retry`	拒絕時，要不要重試、什麼時候重試。見三種 429。

Chat Completions#

body 是 OpenAI Chat Completions 請求。model 填 auto 或 GET /v1/models 裡的名稱。回應的 model 是實際回答的模型，agentlab_decision.reason 是 auto 或 requested_model。設定 stream_options.include_usage 時，串流的最後一個 chunk 會帶用量。

可以另外加一個 agentlab 物件，說明請求需要哪些能力，讓 auto 只挑具備這些能力的模型：{"schema_version": 1, "tool_calling": true, "vision": false, "structured_output": false, "minimum_context_tokens": 0}。

提示詞#

工作區的 owner 和 admin 在 Gateway 的「提示詞」分頁管理提示詞：含 {{變數}} 的訊息、選填的模型（或 auto）與參數。每次儲存都是新版本，其中一個版本是已發布版本。呼叫方式照抄 Portkey 的提示詞 API：

bash

curl https://<gateway>/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#

這兩個端點會照原樣轉送給供應商，只有 model 會換成 Gateway 選的模型。用量、fast mode、區域推論、服務層級、一小時快取寫入、網頁搜尋和程式碼執行時間，都依供應商自己的回報計量，並以目錄價格計價。

有幾個成員會被拒絕，因為它們會讀取或執行 Gateway 無法歸屬到你工作區的東西：

Messages：fallbacks 和 advisor 工具，它們會在一次呼叫裡再跑第二個模型。
Responses：previous_response_id、conversation、prompt 和 item 參照，它們會讀取存放在供應商帳號下的狀態；以及 file_search 和 image_generation 工具。Gateway 會送出 store: false，所以供應商不會保留回應供日後取回。