Text to speech problems

Each entry is keyed by the status and code you see. The request fields and every error are in the endpoint reference. Speech is billed only once audio starts arriving, so none of the refusals below cost anything.

Speech today: Rolling out. The speak tool: Shipping.

404 not found#

Symptom. POST /v1/audio/speech answers 404, while other Flux calls work. On the Flux tools server, the speak tool answers ability_disabled.

Cause. Speech is not switched on for your account yet. Nothing was billed.

Fix. Nothing to change in your code. The status above changes when it is switched on for you. Check the path is exactly https://api.fluxrouter.ai/v1/audio/speech in the meantime. The voice list at GET /v1/audio/voices works either way. An agent that gets ability_disabled should carry on without speech rather than retry.

400 on voice#

Symptom. 400 with "param": "voice", and a message that starts voice for <model> must be one of.

Cause. The voice does not belong to the model you asked for. The common case is a flux-voice-speak voice sent to flux-voice-speak-hd, which takes a smaller set, or a voice from another model's rows in the voice list.

Fix. Use the model and id from the same row of GET /v1/audio/voices. For flux-voice-speak-hd, pick from the voices in Choose a voice. The error message lists the voices the model takes.

400 on response_format#

Symptom. 400 with "param": "response_format".

Cause. The format is not one of mp3, opus, aac, flac, wav or pcm. On the speak tool, only mp3 and wav are offered.

Fix. Pick one of the listed formats. Use opus for small voice notes and pcm for low-latency playback.

400 on speed#

Symptom. 400 with "param": "speed".

Cause. speed is outside 0.25 to 4, or is not a number. A string such as "1.2" is refused.

Fix. Send a number in range, such as 1.2, not a string.

400 on instructions#

Symptom. 400 with "param": "instructions" and a message that they are not supported.

Cause. instructions only work on flux-voice-speak. flux-voice-speak-hd refuses them.

Fix. Switch to flux-voice-speak, or leave instructions out.

400 on input#

Symptom. 400 with "param": "input".

Cause. input is empty, or longer than 4,096 characters.

Fix. Split long text at sentence ends and send each part as its own request. Play or join the parts in order.

The speak tool says the text is too long#

Symptom. The speak tool answers invalid_request: the text is too many characters, split it.

Cause. The tool takes at most 1,000 characters a call, which is less than the API's 4,096 characters. The tool returns audio inside the agent's context as base64, and a long clip would fill it.

Fix. Ask the agent to split the text into parts and speak each one. For long pieces, such as reading out a whole document, call the API from code instead.

The speak tool ran, but there is no audio file#

Symptom. The agent says it spoke the text, and the tool answer shows bytes and cost_usd, but there is no file on disk.

Cause. The speak tool returns the audio as base64 inside its answer. It never writes a file.

Fix. Tell the agent where to save it: "decode the audio and save it as reply.mp3". If you use the tool from your own MCP client, take the audio content block, base64-decode its data, and write the bytes to a file with the extension for its mimeType.

402 premium_locked#

Symptom. 402 with "code": "premium_locked". The speak tool answers premium_locked with an upgrade_url.

Cause. Speech is a paid ability, and the key's account is on the Free plan, or its first payment has not cleared yet. The voice list shows this ahead of time: every row's entitlement is premium_locked.

Fix. Upgrade on the billing page. See Plans.

401 with a key that works for chat#

Symptom. Chat works with the key, but speech answers 401.

Cause. The key has a model list, and the speech model is not on it. The voice list for that key will be missing that model's voices too.

Fix. Add flux-voice-speak (and flux-voice-speak-hd if you use it) to the key's models on your keys page, or use a key with no model restriction.

429 rate_limit_error#

Symptom. 429 with "code": "rate_limit_error".

Cause. One of three things:

• more than 60 requests a minute for your account, counted across speech, transcription and search together;
• more than 36,000 seconds of audio an hour across speech and transcription together, where speech counts an estimate from the length of its text;
• the speech service is busy for a moment.

Fix. Back off and retry. In a voice app that speaks sentence by sentence, send the next sentence only when the last one has started playing. See Rate limits and retries.

502 or 504: no audio#

Symptom. 502 or 504 with "code": "capability_unavailable".

Cause. A 504 means no audio arrived within 30 seconds. A 502 means speech failed, or the service answered with no audio. None of these are billed.

Fix. Retry once. If it keeps happening with one piece of text, try a shorter part or a different voice.

The audio stops partway#

Symptom. A 200, but the clip is cut off before the end of the text.

Cause. Once audio is flowing, a gap of more than 30 seconds between chunks ends the stream. The status was already sent, so there is no error code. The request is billed, because audio was made.

Fix. Retry the text, or split long text into shorter requests so each one finishes quickly.

Still stuck#

See Errors for errors every endpoint shares, or get help from Support.