Flux RouterDocumentation

Speech to text problems

Fixes for Flux transcription errors, keyed by status and code: file too large, unsupported format, 401 and 402 refusals, 429 limits, streaming and subtitle formats, and the transcribe tool's audio_url.

Each entry is keyed by the status and code you see. The request fields and every error are in the endpoint reference. Nothing on this page is billed: a refused transcription costs nothing.

413 file_too_large

Symptom. 413 with "code": "file_too_large" and "param": "file".

Cause. The file is over 8 MB. The check runs while the upload streams in, so a large file is refused before it has finished uploading.

Fix. Make the file smaller or split it:

  • Re-encode speech at a low bitrate. Speech stays clear in Opus at a low bitrate, which fits far more audio into the limit than wav:
    bash
    ffmpeg -i meeting.wav -ac 1 -c:a libopus -b:a 24k meeting.ogg
  • Split a long recording into parts, transcribe each, and join the text:
    bash
    ffmpeg -i meeting.m4a -f segment -segment_time 600 -c copy part-%03d.m4a

400 unsupported_file_format

Symptom. 400 with "code": "unsupported_file_format".

Cause. Flux reads the format from the file's first bytes, not from its name. A file called .mp3 that is really a video, a text file or a broken download is refused. So is a format outside wav, mp3, mp4/m4a, ogg (including Opus), webm and flac.

Fix. Check what the file really is (file meeting.mp3 on macOS or Linux), then convert it:

bash
ffmpeg -i input.anything -ac 1 -c:a libopus output.ogg

401 with a key that works for chat

Symptom. Chat requests work with the key, but transcription answers 401.

Cause. The key has a model list, and flux-voice is not on it. A key only reaches the model ids on its list, and the ability ids count.

Fix. Add flux-voice (and flux-voice-accurate or flux-voice-fast if you pin them) to the key's models on your keys page, or use a key with no model restriction. GET /v1/models with the key shows what it can reach.

402 premium_locked

Symptom. 402 with "code": "premium_locked".

Cause. Transcription is a paid ability, and the key's account is on the Free plan, or its first payment has not cleared yet.

Fix. Upgrade on the billing page. If you have just paid, wait for the payment to clear and retry. See Plans. In an app, show an upgrade prompt for this code instead of a generic error.

402 with another code

Symptom. 402 with credit_unresolved, or another code about credit or a cap.

Cause. credit_unresolved means your balance could not be checked at that moment. Other codes mean a spend cap or a prepaid balance stopped the request.

Fix. Retry credit_unresolved after a short wait. For a cap, see Spend caps.

429 rate_limit_error

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

Cause. One of two per-account limits:

  • more than 60 requests a minute, counted across transcription, speech and search together; or
  • more than 36,000 seconds of audio an hour, counted across transcription and speech together.

A batch job that fires many files at once, or a voice app that also speaks a lot, can hit the audio budget.

Fix. Back off and retry, and cap how many files you send at once. See Rate limits and retries.

400 on stream

Symptom. 400 with "param": "stream".

Cause. You sent stream=true. Transcription returns the whole transcript in one response; there is no streaming mode.

Fix. Leave stream out. For live captions, send short clips as they are recorded and transcribe each one.

400 on srt or vtt

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

Cause. Only json, verbose_json and text are offered. Subtitle formats are not.

Fix. Ask for verbose_json and build subtitles from segments, which carry start, end and text for each line.

504 or 502 capability_unavailable

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

Cause. A 504 means the transcription took longer than 60 seconds. A 502 means it failed upstream.

Fix. Retry once. If a long file keeps timing out, split it into shorter parts.

404 not found

Symptom. 404 from /v1/audio/transcriptions.

Cause. Usually a wrong path: check the URL is exactly https://api.fluxrouter.ai/v1/audio/transcriptions. Otherwise transcription is switched off on the service.

Fix. Fix the path. If it is right, check Status or get help from Support.

The wrong model served

Symptom. You pinned a model, but x-flux-routed-model says flux-voice.

Cause. An unknown model id is not refused: it is treated as flux-voice. A typo such as flux-voice-acurate gets the default.

Fix. Use one of flux-voice, flux-voice-accurate or flux-voice-fast exactly.

The transcribe tool refuses audio_url

Symptom. The transcribe tool on the Flux tools server answers invalid_request with a message about audio_url.

Cause. The tool downloads the audio itself, so the address has to be one it can safely reach:

  • It must be https://. Plain http:// is refused.
  • It must be public. Addresses on your own machine, a private network or a cloud metadata service are refused.
  • It may redirect at most 3 times, and must answer 200 with a body.
  • The file must be under 8 MB; over it the tool answers too_large.

Fix. Host the file somewhere public over https, such as a pre-signed storage link. For a file on your own machine, send it as audio_base64 instead. Pass exactly one of audio_url or audio_base64, never both.

Still stuck

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