Generate speech

Turns text into speech. Drop-in for the OpenAI SDK (client.audio.speech.create, or with_streaming_response). Scope inference:audio.

Name a model listed with the speech surface on GET /v1/models; auto and Routers are refused (router_not_supported). Any field not listed here is refused by name (unsupported_parameter), and so is stream_format: "sse" — the answer is always the audio bytes, streamed as the provider makes them. The text must be within the serving Provider Endpoint's limit — stav_max_input_chars on the model object, when it states one — or the request is refused with 413 speech_input_too_long.

Billing is in the unit the endpoint is priced in: per character of input (X-Stav-Input-Characters is the count billed), per second of audio produced (rounded half up, minimum 1) at the per-minute price ÷ 60, or per token on a token-priced model. When several are priced the first applies, in that order. A format whose duration cannot be metered (aac) is refused by name on a per-minute endpoint. The audio is never stored.

A model served by Google (Gemini TTS) answers raw PCM, so Stav serves wav or pcm there and refuses other formats by name (speech_format_not_supported); a model served by Mistral answers pcm, wav, mp3, flac or opus. Neither takes speed or instructions.

Request bodyapplication/json

• modelstringrequired
• inputstringrequired

  The text to speak. Billed per character (Unicode code points) on a per-character endpoint; stav_max_input_chars on the model object states the endpoint's limit when known.

• voicestringrequired

  The voice. Passed through to the provider as given; stav_voices on the model object lists the ones its endpoints name.

• response_formatenum
  mp3opusaacflacwavpcm
  Default: "mp3"
• speednumber
• instructionsstring

  How to speak — tone, pace, accent — on models that take it. Up to 4096 characters.

• stream_formatenum

  audio only. sse is refused by name.

  audio
  Default: "audio"

Notes

POST https://api.stav.ai/v1/audio/speech takes the same JSON request as OpenAI's speech endpoint and streams the audio back as it is made. The OpenAI SDK works as-is.

Request

Any other field is refused by name with 400 unsupported_parameter. Nothing is dropped silently.

What a provider can do differs, and Stav says so by name before anything is charged:

• A model served by Google (Gemini TTS) answers raw PCM, so Stav serves wav or pcm there; mp3 and the rest are refused with 400 speech_format_not_supported. It takes no speed or instructions.
• A model served by Mistral (Voxtral TTS) answers pcm, wav, mp3, flac or opus, and takes no speed or instructions.
• A model priced per minute of audio cannot be asked for aac: its duration cannot be read off the stream, and Stav never bills a guess.

stav_speech_params on the model object (GET /v1/models) says the same thing ahead of time: for each format and for speed and instructions, whether all, some or none of the model's endpoints take it. When only some do, setting it sends the request to those endpoints only; when none do, the request is refused by name before any provider is called.

Response

The audio bytes, Content-Type for the format asked (audio/mpeg, audio/wav, …), chunked as the provider produces them. Two headers matter beside the usual response headers:

How it differs from chat

• Name the model. auto and Routers serve the chat surfaces only.
• Which models qualify. A model is callable here when a Provider Endpoint of it has been proven to answer on /audio/speech — Stav sends each endpoint two words and records whether real audio came back — so a provider that lists a model it does not serve there is never offered.
• The same policy wall. Compute country, zero data retention, no-training, the sovereignty floor and blocked providers apply exactly as on chat; a request the policy cannot place is refused with the same codes.
• Your key needs the inference:audio scope. The same scope as transcriptions — one audio scope, both directions. Without it: 403 insufficient_scope. A key with no scopes has full access.
• Billing is in the unit the provider prices. One line per request: per character of input at the endpoint's per-1M-characters price ÷ 1,000,000 (exact); else per second of audio produced, rounded half up to whole seconds (never less than one), at the per-minute price ÷ 60; else the tokens the provider reports (text in, audio out). When an endpoint carries more than one price the first in that order applies. The model page shows the price in its unit. A failed request is not charged. See Credits and billing.
• The audio is never stored. Not in the request log, not in a capture window, not in the model page's Try drawer. The request log keeps the character count, the seconds of audio produced, the format, the size and the voice; a capture window keeps the input text and the parameters, as it keeps a prompt.

Errors

Full catalogue: Errors.

On the model page

A speech model's page has a Try model button: type text, pick a voice, press Speak, play the audio and download it, and see the receipt — where it ran, the characters billed and what it cost. The Get code panel prints this call as curl (--output), Python (with_streaming_response) and TypeScript.

Response headers

Errors

Every error code, what it means and what to do: Errors.