> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gradium.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Text-to-Speech Overview

> When to use the WebSocket API vs the REST endpoint, and how the pieces fit together

Gradium exposes Text-to-Speech over two transports. They share the same
models and voices; you pick the transport that matches your input shape
and latency needs.

## WebSocket vs REST

| If your text is...                                           | Use                                              | Why                                                                                                      |
| ------------------------------------------------------------ | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| Streamed in token-by-token (LLM output, agent loop, live UI) | [WebSocket](/guides/text-to-speech)              | Lowest first-byte latency. Send text as it arrives, audio chunks come back as soon as they're generated. |
| A finished block in hand (article, scripted line, batch job) | [REST](/guides/text-to-speech-rest)              | One HTTP call, no connection to manage. Save the response body to a file and you're done.                |
| Many concurrent synthesis requests                           | [WebSocket + Multiplexing](/guides/multiplexing) | Run several requests over a single socket, matched by `client_req_id`.                                   |
| Browser or mobile app audio                                  | [Browser WebSockets](/guides/browser-websockets) | Use short-lived tokens instead of exposing an API key.                                                   |

If you're unsure, start with REST. It's a single POST and the response
body is the audio. Move to WebSocket once latency or streaming-input
concerns make REST the bottleneck.

## What both transports share

* **Voices**: any `voice_id` from the [Voice Library](/guides/voices/overview) works on both.
* **Output formats**: PCM, WAV, Opus, and the telephony codecs (`ulaw_8000`, `alaw_8000`).
* **Voice settings**: `temp`, `cfg_coef`, `padding_bonus`, `rewrite_rules`, `pronunciation_id`. See [Voice Settings](/guides/voice-settings).
* **Pronunciation dictionaries**: pass `pronunciation_id` in either transport.

## What's transport-specific

* **`<flush>` and `<break time="..." />` tags** are processed by the model in both transports, but only meaningfully useful when you're streaming text in over the WebSocket.
* **WebSocket-only**: setup-message stream controls (`send_setup_on_start`, `wait_for_ready_on_start`), multiplexing, in-stream `flush`, browser tokens. See [WebSocket Lifecycle](/guides/websocket-lifecycle).
* **REST-only**: `only_audio` toggle to choose between raw audio bytes and an NDJSON stream that mirrors the WebSocket protocol.

## Next steps

<CardGroup cols={2}>
  <Card title="Use the WebSocket API" icon="waveform-lines" href="/guides/text-to-speech">
    SDK and direct WebSocket usage, streaming output, flush, timestamps.
  </Card>

  <Card title="Use the REST API" icon="file-lines" href="/guides/text-to-speech-rest">
    One-shot synthesis with a single HTTP POST.
  </Card>

  <Card title="LLM to TTS" icon="message-lines" href="/guides/recipes/llm-to-tts">
    Stream generated text into TTS while preserving natural prosody.
  </Card>

  <Card title="Voice settings" icon="sliders" href="/guides/voice-settings">
    Speed, temperature, voice similarity, rewrite rules.
  </Card>

  <Card title="Voice Library" icon="user-music" href="/guides/voices/overview">
    Browse flagship voices or create your own clones.
  </Card>
</CardGroup>