Skip to main content

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-Key request 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​

ParameterTypeRequiredDescription
sourcestringNosystem (default) or personal. Each request lists one source. all is not supported.
model_idstringNoReturn 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.
languagestringNoFilter 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.
searchstringNoMatch a substring in voice names and descriptions. Maximum 100 characters after trimming surrounding whitespace.
page_sizeintegerNoItems per page: 1–100, default 20.
cursorstringNoThe 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:

FieldTypeDescription
voicesarrayVoices in the current page; [] when no voices match.
has_morebooleanWhether another page is available.
next_cursorstring / nullCursor for the next page; null when there is no next page.

System and personal voices use the same structure:

FieldTypeDescription
voice_idstringPublic voice ID for synthesis requests with a compatible model.
namestringVoice name.
descriptionstring / nullVoice introduction.
languagestring / nullLabeled primary language: zh, en, ja, or ko in the current system catalog; null if not labeled.
genderstring / nullStored gender metadata, such as male or female; null when not labeled.
agestring / nullStored age-group metadata, such as young, adult, or elderly; null when not labeled.
descriptivestring / nullStored free-text voice style, such as Sweet and gentle; null when not labeled. This is not an enum or a synthesis control.
preview_urlstring / nullAudio preview URL; null if no preview is available.
preview_url_expires_atinteger / nullExpiration as a Unix timestamp in seconds; null for a permanent URL or no URL.
sourcestringsystem or personal.
supported_model_idsstring[]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​

  1. Query with the model_id you intend to use, adding language or search filters as needed.
  2. Read the voice's name, description, and language. If preview_url is present, listen using a browser or audio player.
  3. Choose a model from supported_model_ids and use its synthesis endpoint and request parameters with the returned voice_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 statuserror_codeConditionWhat to do
40010001Invalid parameter, unsupported model, duplicate parameter, or invalid cursorCorrect the parameter; when changing filters, start without a cursor.
40110003Missing or invalid API keyCheck the X-API-Key header.
40310004Text to Speech is unavailable to this API keyCheck the project's enabled capabilities.
42910005 or 10014Request limit reachedReduce the request rate and retry later.
50010000Unexpected service errorRetry later; contact support if it continues.
50320002Voice catalog is unavailable, or the selected registered model is not enabled in the current environmentIf the model is unavailable, choose a currently available model or contact support. For a temporary service failure, retry later.
50410006Voice query timed outRetry later.

See Errors for the common error response contract.