Voice Design API
Design a voice from a text description without uploading a reference recording. Audition three candidates, save the best match, then use the saved voice ID as voice_id in the Text to Speech API.
Endpoints at a glance
| Task | Endpoint |
|---|---|
| Generate three candidates | POST /api/tts/v1/voice-design/api/generate |
| Save one candidate | POST /api/tts/v1/voice-design/api/save |
| Generate speech with the saved voice (Text to Speech API) | POST /v1/text-to-speech |
Before you start
- Use a project API key with Voice Cloning access to generate and save designed voices. Using a saved voice for speech synthesis requires Text to Speech access. Enable both capabilities to run all three steps with one key. Authenticate with
X-API-Key. See Get your API key. - Generating candidates and saving a new voice require an active paid subscription.
- Saving a new voice requires an available organization voice slot and occupies one slot shared with cloned voices on success. Generation does not check or reserve slots.
Request headers
| Header | Required | Description |
|---|---|---|
X-API-Key | Yes | Project API key. |
Content-Type | Yes | application/json. |
Accept-Language | No | Controls only the language of error_message: en (default) or zh-CN. |
Charging
Each generation round (three candidates) counts as one generation. Available organization Voice Design free uses are consumed first; after they are exhausted, each generation costs $0.01, charged to the account balance. Once free uses are exhausted, the account balance must cover the full cost of one generation. See Pricing.
Saving has no additional charge. A successful generation is billable if you choose not to save, the candidates expire, or saving fails.
View your current organization’s remaining free uses in the Console; only quotas with remaining uses appear in the list.
The examples below use cURL.
export VUILABS_API_BASE_URL="https://api.vuilabs.ai"
export VUILABS_API_KEY="your-api-key"
1. Generate three candidates
Generation returns its result synchronously. We recommend a total client request timeout of 60 seconds or longer; allow more time for longer text or a busy service.
Each generate request starts a new round. A successful round consumes another free use or incurs another charge. Do not automatically resend after a timeout, connection loss, or lost response: the service may already have completed generation. If the outcome is unclear, keep the request time and the generation ID (if available) and contact support.
curl --request POST --max-time 60 \
--url "$VUILABS_API_BASE_URL/api/tts/v1/voice-design/api/generate" \
--header "X-API-Key: $VUILABS_API_KEY" \
--header "Content-Type: application/json" \
--header "Accept-Language: en" \
--data '{
"voiceDescription": "Read in English. A warm adult female narrator with a clear, calm and welcoming voice."
}'
previewText is optional. If omitted, the service generates sample text from the description.
Successful response:
{
"error_code": 0,
"error_message": "",
"succeed": true,
"data": {
"generationId": "YOUR_GENERATION_ID",
"referenceText": "Welcome. Take a moment to settle in and make yourself at home.",
"candidates": [
{"candidateNo": 1, "language": "en", "durationMs": 7080, "previewUrl": "YOUR_SIGNED_PREVIEW_URL_1"},
{"candidateNo": 2, "language": "en", "durationMs": 7080, "previewUrl": "YOUR_SIGNED_PREVIEW_URL_2"},
{"candidateNo": 3, "language": "en", "durationMs": 7080, "previewUrl": "YOUR_SIGNED_PREVIEW_URL_3"}
],
"expiresAt": 1793013949
}
}
After generation succeeds, use data.generationId to save a voice. The three audio URLs are returned in data.candidates[].previewUrl.
2. Audition and save one candidate
Generated candidates and their audition links are valid for 3 hours, until expiresAt. Audition them and save the voice you want as soon as possible. After expiration, create a new round under normal charging rules.
Each candidate’s previewUrl is a WAV audio URL that can be played or downloaded directly, without transcoding. Do not forward your API key to the audio URL.
Download example:
curl --fail "YOUR_PREVIEW_URL" --output design-candidate.wav
Choose a candidate and pass the returned data.generationId and its candidateNo in the save request. This example saves candidate 2. When saving a new voice for the first time, the service checks candidate validity, subscription, available slots, and organization membership.
curl --request POST \
--url "$VUILABS_API_BASE_URL/api/tts/v1/voice-design/api/save" \
--header "X-API-Key: $VUILABS_API_KEY" \
--header "Content-Type: application/json" \
--header "Accept-Language: en" \
--data '{
"generationId": "YOUR_GENERATION_ID",
"candidateNo": 2,
"name": "Welcome narrator",
"language": "en",
"description": "A calm narrator for welcome messages."
}'
Candidates of 15 seconds or less are saved with their complete audio and original spoken text. For candidates longer than 15 seconds, a usable speech segment may be extracted, so the saved reference preview can differ from the original candidate. A definite audio-processing rejection creates no voice and occupies no slot.
3. Generate new speech with the saved voice
After saving succeeds, use the returned data.savedVoiceId as the TTS voice_id to synthesize new text:
curl --fail-with-body --request POST \
--url "$VUILABS_API_BASE_URL/v1/text-to-speech" \
--header "X-API-Key: $VUILABS_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model_id": "luna-tts-1.5",
"voice_id": "YOUR_SAVED_VOICE_ID",
"text": "Hello again. This sentence checks the saved voice.",
"language": "en-US",
"audio_format": "wav"
}' \
--dump-header design-speech.headers \
--output design-speech.response || { cat design-speech.response >&2; exit 1; }
if ! grep -Eiq '^content-type:[[:space:]]*audio/wav([[:space:];]|$)' design-speech.headers || [ ! -s design-speech.response ]; then
cat design-speech.response >&2
echo 'Expected a non-empty audio/wav response' >&2
exit 1
fi
mv design-speech.response design-speech.wav
Successful synthesis returns WAV bytes. Check the HTTP status and audio Content-Type. This workflow uses luna-tts-1.5; later synthesis is billed under TTS rules. See Text to Speech for output and error handling.
To find saved designed voices by name or view their descriptions, call the List Voices API with source=personal. To delete a voice, see custom-voice management.
Write an effective voice description
Use voiceDescription to specify the use case, language, and most important voice qualities, such as perceived age, pitch, texture, pace, and emotion. Focus on two to four characteristics and avoid contradictory instructions.
Avoid: “Speak very quickly and very slowly at the same time.” Use: “A moderate pace with a calm delivery.”
| Use case | Example description |
|---|---|
| Chinese picture-book narration | 中文绘本旁白,年轻女性,嗓音清亮柔和,语速中等,语气亲切。 |
| English product narration | English narration. An adult male voice with a warm, low tone, a steady pace, and a calm delivery. |
| Japanese storytelling | 日本語の朗読。落ち着いた成人女性の声で、自然な速さと柔らかい語り口。 |
Start with a concise description and change one characteristic at a time to compare results. To choose the words spoken during audition, provide them in previewText.
Request and response fields
Generate candidates
POST /api/tts/v1/voice-design/api/generate
| Field | Type | Required | Description |
|---|---|---|---|
voiceDescription | string | Yes | Voice description. After trimming: 1–200 Unicode code points. Emoji are not supported. |
previewText | string | No | Audition text. After trimming: at most 300 weighted characters. Emoji are not supported. Omit it to generate sample text automatically. |
All other documented text-length limits count each Unicode code point as 1.
previewText weighted counting: Han characters, Japanese hiragana/katakana, Korean Hangul, and long-vowel marks (ー and ー) count as 2. Every other Unicode code point counts as 1, including internal spaces, punctuation, and line breaks. For example, Hello! counts as 6 and 你好 as 4. These rules differ from TTS billing character counting.
| Response field | Type | Description |
|---|---|---|
data.generationId | string | Generation ID for this round. |
data.referenceText | string | Actual text used for all three candidates. |
data.candidates | array | Three candidates. |
data.candidates[].candidateNo | integer | Candidate number: 1, 2, or 3. |
data.candidates[].language | string | Candidate language: zh, en, ja, or ko. |
data.candidates[].durationMs | integer | Candidate duration in milliseconds. |
data.candidates[].previewUrl | string | Temporary signed URL for the candidate WAV audio. |
data.expiresAt | integer | Unix timestamp in seconds, three hours after generation completes. |
Save a candidate
POST /api/tts/v1/voice-design/api/save
| Field | Type | Required | Description |
|---|---|---|---|
generationId | string | Yes | Generation ID returned above. |
candidateNo | integer | Yes | 1, 2, or 3. |
name | string | Yes | After trimming: 1–30 Unicode code points. Emoji are not supported. Unique within the organization, ignoring case. |
language | string | Yes | Display category: zh, en, ja, or ko. Does not affect the audio. |
description | string | Yes | Saved voice description. After trimming: 1–200 Unicode code points. Emoji are not supported. |
avatarKey | string | No | Object key from the Console voice-avatar upload. Supports PNG/JPG/WEBP/SVG up to 5 MiB. Audio Upload API object keys cannot be used as avatars. |
The service assigns the formal voice ID.
| Response field | Type | Description |
|---|---|---|
data.savedVoiceId | string | Formal voice ID for the TTS voice_id. |
data.savedOrganizationId | string | Organization ID as a decimal string. |
data.deleted | boolean | Whether this voice has been deleted. |
data.item | object or null | Saved voice details; null when deleted. |
data.item.voiceId | string | Same formal voice ID. |
data.item.name, language, description | string | Saved display metadata. |
data.item.avatarUrl | string | Temporary avatar URL, or an empty string when unset. |
data.item.previewUrl | string | Temporary reference-audio URL. URL expiration does not expire the voice ID. |
data.item.sourceType | integer | 2 for a designed voice. |
Retries and idempotency
| Request | Retry behavior |
|---|---|
| Generate | Not idempotent. Resubmitting creates a new round that is billed again on success. |
| Save | Idempotent. If the response is lost or the outcome is unknown, repeat the save for the same round to retrieve its result without creating another voice. If the round was already saved and you still have access, you can retrieve the saved result even after the subscription expires. |
A round saves at most one voice. Repeating a successful save returns the original result, even with another candidateNo, and does not update metadata. You can retrieve an already saved result after candidate expiration.
If the voice was deleted, repeating the save returns the original savedVoiceId, deleted: true, and item: null. The same round cannot recreate it.
Request limits
By default, generation and saving each allow 10 requests per 60 seconds, counted separately. Within an organization, Console operations and API keys owned by the same user share the request-rate limit for each operation.
Each user can run at most 2 generation rounds at the same time. This concurrency allowance is shared across the user's organizations, Console operations, and API keys; different users have independent allowances. Saving a voice does not consume generation concurrency. Reaching a request-rate or concurrency limit returns 10005; requests rejected by either limit do not generate candidates or incur a charge. See Request Limits for limit errors and capacity requests.
Errors and recovery
Both Voice Design endpoints return the standard JSON envelope. Business rejections can return HTTP 200 with succeed: false. Check succeed and error_code, and handle transport errors and non-2xx responses. Error messages default to English when Accept-Language is omitted. Send Accept-Language: en for English or Accept-Language: zh-CN for Chinese. This header controls only the language of error_message.
Voice Design error responses have data: null. Identify insufficient slots when saving a new voice using error_code: 12903.
Example slot-limit response with Accept-Language omitted or set to en:
{
"error_code": 12903,
"error_message": "No voice slots available. Please upgrade or free a slot.",
"succeed": false,
"data": null
}
Voice Design errors and recovery options are listed below.
error_code | Meaning | What to do |
|---|---|---|
10001 | Invalid input, or missing X-API-Key / Content-Type: application/json header | Check headers, required fields, limits, and language values. |
12934 | Emoji are not supported in the voice name, description, or audition text | Remove emoji from the input and retry. |
10024 | Saved display name already exists | Choose another name and retry the same save before expiry. |
10003 | Invalid API key | Check the key and API environment. |
10004 | Missing project permission or no access to the round or asset | Check that the project has Voice Cloning access. For saving, use a key from the same organization and owner as generation. |
12931 | Paid subscription required | Activate a paid subscription before generating or saving a new voice. |
12903 | No organization voice slot is available for saving a new voice | Free a slot or upgrade, then retry saving before expiry. If candidates have expired, generate again. |
20003 | Insufficient account balance | Add funds before submitting generation again. |
10002 | Round or resource does not exist | Check the generation ID and API environment. |
12932 | Candidates expired | Generate a new round, billed under normal rules. |
12933 | Generation outcome is not yet confirmed | Do not automatically regenerate. Keep the request time and the generation ID (if available) and contact support. |
20016 | No usable speech segment for saving | Try another candidate while valid, or generate again. |
20017 | Audio contains a pause longer than 3 seconds | Try another candidate while valid. |
12913 | Voice and model are incompatible | Select a voice supported by the model. |
12914 | Reference speech language could not be detected | Try another candidate before expiry. |
12915 | Reference speech language is unsupported | Use Chinese, English, Japanese, or Korean candidates. |
10005 | Request-rate or generation-concurrency limit reached | Wait before retrying; generation requests are not idempotent. |
10006 | Request timeout | Retry the same save while valid. Do not automatically resend generation when its outcome is unknown. |
20002 | Model or dependency service temporarily unavailable | Retry the same save while valid. Do not automatically resend generation when its outcome is unknown. |
See Errors for other API errors. When contacting support, provide the endpoint, request time with time zone, generation ID if available, and error code. Do not send API keys or signed preview URLs.