Messages API

以 Anthropic Messages 規格呼叫 Hakila 的所有模型（Claude Code、Anthropic SDK）

Hakila 提供與 Anthropic 相容的 Messages API，給 Claude Code、Anthropic SDK 等原生客戶端使用，可以呼叫平台上所有 chat 模型：

Claude 模型：除了模型路由、金鑰、允許清單與記帳，請求、回應與 SSE 事件都原樣透傳， thinking、tools、cache_control 等能力由上游 Anthropic 決定。
其他模型（GPT、Gemini、Grok、OpenRouter、地端服務…）：Hakila 把請求轉成各家協定，回應與事件再轉回 Messages 格式，詳見下方非 Claude 模型。

端點

方法	路徑	說明
`POST`	`/v1/messages`	建立訊息（支援 `stream`）
`POST`	`/v1/messages/count_tokens`	計算 input token 數（不產生回應、不計費）

快速開始

Anthropic SDK 把 base_url 指到 https://api.hakila.ai、api_key 換成 Hakila API Key 即可。認證可用 x-api-key（Anthropic SDK 預設）或 Authorization: Bearer，兩者都有時以 Bearer 為準。

curl https://api.hakila.ai/v1/messages \
  -H "x-api-key: $HAKILA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "用一句話介紹 Hakila" }]
  }'

模型與路由

沒有前綴的名稱會在平台目錄找同名模型：claude-sonnet-5 正規成 anthropic/claude-sonnet-5，gemini-4-argon 正規成 google/gemini-4-argon；有多個同名模型時回 400，找不到時回 404（見不帶前綴的模型名稱）。
走 Anthropic 協定的供應商（Anthropic 直連）原樣透傳；其他供應商走轉換模式。同一個模型有多家供應商時依多供應商與備援的順序挑選。
hakila/auto 的候選可落在任何供應商：挑到 Claude 就透傳，挑到其他模型就轉換。請求來自 Claude Code 或 Claude Desktop 時只挑 Claude 模型（見第三方工具只挑自家模型）。
模型仍須出現在 GET /v1/models（平台已啟用並通過允許清單）。
Claude 模型的 anthropic-version 與 anthropic-beta header 會轉發給上游，extended thinking、1 小時快取等 beta 功能由客戶端自行開啟。

非 Claude 模型

GPT、Gemini、Grok 等模型沒有 Messages 端點，Hakila 會先把請求轉成 Chat Completions，經過與 /v1/chat/completions 相同的路由、BYOK、hakila/auto 改道與各家協定轉換，再把結果轉回 Messages 的回應物件與 SSE 事件。Anthropic SDK 與 Claude Code 不需要任何改動。

GPT-5 之後的 OpenAI 推理模型在 Chat Completions 上不能同時使用工具與推理，Hakila 會改打 OpenAI 原生的 Responses API （store: false，不在 OpenAI 保存任何東西）；GPT-4.1、GPT-4o 等較早的模型照舊走 Chat Completions。

curl https://api.hakila.ai/v1/messages \
  -H "x-api-key: $HAKILA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-pro-latest",
    "max_tokens": 4096,
    "thinking": { "type": "enabled", "budget_tokens": 8000 },
    "messages": [{ "role": "user", "content": "用一句話介紹 Hakila" }]
  }'

回應的 model 是你請求的 Hakila 模型 id（例如 google/gemini-pro-latest），id 以 msg_ 開頭。轉換模式不在伺服器端保存任何東西，每次請求都要帶完整的對話歷史——這本來就是 Messages API 的用法。

內容與參數

欄位	行為
`system`（字串或 text block 陣列）	合併成一則 system 訊息
`text`、`image`（base64 或 URL）	轉成各家的文字與圖片輸入
`document`	PDF（base64）轉成檔案輸入；純文字文件當成文字；URL 文件改成文字提示
`tool_use`／`tool_result`	轉成工具呼叫與工具結果；`tool_result` 裡的圖片會接在工具結果之後送出
`max_tokens`、`temperature`、`top_p`	照傳（OpenAI 推理模型不接受取樣參數，會被移除）
`stop_sequences`	轉成 `stop`，最多 4 組；OpenAI 推理模型不支援，會被忽略
`top_k`、`metadata`、`cache_control`、`service_tier`	Anthropic 專屬，不轉發

