Skip to main content
POST
Text-to-speech
Response is the audio binary (audio/mpeg / audio/wav depending on response_format).

Sample output

Generated with gemini-2.5-flash-tts, voice Kore. Download tts.wav.

Parameters

  • voice — model-dependent (alloy, echo, onyx, nova, shimmer, etc.)
  • instructions — a description of the voice, for models that design one from words
  • response_formatmp3, wav, opus, flac, pcm
  • speed — 0.25–4.0

Designing a voice

Some models do not pick a voice from a list — they build one from a description. Those carry accepts_voice_instructions in allowed_params on their GET /v1/models entry, and the ones that cannot synthesise without a description carry requires_voice_instructions (they answer 400 without one, before anything is billed). Send the words in input and the voice in instructions:
Every other model ignores instructions rather than failing on it — the description is dropped instead of being pushed into a field that means something else.

Authorizations

Authorization
string
header
required

API key in format: Bearer inf_***

Body

application/json
model
string
required

Model ID to use for TTS

input
string
required

Text to synthesize into speech. Maximum 4096 characters.

Maximum string length: 4096
voice
string

Voice to use for synthesis. Accepted values are model-specific — see allowed_params on the model's GET /v1/models entry.

OPTIONAL. Omitting it is a supported call, not a degraded one, but WHICH voice you get is the routed provider's answer rather than one of ours: the OpenAI and Google paths substitute alloy (Google then maps that name onto one of its own voices), the xAI path substitutes eve, and the Alibaba, FAL and Replicate paths send no voice at all so the model applies its own default. Pass one when the voice matters.

Sending one is not a guarantee either. On FAL and Replicate the value is forwarded only when the chosen model's own input schema declares a voice field that takes a NAME, and only when the value is a member of that field's enum where it has one — anything else is dropped silently so the model falls back to its default, rather than failing the request on a name that model has never heard of.

instructions
string

A DESCRIPTION of the voice to synthesize — "high-pitched, cute energetic anime girl voice, cheerful, youthful". Distinct from voice, which names one the model already has: this one designs a voice from words.

OPTIONAL for most models and IGNORED by them — it is forwarded only to models whose own input schema carries a field for it, which you can read as accepts_voice_instructions in allowed_params on the model's GET /v1/models entry. Sending it to a model without one is not an error; the description is simply dropped rather than pushed into a field that means something else.

REQUIRED by the models that synthesize their voice FROM it (requires_voice_instructions in the same allowed_params). Those answer 400 without it, before anything is billed.

Maximum string length: 4096
response_format
enum<string>
default:mp3

Container for the returned audio. Sets the response Content-Type.

Available options:
mp3,
opus,
aac,
flac,
wav,
pcm
speed
number
default:1

Speed of the generated audio (0.25 to 4.0)

Required range: 0.25 <= x <= 4

Response

Binary audio stream. Content-Type reflects the requested response_format: audio/mpeg (mp3, default), audio/wav, audio/ogg (opus), audio/flac, audio/aac, or audio/pcm. Credits deducted are returned in the x-credits-used response header.

The response is of type file.