Skip to main content

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​

TaskEndpoint
Generate three candidatesPOST /api/tts/v1/voice-design/api/generate
Save one candidatePOST /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​

HeaderRequiredDescription
X-API-KeyYesProject API key.
Content-TypeYesapplication/json.
Accept-LanguageNoControls 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.

Generation requests are not idempotent

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 caseExample description
Chinese picture-book narration中文绘本旁白,年轻女性,嗓音清亮柔和,语速中等,语气亲切。
English product narrationEnglish 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

FieldTypeRequiredDescription
voiceDescriptionstringYesVoice description. After trimming: 1–200 Unicode code points. Emoji are not supported.
previewTextstringNoAudition 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 fieldTypeDescription
data.generationIdstringGeneration ID for this round.
data.referenceTextstringActual text used for all three candidates.
data.candidatesarrayThree candidates.
data.candidates[].candidateNointegerCandidate number: 1, 2, or 3.
data.candidates[].languagestringCandidate language: zh, en, ja, or ko.
data.candidates[].durationMsintegerCandidate duration in milliseconds.
data.candidates[].previewUrlstringTemporary signed URL for the candidate WAV audio.
data.expiresAtintegerUnix timestamp in seconds, three hours after generation completes.

Save a candidate​

POST /api/tts/v1/voice-design/api/save

FieldTypeRequiredDescription
generationIdstringYesGeneration ID returned above.
candidateNointegerYes1, 2, or 3.
namestringYesAfter trimming: 1–30 Unicode code points. Emoji are not supported. Unique within the organization, ignoring case.
languagestringYesDisplay category: zh, en, ja, or ko. Does not affect the audio.
descriptionstringYesSaved voice description. After trimming: 1–200 Unicode code points. Emoji are not supported.
avatarKeystringNoObject 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 fieldTypeDescription
data.savedVoiceIdstringFormal voice ID for the TTS voice_id.
data.savedOrganizationIdstringOrganization ID as a decimal string.
data.deletedbooleanWhether this voice has been deleted.
data.itemobject or nullSaved voice details; null when deleted.
data.item.voiceIdstringSame formal voice ID.
data.item.name, language, descriptionstringSaved display metadata.
data.item.avatarUrlstringTemporary avatar URL, or an empty string when unset.
data.item.previewUrlstringTemporary reference-audio URL. URL expiration does not expire the voice ID.
data.item.sourceTypeinteger2 for a designed voice.

Retries and idempotency​

RequestRetry behavior
GenerateNot idempotent. Resubmitting creates a new round that is billed again on success.
SaveIdempotent. 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_codeMeaningWhat to do
10001Invalid input, or missing X-API-Key / Content-Type: application/json headerCheck headers, required fields, limits, and language values.
12934Emoji are not supported in the voice name, description, or audition textRemove emoji from the input and retry.
10024Saved display name already existsChoose another name and retry the same save before expiry.
10003Invalid API keyCheck the key and API environment.
10004Missing project permission or no access to the round or assetCheck that the project has Voice Cloning access. For saving, use a key from the same organization and owner as generation.
12931Paid subscription requiredActivate a paid subscription before generating or saving a new voice.
12903No organization voice slot is available for saving a new voiceFree a slot or upgrade, then retry saving before expiry. If candidates have expired, generate again.
20003Insufficient account balanceAdd funds before submitting generation again.
10002Round or resource does not existCheck the generation ID and API environment.
12932Candidates expiredGenerate a new round, billed under normal rules.
12933Generation outcome is not yet confirmedDo not automatically regenerate. Keep the request time and the generation ID (if available) and contact support.
20016No usable speech segment for savingTry another candidate while valid, or generate again.
20017Audio contains a pause longer than 3 secondsTry another candidate while valid.
12913Voice and model are incompatibleSelect a voice supported by the model.
12914Reference speech language could not be detectedTry another candidate before expiry.
12915Reference speech language is unsupportedUse Chinese, English, Japanese, or Korean candidates.
10005Request-rate or generation-concurrency limit reachedWait before retrying; generation requests are not idempotent.
10006Request timeoutRetry the same save while valid. Do not automatically resend generation when its outcome is unknown.
20002Model or dependency service temporarily unavailableRetry 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.