Text to Speech Best Practices

Good synthesis starts with natural sentences, accurate punctuation, and a language setting that matches the voice. Reliable production use also requires a clear retry strategy and secure API key storage.

How much text should I send?

Send one sentence or a natural utterance that should be spoken as a unit. Very short fragments can vary in pitch, speed, and pauses, while overly long requests increase generation time and the cost of a failed request.

• Use punctuation to make intended pauses and endings clear.
• Split text with different purposes, such as titles, body copy, and button labels.
• When continuous context matters, group text into natural sentence units.
• When joining multiple clips, check the silence between clips in the final file.

How do I use expression tags?

Supported tags are [laughter], [sigh], [en], [wa], and [hnn]. Place tags directly in the speaking flow, and avoid using too many in one sentence.

That is a relief. [sigh] I can finally relax.

Unsupported square-bracket tags are treated as request errors. For free-form acting direction in an HTTP request, write a natural-language instruction in the instruct field.

How do I choose a language and voice?

Call /v1/voices before a request and select an available voice_id and language combination for the account.

• Store the stable voice_id instead of the display name.
• Match language_code to the language of the text.
• Split multilingual text into meaningful utterances and assign the appropriate language.
• Keep text, voice, language, and output format fixed when comparing quality.

Which output format should I choose?

Format	Good for	Consideration
mp3_44100_128	Web and app playback, smaller transfers	Lossy compression
wav_24000	Post-processing, editing, and analysis	Larger files

Start with the default MP3 format for general playback and consider WAV for editing pipelines. Using one sample rate and format within a project simplifies post-processing.

How should I design retries?

Do not retry every failure. Retry only errors that may succeed without changing the request, and limit the number of attempts.

Response	Retry	Recommended action
400·422	No	Correct the input and supported range
401·402	No	Resolve authentication or Billing status
404	Usually no	Check the voice_id and access
429	Yes	Follow Retry-After and use exponential backoff with jitter
500·502·503·504	Limited	Retry the same request up to 2–3 times
Timeout	Limited	Check whether a response was received and handle duplicates first

For example, add a small random delay around 1, 2, and 4 seconds. For batch work, limit concurrent requests and process them through a queue within the account RPM. Exact limits can vary by API key or contract.

How should I store an API key?

• Store it in a server environment variable or secret management service.
• Do not call the Kitsch API directly from browsers or mobile clients.
• Log only a prefix and a short preview, never the full key.
• Use separate keys for development, staging, and production.
• Revoke and replace the key immediately if exposure is suspected.

export KITSCH_API_KEY="<API_KEY>"

What should I include in production logs?

Do not log API keys or complete user text. Record the following fields in a structured format:

• Request time and application job ID
• Endpoint, voice_id, language, and output format
• HTTP status code
• x-kitsch-request-id
• Retry count and final result

Include the request ID, time, endpoint, and status code in a support request to help us investigate it faster.