Decision guide
REST (sync)
You have short, complete text and want one finished WAV file. Simplest to integrate.
HTTP streaming
You have one complete utterance but want playback to start as early as possible.
WebSocket
Text arrives incrementally (e.g. from an LLM), or you need a long, low-latency, interactive session.
Comparison
REST POST /v1/tts | HTTP stream POST /v1/tts/stream | WebSocket /v1/tts/ws | |
|---|---|---|---|
| Connection | One request/response | One request, streamed response | Persistent, bidirectional |
| Time to first byte | After full synthesis | Low (as generated) | Low (per sentence) |
| Text delivery | All at once | All at once | Incremental, across messages |
| Output | WAV file | Raw PCM (audio/L16) | PCM or streaming-WAV frames per sentence |
| Max input | 500 characters | 500 characters | Unbounded across the session |
| Billing | Up front, per request | Up front, refunded on failure | Per sentence, as generated |
| Auth | API key (header) | API key (header) | API key (header or ?api_key=) |
| Best for | Simplicity, batch | Single low-latency utterance | Real-time and long-form |
Rules of thumb
- Start with REST. If you’re generating short clips and don’t need sub-second first audio,
POST /v1/ttsis the least code. - Reach for HTTP streaming when you already have the full sentence but want the user to hear audio sooner, for example reading a chat reply aloud.
- Use the WebSocket when text is produced token-by-token (streaming from an LLM), when you’re driving a voice agent, or when a single utterance would exceed 500 characters. You send
input.textmessages as text becomes available and receive audio per sentence. See WebSocket streaming.
Concurrency limits are enforced per plan on the synchronous
POST /v1/tts endpoint. If you need many simultaneous generations, see Rate limits & concurrency before choosing a transport.