---
title: Gateway API 參考
description: Gateway 的 /v1 端點、驗證方式、它加上的請求與回應標頭，以及描述這些端點的 OpenAPI 文件。
url: https://agentlab.cresclab.com/docs/zh-tw/gateway/api
language: zh-Hant
updated: 2026-10-28
---

# Gateway API 參考

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

## OpenAPI 文件

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

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

Base URL：`https://api.agentlab.cresclab.com`。錯誤代碼列在[錯誤代碼](https://agentlab.cresclab.com/docs/zh-tw/gateway/errors.md)。

## 端點

| 方法與路徑                              | 作用                                                                   |
| --------------------------------------- | ---------------------------------------------------------------------- |
| `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 物件。見[標籤](https://agentlab.cresclab.com/docs/zh-tw/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/zh-tw/gateway/auto.md#headers)。 |
| `X-Agentlab-Assessment`         | 使用 `auto` 時對任務的判斷，例如 `analysis/multi_step`。                                                            |
| `X-Agentlab-Prompt`             | 呼叫提示詞時，實際回答的提示詞版本，格式為 `<提示詞 id>@<版本>`。                                                   |
| `Retry-After`, `X-Should-Retry` | 拒絕時，要不要重試、什麼時候重試。見[三種 429](https://agentlab.cresclab.com/docs/zh-tw/gateway/limits.md#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`，所以供應商不會保留回應供日後取回。