文字轉語音

文字轉語音會讀取一段文字並回傳音訊檔案。介面遵循 OpenAI 語音合成慣例：請求主體是 JSON，回應主體就是音訊本身，沒有非同步任務或輪詢步驟。

如果你的用戶端 Base URL 設定時沒有 /v1，POST /audio/speech 同樣可用；閘道會在內部將它改寫為 /v1/audio/speech。

端點

POST /v1/audio/speech

https://api.routeapi.ai/v1/audio/speech

請求參數

請求主體為 JSON。RouteAPI 本身只驗證 model，其餘欄位都會轉發給上游模型，可接受的值取決於該模型。

欄位	類型	必填	說明
`model`	string	是	TTS 模型 ID，例如 `tts-1`、`tts-1-hd` 或 `gpt-4o-mini-tts`。它必須出現在請求主體中：空值或缺少時會返回 `400` 與 `Missing required field: model`（路由有 `tts-1` 的備援，但驗證會先執行）
`input`	string	上游必填	要合成的文字。閘道也會依這個欄位估算輸入 token 以計費
`voice`	string	上游必填	語音名稱。可用的語音集合因模型而異
`response_format`	string	否	音訊容器，轉發給上游。省略時套用上游預設值。閘道也會用這個值量測返回音訊的時長以計費，並將省略值視為 `mp3`；`pcm` 以 24 kHz、16 位元、單聲道量測
`speed`	number	否	播放速度倍率，有值時原樣轉發
`instructions`	string	否	給支援此功能的模型（例如 `gpt-4o-mini-tts`）的語氣/風格指示
`stream_format`	string	否	設為 `sse` 時，以 Server-Sent Events 接收音訊，而非單一二進位主體。這個值會原樣轉發；只有支援串流 TTS 的上游才會實際串流
`metadata`	object	否	某些渠道類型會併入自身上游請求的額外欄位（例如火山引擎 TTS 或 MiniMax）

範例

curl

curl https://api.routeapi.ai/v1/audio/speech \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "voice": "alloy",
    "input": "RouteAPI aggregates many AI providers behind a single API.",
    "response_format": "mp3"
  }' \
  --output speech.mp3

Python (OpenAI SDK)

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1",
)

with client.audio.speech.with_streaming_response.create(
    model="tts-1",
    voice="alloy",
    input="RouteAPI aggregates many AI providers behind a single API.",
    response_format="mp3",
) as response:
    response.stream_to_file("speech.mp3")

client.audio.speech.create(...) 同樣可用，並返回 response.content，也就是原始音訊位元組。可用 open("speech.mp3", "wb").write(response.content) 儲存。

回應

主體是音訊檔案本身，不是 JSON。閘道會讀取上游主體以量測時長用於計費，然後以與你實際收到的內容相符的 Content-Length 寫出。只有一小份允許清單中的上游標頭會原樣傳遞——特別是 Content-Type（例如 audio/mpeg），你可以靠它決定副檔名；其他上游標頭（例如 Server）會被丟棄。只有當上游主體未被閘道解壓縮時，才會轉發 Content-Encoding。

使用 "stream_format": "sse" 時，回應為 text/event-stream。每個音訊區塊都以 data: 框架送達；如果上游送出最後的 usage 區塊，閘道會讀取它來計費；否則按估算值計費。

計費

音訊呼叫與其他所有模型呼叫 API 請求一樣，透過相同的錢包與額度機制計費：先預扣一筆預估金額，上游回應後結算，失敗的呼叫會退還。價格來自模型的設定——音訊價格如何顯示在模型詳情頁，參見模型定價。

適用哪種方式取決於模型如何計價，模型的詳情頁會顯示：

每次請求固定價格。 如果模型設定了每次請求價格，請求會按該價格乘以你的分組倍率收費，token 不影響金額。在內建預設中，gpt-4o-mini-tts 已是這樣設定——請查看詳情頁，不要假設是按 token 計價。
依 token 計費。 否則費用會依下方的用量計算。

輸入

輸入由 input 估算。閘道對多數模型按字元計數，對模型 ID 含 gpt 的模型使用分詞器，然後依模型的倍率收取該計數的費用。

輸出

生成的音訊以每分鐘音訊 1000 個 token 換算：閘道從返回的音訊讀取時長，並收取 ceil(duration) / 60 × 1000 個輸出 token，價格為模型倍率乘上其音訊倍率、再乘上其音訊輸出倍率。如果無法量測音訊時長，則回退為大約每千位元組音訊一個 token。

內建的音訊輸出倍率對 tts-1 / tts-1-hd 系列為 0，因此在 token 計價下，這些模型生成的音訊不會產生額外費用，按字元計算的輸入實際上就是全部費用。音訊輸出倍率非零的模型，生成音訊也會一併收費。

時長量測取決於 response_format：pcm 沒有容器標頭，因此其時長由位元組數以 24 kHz / 16 位元 / 單聲道換算；其他格式則從容器解析。

由於輸出 token 是從返回的檔案推導而來，費用跟隨實際生成的內容，而不只是 input 的長度。

錯誤

錯誤使用標準的 { "error": { ... } } 主體，訊息中會帶一個 request ID，你可以在控制台日誌中搜尋。完整清單參見常見錯誤。

狀態碼	錯誤碼	原因
400	`invalid_request`	`model` 缺少或為空（`Missing required field: model`）
403	`insufficient_user_quota` / `pre_consume_token_quota_failed`	帳戶餘額或 Key 額度不足以涵蓋預估費用
403	—	模型不在該 Key 的模型白名單中（`This token has no access to model ...`）
429	—	請求速率超過限制
503	`model_not_found`	模型沒有可用渠道（`No valid upstream service`）
500	`convert_request_failed`	請求無法為該渠道轉換——例如渠道適配器未實作文字轉語音
4xx / 5xx	上游錯誤碼	供應商拒絕了請求；狀態碼與訊息會原樣傳遞

{
  "error": {
    "message": "Missing required field: model (request id: 20261023153000123456789AbCdEfGh)",
    "type": "error",
    "code": "invalid_request"
  }
}

請求失敗時，預扣的費用會退還。

下一步

語音轉文字 —— 轉錄或翻譯音訊檔案。
模型 —— 呼叫前先確認模型 ID 對你的 Key 可見。
模型定價 —— 音訊輸入與輸出價格如何顯示。
常見錯誤 —— 狀態碼、錯誤主體與排查順序。