工具

工具類型	行為
客戶端工具（`name` + `input_schema`）	轉成各家的 function calling
名稱超過 64 字元或含特殊字元（例如很長的 MCP 工具）	送給上游時換成固定的短名稱，回應時還原成原本的名稱
`web_search_20250305` 等 Anthropic 伺服器端工具	移除，被移除的類型列在回應 header `X-Hakila-Dropped-Tools`

tool_choice 的 auto／any／tool／none 都會對應過去，disable_parallel_tool_use 會轉成關閉平行工具呼叫。回應裡 tool_use 的 id 只會含 [a-zA-Z0-9_-]，之後改用 Claude 也不會被拒。

推理

thinking 與 output_config.effort 會換成各家的推理等級：

請求	推理等級
`output_config.effort`	照該值（`low`／`medium`／`high`／`xhigh`／`max`）
`thinking.type: "enabled"` + `budget_tokens`	≤ 2048 → `low`、≤ 8192 → `medium`、≤ 16384 → `high`，更多 → `xhigh`
`thinking.type: "adaptive"`（沒指定 effort）或沒帶 `thinking`	不指定，用各家預設
`thinking.type: "disabled"`	不指定

各家再依模型支援的等級收斂（例如 Gemini 最高到 high），規則與 Responses 的轉換模式相同。

模型回傳的推理摘要（GPT、Grok 等）會以 thinking block 串流（thinking_delta）。各家需要在下一輪原樣送回的推理資料—— OpenAI 的加密推理、Gemini 的 thought signature——會加密放進 thinking block 的 signature，沒有摘要文字時改放在 redacted_thinking block 的 data。只要照 Anthropic 的慣例把上一輪的 content block 原樣送回，推理就能延續。

對話中途切回 Claude 時，Hakila 會在轉發前移除其他模型留下的推理 block，不會讓 Anthropic 以簽章無效回 400；反過來從 Claude 切到其他模型時，Claude 的 thinking block 會被略過。

記帳與快取

依上游實際回報的 usage 計費；回應的 input_tokens 照 Anthropic 慣例不含快取讀寫，快取明細放在 cache_read_input_tokens
Claude 的伺服器端工具由 Anthropic 執行：web_search 每次搜尋另收 US$0.01（依 usage.server_tool_use.web_search_requests，失敗的搜尋不收），搜尋結果本身算在 input tokens；web_fetch 與 code_execution 只收 token
串流時完整的用量（含 input）放在 message_delta 事件，message_start 的用量是 0
串流中途斷線時以已送出的內容估算輸出 tokens
請求紀錄的端點是 /v1/messages、供應商是實際呼叫的那一家，回應內容以 Messages 格式保存
Response Cache 照常運作，命中時重播轉換後的內容

計算 input tokens

/v1/messages/count_tokens 搭配非 Claude 模型時，其他供應商沒有對應的計數端點，Hakila 會以本機粗估回傳 input_tokens（圖片與文件以固定值估算），數字只供參考。hakila/auto 的計數一律交給 Claude。

其他行為

錯誤形狀與 Anthropic 一致：{"type":"error","error":{"type":"invalid_request_error","message":"..."}}，連認證失敗、預算超支（402）與轉換模式的上游錯誤也是。
Streaming：Claude 原樣轉發 Anthropic 的 SSE 事件；轉換模式依同樣的順序產生 message_start、ping、content_block_*、message_delta、message_stop，上游中途出錯時送出 error 事件。
Preset 目前不支援，引用時回 400。
上游首字元逾時（預設 30 秒）回 504。

完整參數與 Schema 請見建立 Message。

本頁目錄