List Voices API
Find voices available for speech synthesis, including their IDs, names, descriptions, languages, and audio previews. Requests return system voices by default. Set source=personal to list personal voices accessible to your API key's organization.
Use the current API response when choosing a voice. Voices can be added or retired, so this page does not maintain a complete static catalog.
The model defaults and availability below apply to releases that include Luna-TTS 1.5. Earlier deployments keep their existing behavior; use the catalog for the API endpoint you call.
Model selection
Use model_id=luna-tts-1.5 for Chinese, English, Japanese, and Korean, including legacy and new 1.5 voices. luna-tts selects the legacy version and excludes 1.5-only voices. latest resolves to the latest enabled Luna version, currently 1.5. Character uses luna-tts-character. Pass the same model when listing and synthesizing; incompatible combinations return 12913 VOICE_MODEL_INCOMPATIBLE.
Endpoint
- Method and path:
GET /v1/voices - Authentication:
X-API-Keyrequest header - Success response: HTTP
200,Content-Type: application/json
The API key must have Text to Speech access. Personal voice queries use organization access and do not require permission to create cloned voices.
Listing voices does not generate audio or incur speech synthesis charges. See Get your API key to create a key.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
source | string | No | system (default) or personal. Each request lists one source. all is not supported. |
model_id | string | No | Return only voices compatible with a public model ID, for example luna-tts-1.5, latest, luna-tts, or luna-tts-character. Omit to skip model filtering. |
language | string | No | Filter by the voice's labeled primary language: zh (Chinese), en (English), ja (Japanese), or ko (Korean) in the current system catalog. Omit to include all languages. |
search | string | No | Match a substring in voice names and descriptions. Maximum 100 characters after trimming surrounding whitespace. |
page_size | integer | No | Items per page: 1–100, default 20. |
cursor | string | No | The preceding response's next_cursor. Omit for the first page. |
Defaults apply only when source and page_size are omitted. An explicit empty source, an empty or zero page_size, and empty model_id or language values are rejected. An empty or whitespace-only search does not filter results; an empty cursor starts at the first page. Send each query parameter only once. Use only the query parameters listed above; do not add organization or user ID parameters to select another scope.
System and personal voices have separate ordering and pagination. Continue with the same API key, project, user and organization context, page_size, and query filters. When changing any of these, omit the old cursor and start a new query. Cursors are opaque; pass them unchanged.
Request examples
Set the API base URL and your API key:
export VUILABS_API_BASE_URL="https://api.vuilabs.ai"
export VUILABS_API_KEY="your-api-key"
List system voices using the default source:
curl --get "$VUILABS_API_BASE_URL/v1/voices" \
--header "X-API-Key: $VUILABS_API_KEY"
Find English system voices compatible with legacy Luna-TTS (use luna-tts-1.5 for 1.5):
curl --get "$VUILABS_API_BASE_URL/v1/voices" \
--header "X-API-Key: $VUILABS_API_KEY" \
--data-urlencode 'model_id=luna-tts' \
--data-urlencode 'language=en' \
--data-urlencode 'page_size=20'
List your organization's personal voices:
curl --get "$VUILABS_API_BASE_URL/v1/voices" \
--header "X-API-Key: $VUILABS_API_KEY" \
--data-urlencode 'source=personal'
Response fields
A successful response contains these fields directly:
| Field | Type | Description |
|---|---|---|
voices | array | Voices in the current page; [] when no voices match. |
has_more | boolean | Whether another page is available. |
next_cursor | string / null | Cursor for the next page; null when there is no next page. |
System and personal voices use the same structure:
| Field | Type | Description |
|---|---|---|
voice_id | string | Public voice ID for synthesis requests with a compatible model. |
name | string | Voice name. |
description | string / null | Voice introduction. |
language | string / null | Labeled primary language: zh, en, ja, or ko in the current system catalog; null if not labeled. |
gender | string / null | Stored gender metadata, such as male or female; null when not labeled. |
age | string / null | Stored age-group metadata, such as young, adult, or elderly; null when not labeled. |
descriptive | string / null | Stored free-text voice style, such as Sweet and gentle; null when not labeled. This is not an enum or a synthesis control. |
preview_url | string / null | Audio preview URL; null if no preview is available. |
preview_url_expires_at | integer / null | Expiration as a Unix timestamp in seconds; null for a permanent URL or no URL. |
source | string | system or personal. |
supported_model_ids | string[] | Public model IDs currently compatible with this voice. |
Gender, age, and style are actual catalog metadata and can vary by voice; they are not additional synthesis parameters or query filters. Descriptive attributes are null when unavailable. The language label does not enumerate all cross-language synthesis capabilities. Preview URLs can differ between models, even for the same voice_id. Query with the intended model and use its returned URL; do not construct a URL or reuse another model’s preview. This API does not return an avatar URL. If a preview has an expiration time, use it before expiration or query again for a new URL.
The following illustrates the response structure. The current API response determines voice availability and metadata:
{
"voices": [
{
"voice_id": "michael",
"name": "Michael",
"description": "Clear, approachable young American male voice.",
"language": "en",
"gender": null,
"age": null,
"descriptive": null,
"preview_url": null,
"preview_url_expires_at": null,
"source": "system",
"supported_model_ids": ["luna-tts"]
}
],
"has_more": false,
"next_cursor": null
}
No matching results is also a successful response:
{
"voices": [],
"has_more": false,
"next_cursor": null
}
Pagination
When has_more is true, keep the query filters unchanged and pass next_cursor as the next request's cursor. This Python example lists system voices for a model and reads their IDs and previews:
import os
import requests
params = {"source": "system", "model_id": "luna-tts", "page_size": 20}
headers = {"X-API-Key": os.environ["VUILABS_API_KEY"]}
while True:
response = requests.get(
f"{os.environ['VUILABS_API_BASE_URL']}/v1/voices",
headers=headers,
params=params,
timeout=30,
)
response.raise_for_status()
payload = response.json()
for voice in payload["voices"]:
print(voice["voice_id"], voice["name"], voice["preview_url"])
if not payload["has_more"]:
break
params["cursor"] = payload["next_cursor"]
System voices follow their configured display order. Personal voices are returned newest first. The catalog can change between pages; start from the first page when beginning a new browsing session or changing filters.
Use a voice
- Query with the
model_idyou intend to use, adding language or search filters as needed. - Read the voice's name, description, and language. If
preview_urlis present, listen using a browser or audio player. - Choose a model from
supported_model_idsand use its synthesis endpoint and request parameters with the returnedvoice_id. The examples and Text to Speech API linked here cover Luna-TTS and Luna-TTS Character. To create or delete personal voices, see Voice Cloning.
Newly enabled voices appear in the catalog; retired voices are excluded. A voice or its permissions can change after querying, so synthesis can fail. Query again and choose an available voice; the service does not silently substitute another voice.
Choose system voices by model
Luna-TTS
Set model_id=luna-tts to find compatible system voices. Add source=personal to query personal voices instead. Personal voices support legacy Luna-TTS and Luna-TTS 1.5 according to their current supported_model_ids; they do not support Character.
Luna-TTS Character
Set model_id=luna-tts-character to find Character system voices. Character does not support personal voices. For scene and expressivity controls, see the Text to Speech API.
cleo, odile, and aude support only Luna-TTS Character; they are unavailable for both legacy Luna-TTS and Luna-TTS 1.5. The stable voice ID for Auden is aude.
Errors
Failed requests return a non-2xx HTTP status and a JSON error body, rather than an empty successful page. Check the HTTP status and error_code; error_message defaults to English, or Chinese when Accept-Language: zh-CN is sent.
{
"error_code": 10001,
"error_message": "Invalid parameters",
"succeed": false,
"data": null
}
| HTTP status | error_code | Condition | What to do |
|---|---|---|---|
400 | 10001 | Invalid parameter, unsupported model, duplicate parameter, or invalid cursor | Correct the parameter; when changing filters, start without a cursor. |
401 | 10003 | Missing or invalid API key | Check the X-API-Key header. |
403 | 10004 | Text to Speech is unavailable to this API key | Check the project's enabled capabilities. |
429 | 10005 or 10014 | Request limit reached | Reduce the request rate and retry later. |
500 | 10000 | Unexpected service error | Retry later; contact support if it continues. |
503 | 20002 | Voice catalog is unavailable, or the selected registered model is not enabled in the current environment | If the model is unavailable, choose a currently available model or contact support. For a temporary service failure, retry later. |
504 | 10006 | Voice query timed out | Retry later. |
See Errors for the common error response contract.