REST API

Tts

GET /api/v1/tts/voices

功能說明

取得指定語言可用的 TTS 語音列表。每種語言有多個語音可選擇，包含不同性別和風格。

認證方式

Header：X-API-Key（詳見認證機制）

請求參數

參數	類型	位置	必填	說明
`language`	string	query	是	語言代碼（如 `en-US`）

請求範例

curl -X GET "https://vas-poc.vurbo.ai/api/v1/tts/voices?language=en-US" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

成功回應

HTTP 200

{
  "data": {
    "language": "en-US",
    "voices": [
      {
        "voice_name": "en-US-JennyNeural",
        "display_name": "Jenny",
        "gender": "Female",
        "is_default": true,
        "sample_url": "https://vas-poc.vurbo.ai/api/v1/tts/voices/en-US-JennyNeural/sample"
      },
      {
        "voice_name": "en-US-GuyNeural",
        "display_name": "Guy",
        "gender": "Male",
        "is_default": false,
        "sample_url": "https://vas-poc.vurbo.ai/api/v1/tts/voices/en-US-GuyNeural/sample"
      },
      {
        "voice_name": "en-US-AriaNeural",
        "display_name": "Aria",
        "gender": "Female",
        "is_default": false,
        "sample_url": "https://vas-poc.vurbo.ai/api/v1/tts/voices/en-US-AriaNeural/sample"
      },
      {
        "voice_name": "en-US-DavisNeural",
        "display_name": "Davis",
        "gender": "Male",
        "is_default": false,
        "sample_url": "https://vas-poc.vurbo.ai/api/v1/tts/voices/en-US-DavisNeural/sample"
      }
    ]
  }
}

回應欄位說明

欄位	類型	說明
`voice_name`	string	語音識別碼（用於 API 呼叫）
`display_name`	string	語音顯示名稱
`gender`	string	性別：`Female` / `Male`
`is_default`	boolean	是否為該語言的預設語音
`sample_url`	string	語音示範音訊 URL（可直接播放試聽）

特有錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`validation_failed`	400	缺少 `language` 參數或參數格式錯誤	提供有效的 `language` 參數
`tts_invalid_language`	400	不支援的語言	參考支援語言清單取得有效的語言代碼（注意：本 voices 端點若收到不支援 locale 會回傳空 `voices` 陣列而非錯誤；TTS 串流端點 `/api/v1/sse/tts/{taskId}` 才會回此錯誤碼）

GET /api/v1/tts/voices/{voiceName}/sample

功能說明

取得指定語音的示範音訊檔案（MP3 格式）。首次請求會即時合成並快取，後續請求直接從快取返回。

此端點不計入 TTS 費用。

認證方式

Header：X-API-Key（詳見認證機制）

請求參數

參數	類型	位置	必填	說明
`voiceName`	string	path	是	語音名稱（如 `en-US-JennyNeural`）

請求範例

curl -X GET "https://vas-poc.vurbo.ai/api/v1/tts/voices/zh-TW-HsiaoChenNeural/sample" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  --output sample.mp3

成功回應

HTTP 200

回應為 MP3 音訊二進位資料（非 JSON）。

Header	值
`Content-Type`	`audio/mpeg`
`Content-Length`	音訊檔案大小（bytes）
`Cache-Control`	`public, max-age=86400`

限流

每分鐘 30 次/每用戶。超過限制時回傳 HTTP 429。

特有錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`tts_voice_not_found`	404	語音不存在	確認語音名稱是否正確
`tts_sample_generation_failed`	500	語音示範生成失敗	稍後重試
-	429	請求頻率過高	等待後重試（限制 30 次/分鐘）

提示：如需查詢系統支援 TTS 的語言清單，請參考附錄 - 支援語言清單中的 TTS 語音合成支援章節。

版本：V1.5.7 最後更新：2026-05-20

Tasks

Viewer