POST/v1/audio/speech

Text to Speech

Synthesize audio from input text.

OpenAI-dialect TTS. Returns a raw audio body (audio/*) — there is never a JSON envelope on success. The provider_metadata side-channel rides only in the X-TF-* response headers.

Warning

Streaming is best-effort / a documented deviation. Two streaming contracts currently work on the data plane but neither is OpenAI speech.audio.delta-compliant:

stream: true — chunked audio/wav (progressive, not SSE-shaped);
stream: true + stream_format: "sse" — text/event-stream of bare base64-PCM data: lines, with no usage event.

Do not build on either as a stable interface yet. Full speech.audio.delta parity is not promised.

Request body

Field	Type	Required	Notes
`model`	string	yes	A TTS alias.
`input`	string	yes	Text to synthesize.
`voice`	string	no	Model-dependent voice id.
`response_format`	string	no	`wav`, `mp3`, `opus`, `aac`, `flac`, `pcm` — provider dependent.
`speed`	number	no	Playback speed.
`stream`	boolean	no	Best-effort (see warning above).
`stream_format`	`audio` \| `sse`	no	With `stream: true`.

Code sample

curl https://api.<domain>/v1/audio/speech \
  -H "Authorization: Bearer $TOKENFACTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "Today is a wonderful day to build something people love!",
    "voice": "alloy",
    "response_format": "mp3"
  }' \
  --output speech.mp3

Response

Raw audio bytes (audio/mpeg, audio/wav, …) — save or stream them directly. Inspect the X-TF-* headers for provider / actual-model / request-id.

Errors

Standard error surface — see Errors. Errors are JSON envelopes even though success is binary.