語音轉文字

通用資訊

• Base URL：https://api.routeapi.ai
• 認證：Authorization: Bearer $ROUTEAPI_KEY，使用 sk- 開頭的 API Key（在控制台 API Keys 頁面建立）。rat_ 開頭的管理金鑰不能呼叫模型。
• 錯誤格式：{"error": {"message": "...", "type": "...", "code": "..."}}，狀態碼含義見常見錯誤。

RouteAPI 提供兩個 OpenAI 語音轉文字端點：轉錄依音訊原語言回傳文字，翻譯則一律回傳英文。兩者都以 multipart/form-data 送出，結果在同一個回應中返回——沒有非同步任務或輪詢步驟——並且與模型呼叫 API 的其他介面使用同一個 API Key 認證。

端點	用途	回應
POST /v1/audio/transcriptions	音訊轉文字，使用來源語言	JSON 或文字，取決於 response_format
POST /v1/audio/translations	音訊轉英文文字	JSON 或文字，取決於 response_format

如果你的用戶端 Base URL 設定時沒有帶上 /v1，POST /audio/transcriptions 和 POST /audio/translations 同樣可用；閘道會在內部改寫為 /v1 路徑。

模型列表不會標示音訊模型

RouteAPI 內建的端點類型沒有音訊這個值，因此在 GET /v1/models 中，轉錄模型與對話模型無法區分：它的 supported_endpoint_types 反映的是服務它的渠道類型（最常見是 openai）。請從列表中挑選模型 ID，再用該 ID 呼叫音訊路徑。參見模型。

語音轉錄

以原始語言轉錄音訊檔案。請以 multipart/form-data 送出。

POST /v1/audio/transcriptions

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

請求參數

欄位	類型	必填	說明
file	file	是	音訊檔案。只會轉發第一個 file 部分
model	string	是	轉錄模型 ID，例如 whisper-1、gpt-4o-transcribe 或 gpt-4o-mini-transcribe
response_format	string	否	要求的輸出格式，例如 json、text、srt、vtt 或 verbose_json。RouteAPI 會將 json 記錄為預設值，但不會把預設值寫入轉發的表單——省略這個欄位時，由上游套用自己的預設值，上游主體會原樣返回
language	string	否	ISO-639-1 語言提示，轉發給上游
prompt	string	否	上下文/術語提示，轉發給上游
temperature	number	否	取樣溫度，轉發給上游
timestamp_granularities[]	array	否	時間戳細節層級；會原樣轉發，且在上游只有搭配 verbose_json 才有意義

其他表單欄位也會一併轉發。 閘道會從你的表單重建 multipart 主體：它自己寫入 model、複製第一個檔案部分，並把其餘所有文字欄位原樣複製。RouteAPI 只驗證 model；chunking_strategy 這類欄位是否被採用，由上游模型決定。

範例

curl https://api.routeapi.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -F "file=@./meeting.mp3" \
  -F "model=whisper-1" \
  -F "response_format=json" \
  -F "language=en"

import os

from openai import OpenAI

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

with open("meeting.mp3", "rb") as audio_file:
    transcript = client.audio.transcriptions.create(
        model="whisper-1",
        file=audio_file,
        response_format="json",
    )

print(transcript.text)

回應

上游回應主體會原樣返回，只會正規化 Content-Type 與 Content-Length。當 response_format 設為 json——OpenAI 相容上游的預設值——你會得到：

{
  "text": "This is the transcribed content of the uploaded audio."
}

使用 verbose_json 時，通常還會得到 task、language、duration 與 segments；使用 text、srt 或 vtt 時，主體是純文字而非 JSON。特定模型實際支援其中哪些，由供應商定義——RouteAPI 不會重塑主體。

請使用閘道可量測的容器

為了估算時長，閘道會在請求送往上游前，依副檔名讀取上傳檔案的長度。支援 mp3、wav、flac、m4a/mp4、ogg/oga、opus、aac 與 aiff。無法量測的容器——特別是 WebM——會讓 token 估算失敗，請求會返回錯誤而不是轉錄結果。請先將這類檔案轉換為 mp3 或 wav 再上傳。（這在 token 計數啟用時適用，而 token 計數預設為啟用。）

語音翻譯

multipart 結構與轉錄相同，但輸出一律是英文文字，不論輸入語言。適用相同的欄位（file、model、response_format、prompt、temperature）。來源語言由模型偵測，因此翻譯介面沒有 language 參數——閘道會轉發額外的表單欄位，但不接受這些欄位的上游可能會拒絕請求。

POST /v1/audio/translations

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

curl https://api.routeapi.ai/v1/audio/translations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -F "file=@./interview-de.mp3" \
  -F "model=whisper-1"

import os

from openai import OpenAI

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

with open("interview-de.mp3", "rb") as audio_file:
    result = client.audio.translations.create(
        model="whisper-1",
        file=audio_file,
    )

print(result.text)

計費

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

• 如果上游回應包含 usage 物件且 total_tokens 非零，就按該用量計費（prompt_tokens/completion_tokens 缺席時，改用 input_tokens/output_tokens）。
• 如果上游未回報用量，閘道會回退到時長估算：每分鐘上傳音訊 1000 個 token，且沒有輸出 token。在按 token 計價的模型上，同一個估算也會驅動預扣（下限為閘道對任何請求的最低預扣金額）。
• 如果回報的用量帶有音訊 token 明細，這些 token 按音訊費率計價；否則按一般輸入 token、以模型倍率計價。時長回退沒有音訊明細，這也是為什麼每分鐘 1000 個 token 會與每分鐘費率對得上。
• 套用回退時，轉錄成本取決於音訊長度，而不是返回多少文字。當上游確實回報用量時，以回報的明細為準。

注意

上述每分鐘與每 token 的費率是閘道的計費規則；實際扣款金額是模型設定的價格乘以你的分組倍率。大批量處理前，請先在模型廣場確認費率。

錯誤

音訊請求使用標準的 { "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	count_token_failed	無法量測上傳音訊的時長（不支援的副檔名或容器）
500	convert_request_failed	請求無法為該渠道轉換——例如沒有 file 部分的轉錄，或適配器未實作音訊的渠道
4xx / 5xx	上游錯誤碼	供應商拒絕了請求；狀態碼與訊息會原樣傳遞

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

有兩種失敗模式值得事先準備，因為它們很容易被誤認為供應商問題：

• 缺少 file 的轉錄或翻譯不會被閘道的驗證層攔下；它會在之後以 convert_request_failed 出現。請確認欄位名稱正好是 file，且用戶端確實附加了部分。
• 不支援的音訊容器會在 token 估算階段失敗，發生在任何上游呼叫之前，因此會回報為 count_token_failed，而不是上游錯誤。

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

下一步

• 文字轉語音 —— 將文字合成為語音。
• 模型 —— 呼叫音訊端點前，先確認模型 ID 對你的 Key 可見。
• 模型定價 —— 音訊輸入與輸出價格如何顯示。
• 常見錯誤 —— 狀態碼、錯誤主體與排查順序。