Hakila Docs
Embeddings

建立 Embeddings

對齊 OpenAI Embeddings 規格（`POST https://api.openai.com/v1/embeddings`）。 `model` 必須是平台目錄中 `type: embedding`、已啟用、且通過組織 ∩ API Key 允許清單的 id。 - **OpenAI**（`openai/text-embedding-3-*` 等）：原樣轉發，`dimensions`、`encoding_format`、token 陣列 input 都由上游處理 - **Gemini**（`google/gemini-embedding-*`）：Hakila 翻譯成原生 `batchEmbedContents`， `dimensions` → `outputDimensionality`、`task_type` → `taskType`、`title` 對應帶入；回應轉回 OpenAI 形狀 - 後台新增的 OpenAI 相容供應商（地端服務等）與 xAI 走 OpenAI 相容 `/embeddings` - Anthropic 沒有 Embeddings API；把 chat 模型帶進來會回 `400` 並提示改用 `/v1/chat/completions` - 沒有前綴的 `model` 會在已啟用的 embedding 模型中比對名稱並補上開發商前綴；有多個同名模型時回 `400`，找不到時回 `404` - 不支援 `hakila/auto`、Preset 與 streaming - 只以輸入 tokens 計費（`usage.prompt_tokens`）；Gemini 原生 API 不回 usage，Hakila 以文字長度估算 - 支援 Response Cache header：同一組 input 的向量是穩定的，命中時不呼叫上游、不計費 - 上游首字元逾時（預設 30 秒）回傳 `504`

POST/v1/embeddings

對齊 OpenAI Embeddings 規格（POST https://api.openai.com/v1/embeddings）。 model 必須是平台目錄中 type: embedding、已啟用、且通過組織 ∩ API Key 允許清單的 id。

  • OpenAI（openai/text-embedding-3-* 等）：原樣轉發，dimensions、encoding_format、token 陣列 input 都由上游處理
  • Gemini（google/gemini-embedding-*）：Hakila 翻譯成原生 batchEmbedContents， dimensions → outputDimensionality、task_type → taskType、title 對應帶入；回應轉回 OpenAI 形狀
  • 後台新增的 OpenAI 相容供應商（地端服務等）與 xAI 走 OpenAI 相容 /embeddings
  • Anthropic 沒有 Embeddings API；把 chat 模型帶進來會回 400 並提示改用 /v1/chat/completions
  • 沒有前綴的 model 會在已啟用的 embedding 模型中比對名稱並補上開發商前綴；有多個同名模型時回 400，找不到時回 404
  • 不支援 hakila/auto、Preset 與 streaming
  • 只以輸入 tokens 計費（usage.prompt_tokens）；Gemini 原生 API 不回 usage，Hakila 以文字長度估算
  • 支援 Response Cache header：同一組 input 的向量是穩定的，命中時不呼叫上游、不計費
  • 上游首字元逾時（預設 30 秒）回傳 504

Authorization

bearerAuth
AuthorizationBearer <token>

在 Authorization 標頭帶入 Workspace API Key： Authorization: Bearer sk-hakila-...

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.

對齊 OpenAI Embeddings。 OpenAI 模型原樣轉發；Gemini 模型由 Hakila 翻譯成原生 batchEmbedContents。

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/embeddings" \  -H "Content-Type: application/json" \  -d '{    "model": "openai/text-embedding-3-small",    "input": "Hakila 是統一的 AI Gateway。"  }'
{  "object": "list",  "data": [    {      "object": "embedding",      "index": 0,      "embedding": [        0.0023064255,        -0.009327292,        0.015797347      ]    }  ],  "model": "text-embedding-3-small",  "usage": {    "prompt_tokens": 8,    "total_tokens": 8  }}

建立 Chat Completion POST

