Hakila Docs
Audio

文字轉語音

對齊 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`

POST/v1/audio/speech

對齊 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

Authorization

bearerAuth
AuthorizationBearer <token>

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

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

對齊 OpenAI Audio Speech。 OpenAI 模型原樣轉發；Gemini、xAI、Azure 由 Hakila 翻譯成各自的原生 API。 language、sample_rate、speakers、style、style_degree、role 為 Hakila 延伸欄位，對 OpenAI 相容上游會被移除。

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/audio/speech" \  -H "Content-Type: application/json" \  -d '{    "model": "openai/gpt-4o-mini-tts",    "input": "今天的天氣真好，適合出門走走。",    "voice": "coral",    "instructions": "用溫暖、友善的語氣說話。",    "response_format": "mp3"  }'
"string"

建立 Embeddings POST

對齊 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`

生成或編輯圖片（OpenRouter 形狀） POST

對齊 [OpenRouter Image API](https://openrouter.ai/docs/api/api-reference/images/create-image)。 `model` 必須是 `type: image`、已啟用、且通過組織 ∩ API Key 允許清單的 id（用 `GET /v1/images/models` 查詢）。 帶 `input_references` 就是以圖生圖／編輯；同一個端點涵蓋文字生圖與編輯。 **參數處理**（依模型的 `supported_parameters`）： - 明確不支援的要求回 `400`：參考圖或遮罩、超過上限的 `n`、透明背景、enum 以外的值 - `aspect_ratio` 不在清單時自動調到最接近的支援值 - 模型沒有對應旋鈕的參數（`quality`、`seed`、`output_compression`…）直接忽略 - 所有調整與忽略列在回應 header `X-Hakila-Adjusted-Params`（例如 `aspect_ratio=5:3>16:9, seed=ignored`） **計費與限制**： - 全有全無：上游失敗或用戶端中途斷線不扣點；`n > 1` 部分成功時只算成功送達的張數 - 送出前以「每張最高費用 × 張數」預估，超過任何一層預算或儲值餘額回 `402` - API Key 與組織可設每日張數上限（台北時間 00:00 重置），超過回 `429`（`code: image_quota_exceeded`） - 提示詞與參考圖會先經過內容審核，未通過回 `400`（`code: content_policy_violation`）； 各供應商的安全設定一律用最嚴格等級，`moderation: low` 會被改回 `auto` - 不支援 `hakila/auto`、Preset 與 Response Cache