模型與路由

Hakila 的 model 欄位使用 開發商/模型名稱 命名，例如 anthropic/claude-opus-5。前綴是開發這個模型的公司，與實際由哪家供應商提供服務無關：同一個 id 可能由原廠、Amazon Bedrock、Groq 等多家供應商提供，不論走哪家，請求的 model 都一樣。正式環境只轉發平台目錄中已啟用、且通過 允許清單 的 id；不在目錄中的 id 回 404。

權威清單：

curl https://api.hakila.ai/v1/models \
  -H "Authorization: Bearer $HAKILA_API_KEY"

路由表

平台目錄為每個模型列出提供它的供應商，以及各家的上游模型名稱、上下文長度與單價。常見前綴與主要供應商：

其他前綴若已登錄於平台目錄，會依目錄設定的供應商轉發。地端或私有部署（Ollama、vLLM 等 OpenAI 相容服務）由平台管理員在後台新增為供應商後，再把模型掛到該供應商下。Claude 在 Bedrock 上仍走 Anthropic 原生格式，prompt caching 與 thinking 用法與直連相同。

不帶前綴的模型名稱

官方 SDK 只改 base_url 時常會送不帶前綴的名稱，例如 gemini-4-argon、llama-4-maverick。Gateway 會在已啟用的目錄中找名稱部分相同的模型：

• Gateway 不會依命名慣例猜開發商（例如不會因為名稱是 claude-* 就補 anthropic/），一律以目錄為準
• 同名模型類型不同時（例如一個是 chat、一個是 embedding），只比對符合該端點類型的模型
• auto 一律回 400：hakila/auto 與 openrouter/auto 是兩個不同的模型，請寫完整 id
• 舊版的模型 id 不會自動轉換成新 id，請以 GET /v1/models 為準

多供應商與備援

同一個模型 id 可以由多家供應商提供，例如 anthropic/claude-opus-5 由 Anthropic 直連，也由 Amazon Bedrock 提供。各模型的供應商與各自單價列在 Hakila Models 的模型頁，也可以用下方的 endpoints API 查詢。

沒有指定 provider 時，Gateway 依下列順序決定要送哪家：

1. 平台為這個模型設定的供應商優先順序
2. 請求的 provider 偏好（見下節）
3. 組織的供應商限制
4. 略過接不下這個請求的供應商（例如輸入超過該家的上下文長度、需要該家不支援的功能）
5. 略過沒有可用金鑰的供應商；工作區 BYOK 有金鑰的供應商排到最前面（請求指定 provider.order 時不調整）
6. 暫停中的供應商排到最後（見下方「自動暫停」）

送出後：

• 遇到 408、429、500、502、503、504、529，或該供應商回 401～404（例如平台在該供應商尚未開通此模型），或連線失敗，且還沒開始回應時，自動改送下一家。串流已經開始輸出後不會切換
• 費用依實際提供服務的供應商單價計算，同一模型在不同供應商的價格可能不同
• 回應帶 x-hakila-provider header 標示實際提供服務的供應商代號；非串流的 Chat Completions 回應也會在 JSON 加上 provider 欄位（與 OpenRouter 相同）。Request Log 也會記錄供應商與上游模型

自動暫停

同一個模型經同一家供應商在 60 秒內失敗 5 次（408、429 或 5xx），這個組合會暫停 30 秒；之後再次觸發時暫停時間加倍，最長 5 分鐘。暫停中的供應商會排到最後，其他供應商都失敗時仍會嘗試它。401～404 多半是設定問題，會改送下一家但不計入暫停。

查詢模型的供應商

curl https://api.hakila.ai/v1/models/anthropic/claude-opus-5/endpoints \
  -H "Authorization: Bearer $HAKILA_API_KEY"

格式與 OpenRouter 相同，依預設選路順序列出這把 API Key 可用的供應商（已套用組織的供應商限制）：

