Text to Speech troubleshooting

This page lists the errors that speech requests return, then the usual causes of speech that sounds wrong, flat, cut short, or slow to start. Each fix links to the page that covers the setting to change.

Tip

Many problems with generated speech have a setting that fixes them, such as phonemes for a name or a tag for an emotion. Check the symptom tables before you change voices or contact support.

Errors

A speech request that fails returns an HTTP error with a JSON body, for example:

{
  "object": "error",
  "message": "Voice '01a0f6db-3084-701a-b61c-b6b755947e7f' not found.",
  "type": "invalid_voice",
  "param": null,
  "code": "1902",
  "raw_status_code": 404
}

{
  "object": "error",
  "message": "Voice '01a0f6db-3084-701a-b61c-b6b755947e7f' not found.",
  "type": "invalid_voice",
  "param": null,
  "code": "1902",
  "raw_status_code": 404
}

A 422 validation error carries its explanation in message.detail, a list where each item has a msg field.

Speech request errors

These errors come from a field of the speech request. Fix the field and send the request again:

Error	Cause	Fix
404 `Voice 'x' not found.`	The `voice_id` doesn't match a preset voice or a voice saved in your workspace.	List the voices and copy the exact slug or ID. See Use a voice ID.
400 `Either ref_audio or voice must be provided.`	The request has no voice.	Add `voice_id`. See Request fields.
422 `Extra inputs are not permitted`	A misspelled or unknown field name, such as `instructions` instead of `instruction`.	Check the field name. See Request fields.
	The value is out of range.	Use a value from `1.0` to `5.0`. See Expressiveness.
422, the message lists the accepted phonemes	A phoneme in `phoneme_hints` isn't in the accepted list.	Replace it with a phoneme from the list. See Accepted phonemes.
422 with type `string_type`	`instruction` isn't a string.	Send the instruction as text. See Style instructions.
Style instructions are not available at launch.	The instruction is over the length limit. It isn't shortened for you.	Shorten the instruction. See Style instructions.
Style instructions are not available at launch.	The model doesn't support style instructions.	Use a model that supports them. See Style instructions.
400 `Failed to load audio file. Verify that the given file is valid mp3 or wav.`	The `ref_audio` recording is a URL, or not an MP3 or WAV file.	Send the recording itself, base64-encoded, as MP3 or WAV. See Prepare a reference clip.

Mispronounced words

When the voice says a word wrong, the fix is in the request, not in the voice:

Symptom	Cause	Fix
A name, a brand, or an acronym is mispronounced	The voice guesses the reading from the spelling.	Give the word its phonemes in `phoneme_hints`. See Define a pronunciation and Custom vocabulary.

Emotion and delivery

When the words are right but the delivery isn't, find the symptom in this table:

Symptom	Cause	Fix
The speech sounds flat, or the emotion doesn't come through		Add an emotion tag before the text, then raise `expressiveness` if the emotion is still faint. See Tag an emotion and Expressiveness.
The speech sounds forced or exaggerated		Lower `expressiveness`. See Expressiveness.
A tag has no audible effect	The tag value isn't in the supported list. The API doesn't reject it, and the tag isn't spoken.	Use a listed value. See Supported emotions, Pace tags, and Unsupported values.
The audio stops after the first part of a sentence that has an emotion tag	A tag before a long sentence can end the audio early, at a comma.	Keep tagged sentences short, or split a long sentence in two. See Tag an emotion.

Slow first audio

When the speech is right but the listener waits too long before hearing it, the fix depends on what they wait for:

Symptom	Cause	Fix
The listener waits for the whole audio before anything plays	A speech request returns the audio once all of it is generated.	Stream the response, and play each chunk as it arrives. The total time stays the same. See Stream a request.
Nothing plays until the stream ends, even with streaming on	Your client reads the full response before handing it on.	Read the events as they arrive, and pass each chunk to the player at once. See Common issues.
The time to first audio varies from one request to the next		Measure it over many requests, from where your application runs. See Time to first audio and Latency.

Cloned voices

A cloned voice depends on its reference clip. When a clone doesn't sound the way you expect, check the clip first:

Symptom	Cause	Fix
The cloned voice carries background noise, or the mood of the recording	A clone copies more than the voice: the recording conditions and the delivery come with it.	Record a clean clip of one speaker, in the style you want to hear. See Prepare a reference clip.
The cloned voice sounds different from one request to the next	Each request clones from the clip it receives, so a different clip gives a different voice.	Save the voice once, and pass its ID in every request. See Save a cloned voice.

Going further

Speech generation

Emotion and pace tags