Best practices

The voice reads exactly the text you send. Most of the quality comes from the text itself.

Write it as it should be spoken

• Spell out what is ambiguous. Numbers, dates, units, currencies and abbreviations can be read more than one way. Write the reading you want: “twenty twenty-six” or “two thousand twenty-six”, “Doctor Lee” rather than “Dr. Lee”, “five kilometres” rather than “5 km”.
• Spell out symbols and code. URLs, email addresses, file names and code are hard to read aloud. Rewrite them for the ear, or leave them out.
• Remove what is not meant to be heard: Markdown, HTML, emoji, footnote marks, table layouts.

Use punctuation for pauses

There is no markup for pauses: punctuation is how the text paces the voice. Commas and full stops make the voice pause and breathe, and a sentence that runs on is read in one breath. Break long sentences into shorter ones for a calmer read. Aderra also splits long text at sentence ends, so complete, well-punctuated sentences join best.

Set the language for short or mixed text

Detection works best on a few sentences. For a word, a name or a short phrase, set language. One request is spoken in one language, so send text in different languages as separate requests.

Pick the voice by what it is for

Filter the voices by use_case first (narration, conversational, educational, entertainment, social_media), then by style, and listen to a few. Keep one voice per speaker or per product, so your users always hear the same one. If you let users choose, build the picker from GET /v1/audio/voices, which gives every voice a preview_url to play.

Stream for a fast start

Every response is streamed: the first audio arrives in about half a second. Start playback as the bytes arrive instead of waiting for the whole file; pcm is the easiest to play as it comes. See Streaming.

Don’t pay twice for the same audio

• Play the samples, not your own requests, while choosing a voice. Each voice’s preview_url is free.
• Store audio you will play again, such as fixed prompts, menus and greetings, instead of generating it on every play. Each request is billed, even for text you have sent before.