{
  "data": {
    "id": "anthropic/claude-opus-5",
    "name": "Anthropic: Claude Opus 5",
    "architecture": { "output_modalities": ["text"] },
    "endpoints": [
      {
        "name": "Anthropic | anthropic/claude-opus-5",
        "provider": "anthropic",
        "provider_name": "Anthropic",
        "context_length": 1000000,
        "max_completion_tokens": null,
        "status": "available",
        "pricing": { "prompt": "0.000005", "completion": "0.000025" }
      },
      {
        "name": "Amazon Bedrock | anthropic/claude-opus-5",
        "provider": "bedrock",
        "provider_name": "Amazon Bedrock",
        "context_length": 1000000,
        "max_completion_tokens": null,
        "status": "available",
        "pricing": {
          "prompt": "0.0000055",
          "completion": "0.0000275",
          "input_cache_read": "0.00000055",
          "input_cache_write": "0.000006875"
        }
      }
    ]
  }
}

（數值僅為示意，以實際回應為準。）

• provider 是可以用在請求 provider 欄位的供應商代號
• pricing 是每 token 的 USD 單價；有快取計價時另有 input_cache_read、input_cache_write
• status 為 paused 表示目前處於自動暫停
• 模型不存在或這把 API Key 不能使用時回 404

指定供應商（provider）

Chat Completions、Responses 與 Messages 都接受 OpenRouter 相容的 provider 欄位：

provider 也可以直接給字串，例如 "provider": "bedrock"，等同只用這家、不備援。

• 供應商代號請用 endpoints API 回傳的 provider，例如 openai、anthropic、google、x-ai、deepseek、groq、bedrock。也接受 OpenRouter 的寫法：amazon-bedrock、aws 等同 bedrock，xai 等同 x-ai，google-ai-studio、google-vertex 等同 google
• 提到平台沒有的供應商代號時回 400
• only 列了這個模型沒有的供應商時回 400，訊息會列出可用的供應商；order、ignore 列到這個模型沒有的供應商則略過
• 條件過濾後沒有可用的供應商時回 400
• 只經 OpenRouter 轉接的模型，provider 會原樣轉給 OpenRouter

curl https://api.hakila.ai/v1/chat/completions \
  -H "Authorization: Bearer $HAKILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-opus-5",
    "provider": { "order": ["bedrock"], "allow_fallbacks": true },
    "messages": [{ "role": "user", "content": "hi" }]
  }'

組織的供應商限制

組織管理者可以在 Console → 組織 → 供應商限制，限定組織的請求能經過哪些供應商（例如資料只能留在特定雲端）：

限制會套用到組織所有 API Key 的請求，也會反映在 endpoints API 的結果。某個模型的供應商全部被限制排除時回 403。hakila/auto 選路用的內部供應商不受這項限制。

模型類型

目錄的每一列都有類型，GET /v1/models 以 type 回傳：

把模型送進與類型不符的端點（例如 embedding 模型送進 Chat、chat 模型送進 /v1/audio/speech），都會回 400 並提示正確端點。hakila/auto 只在 chat 模型中選路。

種子目錄裡，hakila/auto 的預設候選為：openai/gpt-6-luna → google/gemini-flash-latest → anthropic/claude-haiku-4-5-20251001 → x-ai/grok-4.3。正式環境以目錄的 IsAutoCandidate 為準，且會再與允許清單取交集。

自動選路（hakila/auto）

指定 hakila/auto 時，Gateway 先算出可用候選（目錄的 auto candidate ∩ 組織 ∩ API Key，且有上游金鑰），再把你這次的請求內容交給 Hakila 內部的選路模型，由它從候選中挑一個。挑出結果後，原始請求會原樣轉發給該模型；選路過程不佔用你的用量，也不會產生額外的請求紀錄。

選路模型沒有回應、逾時，或挑出的不是可用候選時，會自動退回候選順序中第一個可用的模型，你的請求不受影響。回應中的 model 會顯示實際使用的上游模型。

第三方工具只挑自家模型

