REST API

Tts

GET /api/v1/tts/voices

Description

Retrieve the list of available TTS voices for a given language. Each language offers multiple voices to choose from, covering different genders and styles.

Authentication

Header: X-API-Key (see Authentication)

Request Parameters

Parameter	Type	Location	Required	Description
`language`	string	query	Yes	Language code (e.g. `en-US`)

Request Example

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

Success Response

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"
      }
    ]
  }
}

Response Fields

Field	Type	Description
`voice_name`	string	Voice identifier (used in API calls)
`display_name`	string	Display name of the voice
`gender`	string	Gender: `Female` / `Male`
`is_default`	boolean	Whether this is the default voice for the language
`sample_url`	string	Sample audio URL for the voice (playable directly for preview)

Specific Error Codes

Error Code	HTTP Status	Description	Recommended Action
`validation_failed`	400	Missing `language` parameter or invalid parameter format	Provide a valid `language` parameter
`tts_invalid_language`	400	Unsupported language	Refer to the supported language list for valid language codes (note: if this voices endpoint receives an unsupported locale, it returns an empty `voices` array rather than an error; only the TTS streaming endpoint `/api/v1/sse/tts/{taskId}` returns this error code)

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

Description

Retrieve the sample audio file (MP3 format) for a given voice. The first request synthesizes and caches the audio in real time; subsequent requests are served directly from the cache.

This endpoint does not count toward TTS usage charges.

Authentication

Header: X-API-Key (see Authentication)

Request Parameters

Parameter	Type	Location	Required	Description
`voiceName`	string	path	Yes	Voice name (e.g. `en-US-JennyNeural`)

Request Example

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

Success Response

HTTP 200

The response is binary MP3 audio data (not JSON).

Header	Value
`Content-Type`	`audio/mpeg`
`Content-Length`	Audio file size (bytes)
`Cache-Control`	`public, max-age=86400`

Rate Limiting

30 requests per minute per user. Requests exceeding the limit return HTTP 429.

Specific Error Codes

Error Code	HTTP Status	Description	Recommended Action
`tts_voice_not_found`	404	Voice not found	Verify that the voice name is correct
`tts_sample_generation_failed`	500	TTS sample generation failed	Retry later
-	429	Request rate too high	Wait and retry (limit: 30 requests/minute)

Tip: To look up the list of languages that support TTS, refer to the TTS speech synthesis support section in Appendix - Supported Language List.

Version: V1.5.7 Last Updated: 2026-05-20

Tasks

Viewer