文字轉語音介面

平台提供相容於 AI Platform 的文字轉語音介面。是否可用取決於目前 API keys 的分組與模型目錄： 請先在 GET /v1/models 中確認存在可用的音訊模型，再呼叫本介面。

請求

項目	值
方法	`POST`
路徑	`/v1/audio/speech`
驗證	`Authorization: Bearer <API_KEY>`
請求標頭	`Content-Type: application/json`
回應	二進位音訊（不是 JSON）

傳回的是二進位音訊，不是 JSON —— 所以請使用 --output（或 -o）將回應直接寫成檔案。若把它當成 JSON 解析，會得到空白的回應內容。

voice 的可用取值取決於目前模型，並非所有模型都接受 alloy。

請求

curl -X POST "$LOCOPAL_BASE_URL/v1/audio/speech" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的音频模型 ID",
    "input": "欢迎使用 LocoPal Ai。",
    "voice": "alloy",
    "response_format": "mp3"
  }' \
  --output speech.mp3

請求參數

參數	類型	說明
`model`	string	必填。`GET /v1/models` 傳回的音訊模型 `data[].id`。
`input`	string	必填。要合成的文字。長度上限以實際模型為準。
`voice`	string	音色名稱。可用音色取決於目前模型，請以模型詳情為準。
`response_format`	string	輸出音訊格式，例如 `mp3`。支援的格式以實際模型為準。
`speed`	number	語速。是否支援及取值範圍以實際模型為準。

音色、格式與語速的可用範圍因模型而異。不要假設所有模型都支援 alloy 或 mp3，也不要把某個模型的音色清單寫死在程式碼裡。

回應

成功

成功回應的內容是二進位音訊資料，不是 JSON。直接寫入檔案或串流轉發給用戶端即可。

# 保存为文件
curl ... --output speech.mp3

# 检查确实是音频而不是 JSON
file speech.mp3

失敗

失敗時會傳回帶有 error 物件的非 2xx 回應，結構與模型介面一致：

{
  "error": {
    "code": "invalid_parameter",
    "message": "..."
  }
}

常見的失敗原因：

情況	表現	處理
分組中沒有音訊模型	`model_not_found` 或模型無法使用	使用 `GET /v1/models` 確認可用的音訊模型
音色不受該模型支援	`invalid_parameter`	改用該模型支援的音色
格式不受該模型支援	`invalid_parameter`	改用支援的 `response_format`
請求過於頻繁	HTTP `429`	依提示退避重試

伺服器端接入建議

文字轉語音是同步介面，回應即為音訊資料，接入時請注意：

不要把它當成 JSON 解析。請先判斷 HTTP 狀態與 Content-Type，只有失敗時才以 JSON 讀取 error；
將音訊直接透傳給瀏覽器時，不要忘記設定 Content-Type，否則瀏覽器會把它當成文字處理；
控制 input 長度。過長的文字建議在業務端切分，分段合成後再拼接，避免單次請求超過上限；
音訊檔案建議轉存到自己的儲存空間，不要長期依賴平台傳回的暫存結果；
業務後端應快取高頻重複的合成結果，避免重複計費。

非同步音訊任務

除本同步介面外，平台還提供非同步的音訊生成能力（例如配樂、音效）。這類任務的狀態與成品可在主控台「任務日誌」中查詢，處理方式與影片任務類似：建立後儲存任務 ID，使用查詢介面輪詢到終態，不要重複建立。

計費

音訊介面的計費方式以模型廣場的模型詳情為準，可能依 Token、依次數或依時長計費。計費與結算規則請見計費與帳單。

文字轉語音介面

文字轉語音介面

請求

請求參數

回應

成功

失敗

伺服器端接入建議

非同步音訊任務

計費

相關文件

本頁目錄