Gateway 認出請求來自以下工具時，候選只留該工具的模型：

自動判斷不符時，可以帶 X-Hakila-Client header 明確指定：claude-code、claude-desktop、codex；其他值代表不限制。 限縮後沒有候選時回 400，請平台管理員把該類模型（例如 Claude Sonnet、Opus）設為 auto candidate。

回應格式

{
  "data": [
    {
      "id": "hakila/auto",
      "name": "Hakila: Auto",
      "context_length": 2000000,
      "owned_by": "hakila",
      "type": "chat"
    },
    {
      "id": "openai/gpt-5.6-luna",
      "name": "OpenAI: GPT-5.6 Luna",
      "context_length": 1050000,
      "owned_by": "openai",
      "type": "chat"
    },
    {
      "id": "openai/text-embedding-3-small",
      "name": "OpenAI: Text Embedding 3 Small",
      "context_length": 8192,
      "owned_by": "openai",
      "type": "embedding"
    }
  ]
}

種子資料目前涵蓋：

• OpenAI：GPT-6 Astra / Sol / Luna、GPT-5.6 Sol / Terra / Luna、GPT-4.1、GPT-4o / mini；Embeddings：text-embedding-3-large / -small；TTS：gpt-4o-mini-tts、tts-1、tts-1-hd
• Google：Gemini 3.8–3.5 Flash、Flash-Lite、gemini-flash-latest、gemini-pro-latest；Embeddings：gemini-embedding-2、gemini-embedding-001；TTS：gemini-3.1-flash-tts-preview、gemini-2.5-flash-preview-tts、gemini-2.5-pro-preview-tts
• Anthropic：Claude Fable 5.1、Opus 5、Sonnet 5、Haiku 4.5（以上也由 Amazon Bedrock 提供）；經 Amazon Bedrock：Claude Opus 5.5、Sonnet 5.5、Haiku 5.5、Fable 5、Opus 4.8 / 4.7 / 4.6 / 4.5、Sonnet 4.6 / 4.5
• xAI：Grok 4.6（也由 Amazon Bedrock 提供）/ 4.5 / 4.3 / 4.20；經 Amazon Bedrock：Grok 4.7；TTS：x-ai/tts
• 經 Amazon Bedrock：OpenAI GPT-6.1 Sol、GPT-OSS 120B / 20B（含 Safeguard）；Amazon Nova 2 Lite、Nova Pro / Lite / Micro；Meta Llama 4 Maverick / Scout、Llama 3.3 70B、3.1 70B / 8B；Mistral Large 3、Devstral 2、Magistral Small、Ministral 3、Pixtral Large 等；DeepSeek V3.2、R1；Qwen3 Coder、Qwen3 Next、Qwen3 VL、Qwen3 32B；Kimi K3 / K2.5 / K2 Thinking；GLM 5 / 4.7；MiniMax M2.5 / M2.1 / M2；Gemma 3；NVIDIA Nemotron；Writer Palmyra X5 / X4；Embeddings：Amazon Titan Text Embeddings V2 / G1、Cohere Embed v4 / v3。GPT-6、GPT-5.6 也由 Amazon Bedrock 提供
• Azure AI Speech（僅 TTS）：azure/neural-tts、azure/neural-hd-tts、azure/mai-voice-2、azure/mai-voice-2-flash

平台之後可能增刪或改價，請以 GET /v1/models 為準。

範例

# 指定 OpenAI
curl https://api.hakila.ai/v1/chat/completions \
  -H "Authorization: Bearer $HAKILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-5.6-luna","messages":[{"role":"user","content":"hi"}]}'

# 自動選路
curl https://api.hakila.ai/v1/chat/completions \
  -H "Authorization: Bearer $HAKILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"hakila/auto","messages":[{"role":"user","content":"hi"}]}'

hakila/auto 需要至少一個通過允許清單、且有上游金鑰的候選；否則回 400（沒有候選）或 502（有候選但都沒金鑰）。