Hakila Docs
Messages

建立 Message

對齊 Anthropic Messages 規格（`POST https://api.anthropic.com/v1/messages`），給 Claude Code、 Anthropic SDK 等原生客戶端使用，可呼叫平台上所有 chat 模型。 - **Claude 模型**：除了模型路由、金鑰、允許清單與記帳，請求、回應與 SSE 事件都原樣透傳 - **其他模型**（GPT、Gemini、Grok…）：轉成各家協定後再轉回 Messages 格式（無狀態）； `thinking`／`output_config.effort` 換成各家推理等級，需要回傳的推理資料加密放在 `thinking` block 的 `signature` 或 `redacted_thinking` 的 `data`；Anthropic 伺服器端工具（例如 `web_search_20250305`） 會移除並列在回應 header `X-Hakila-Dropped-Tools`。詳見 [Messages 指南](/docs/guides/messages#非-claude-模型) - 沒有前綴的 `model`（例如 `claude-sonnet-5`）在目錄中只有一個同名模型時補上開發商前綴（`anthropic/claude-sonnet-5`）；多個同名模型時回 `400`，沒有時回 `404` - `hakila/auto` 的候選可落在任何供應商；裸名稱 `claude-auto` 視同 `hakila/auto`（給只接受 Claude 名稱的 Claude Desktop 用） - 認證可用 `x-api-key`（Anthropic SDK 預設）或 `Authorization: Bearer` - Claude 模型的 `anthropic-version` 與 `anthropic-beta` header 會轉發給上游 - 錯誤形狀與 Anthropic 一致（`{"type":"error","error":{"type","message"}}`） - 支援 Response Cache header；不支援 Preset（回 `400`） - 上游首字元逾時（預設 30 秒）回傳 `504`

POST/v1/messages

對齊 Anthropic Messages 規格（POST https://api.anthropic.com/v1/messages），給 Claude Code、 Anthropic SDK 等原生客戶端使用，可呼叫平台上所有 chat 模型。

  • Claude 模型：除了模型路由、金鑰、允許清單與記帳，請求、回應與 SSE 事件都原樣透傳
  • 其他模型（GPT、Gemini、Grok…）：轉成各家協定後再轉回 Messages 格式（無狀態）； thinking／output_config.effort 換成各家推理等級，需要回傳的推理資料加密放在 thinking block 的 signature 或 redacted_thinking 的 data；Anthropic 伺服器端工具（例如 web_search_20250305） 會移除並列在回應 header X-Hakila-Dropped-Tools。詳見 Messages 指南
  • 沒有前綴的 model（例如 claude-sonnet-5）在目錄中只有一個同名模型時補上開發商前綴（anthropic/claude-sonnet-5）；多個同名模型時回 400，沒有時回 404
  • hakila/auto 的候選可落在任何供應商；裸名稱 claude-auto 視同 hakila/auto（給只接受 Claude 名稱的 Claude Desktop 用）
  • 認證可用 x-api-key（Anthropic SDK 預設）或 Authorization: Bearer
  • Claude 模型的 anthropic-version 與 anthropic-beta header 會轉發給上游
  • 錯誤形狀與 Anthropic 一致（{"type":"error","error":{"type","message"}}）
  • 支援 Response Cache header；不支援 Preset（回 400）
  • 上游首字元逾時（預設 30 秒）回傳 504

Authorization

x-api-key<token>

Anthropic 風格的認證 header；與 Authorization: Bearer 擇一即可，兩者都有時以 Bearer 為準。

In: header

Header Parameters

X-Hakila-Cache?string

true 啟用 Response Cache、false 停用。Preset 設為強制關閉時 true 無效； 未帶時依 Preset 設定（預設關閉）。

Value in

  • "true"
  • "false"
X-Hakila-Cache-TTL?string

快取存活秒數（只取前導數字），範圍 1–86400；未帶時用 Preset 設定，否則 300。

X-Hakila-Cache-Clear?"true"

啟用快取時先刪除同一個 cache key 的舊條目，再照常呼叫上游並存入新結果。

Value in

  • "true"

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

只列出 Hakila 會檢查或改寫的欄位；其餘欄位（system、tools、thinking、stream…）與 Anthropic Messages 規格 完全相同，Claude 模型原樣透傳、 其他模型依 Messages 指南 轉換。

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/messages" \  -H "Content-Type: application/json" \  -d '{    "model": "claude-sonnet-5",    "max_tokens": 1024,    "messages": [      {        "role": "user",        "content": "用一句話介紹 Hakila"      }    ]  }'
{  "id": "msg_01",  "type": "message",  "role": "assistant",  "model": "claude-sonnet-5",  "content": [    {      "type": "text",      "text": "Hakila 是統一的 AI Gateway。"    }  ],  "stop_reason": "end_turn",  "usage": {    "input_tokens": 12,    "output_tokens": 10  }}

列出 Response 的 input items GET

對齊 OpenAI `GET /v1/responses/{response_id}/input_items`， query 參數（`after`、`include`、`limit`、`order`）原樣轉發。不計費。

計算 Message 的 input tokens POST

對齊 Anthropic `POST /v1/messages/count_tokens`。路由、允許清單與錯誤形狀和建立 Message 相同； 回傳的 `input_tokens` 只是計數，**不計費**。非 Claude 模型沒有對應的計數端點，回傳本機粗估值； `hakila/auto` 的計數一律交給 Claude。