對齊 OpenAI Chat Completions 規格。`model` 必須是平台目錄中已啟用、且通過組織 ∩ API Key 允許清單的 id。 - Gateway 強制驗證 `model`；`messages` 請一併帶入（文件 Try it 與實務皆需要） - 設定 `"stream": true` 時以 SSE（`text/event-stream`）回傳 - 轉發時把 model id 換成該供應商的上游模型名稱 - 同一模型有多家供應商時，依平台優先順序 → `provider` 偏好 → 組織供應商限制 → 金鑰（BYOK 優先）挑選， 429／5xx 等錯誤且尚未開始回應時自動改送下一家；費用依實際供應商單價計算（見[多供應商與備援](/docs/guides/models#多供應商與備援)） - 回應 header `x-hakila-provider` 標示實際提供服務的供應商；非 streaming 回應的 JSON 另有 `provider` 欄位 - 未知欄位會盡可能透傳給上游（pass-through）；空的 `tools`／`response_format`／`tool_choice` 會在轉發前移除 - `hakila/auto` 會先把請求內容交給內部選路模型，從通過允許清單的 auto candidate 中挑一個； 選路失敗時退回候選順序中第一個有上游金鑰者 - 上游首字元逾時（預設 30 秒）回傳 `504` - `model` 可引用工作區 Preset：`@preset/slug` 或 `openai/gpt-4o@preset/slug`，也可用 `preset` 欄位（見 [Presets](/docs/guides/presets)） - `usage.prompt_tokens_details` 回報 Prompt Cache 讀取／寫入 tokens（見 [Prompt Cache](/docs/guides/prompt-cache)） - `X-Hakila-Cache: true` 啟用 Response Cache，命中時不呼叫上游、不計費（見 [Response Cache](/docs/guides/response-cache)）

文字轉語音 POST

對齊 OpenAI Audio Speech 規格（`POST https://api.openai.com/v1/audio/speech`）。 `model` 必須是平台目錄中 `type: tts`、已啟用、且通過組織 ∩ API Key 允許清單的 id。 成功時回應本體就是音訊位元組，`Content-Type` 依 `response_format`。 - **OpenAI**（`openai/gpt-4o-mini-tts`、`openai/tts-1*`）：原樣轉發，`voice`／`instructions`／`speed`／`stream_format: sse` 由上游處理；沒帶 `voice` 時補 `alloy` - **Gemini**（`google/gemini-*-tts*`）：Hakila 翻譯成原生 `generateContent`（`responseModalities: ["AUDIO"]`）， `voice` → `prebuiltVoiceConfig.voiceName`（預設 `Kore`）、`instructions` 併入提示、`language` → `languageCode`、 `speakers` → `multiSpeakerVoiceConfig`；只支援 `response_format` `wav`（預設，由 Hakila 補檔頭）與 `pcm` - **xAI**（`x-ai/tts`）：翻譯成 `POST /v1/tts`，`voice` → `voice_id`（預設 `eve`）、`language`（預設 `auto`）、 `response_format` → `output_format.codec`（`mp3`／`wav`／`pcm`／`mulaw`／`alaw`）、`sample_rate`、`speed`；`instructions` 忽略 - **Azure AI Speech**（`azure/neural-tts`、`azure/neural-hd-tts`、`azure/mai-voice-2`、`azure/mai-voice-2-flash`）：翻譯成 SSML，`voice` 為完整語音名稱， 且須屬於模型的語音家族（標準 Neural／Dragon 與 DragonHD／MAI-Voice-2／MAI-Voice-2 Flash，不符回 `400`）； `speed` → `prosody rate`、`language` → `xml:lang`、`style`／`style_degree`／`role` → `mstts:express-as`； `input` 以 `<speak` 開頭時視為完整 SSML 原樣送出（仍檢查 `<voice name>` 的家族）；`response_format` 支援 `mp3`／`wav`／`pcm`／`opus` - 後台新增的 OpenAI 相容供應商（自架服務等）走 OpenAI 相容 `/audio/speech` - Anthropic 沒有 TTS API；把 chat／embedding 模型帶進來會回 `400` 並提示正確端點 - 沒有前綴的 `model` 會在已啟用的 tts 模型中比對名稱並補上開發商前綴；有多個同名模型時回 `400`，找不到時回 `404` - 不支援 `hakila/auto`、Preset 與 Response Cache - 計費：OpenAI／xAI／Azure 以 `input` 字元數記在 `prompt_tokens`（單價為 USD / 1M 字元）； Gemini 使用真實 usage（文字輸入 tokens／音訊輸出 tokens）。上游錯誤或沒有回音訊時不計費 - 上游首字元逾時（預設 30 秒）回傳 `504`