> ## 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.

# Speech-to-Text Overview

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

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

## Choosing a model

Two kinds of Speech-to-Text model are available, selected with `model_name`:

* **`"default"`** — a standard transcription model. The transcription is
  produced in the language of the audio.
* **`"stt-translate"`** — a translating transcription model. The
  transcription is generated in another language, which you choose with
  `language` (or `target_language`). See [Transcription Settings](/guides/transcription-settings#languages).

Both kinds work identically over either transport.

## WebSocket vs REST

| If your audio is...                                                          | Use                                                | Why                                                                                                                             |
| ---------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Live (microphone, telephony, agent loop) and you need sub-second turn-taking | [WebSocket](/guides/speech-to-text)                | Lowest latency. Push audio as it's captured, get text and VAD signals as they're produced. React to end-of-turn in real time.   |
| A complete file you already have on disk or in memory                        | [REST](/guides/speech-to-text-rest)                | One HTTP POST with the audio in the body. No connection to manage; the server streams NDJSON results back as the response body. |
| In hand but you want VAD signals or to react to flush events                 | [WebSocket](/guides/speech-to-text)                | Use `stt_stream` (pull-based) over the WebSocket. Same low latency, no manual connection management.                            |
| Browser microphone or mobile client audio                                    | [Browser WebSockets](/guides/browser-websockets)   | Use short-lived tokens instead of exposing an API key.                                                                          |
| Telephony media streams                                                      | [Telephony Audio](/guides/recipes/telephony-audio) | Use `ulaw_8000`, `alaw_8000`, or low-sample-rate PCM directly.                                                                  |

If you're transcribing pre-recorded audio and don't need VAD, REST is
the simpler path. Move to WebSocket when you need live audio,
turn-taking, or in-stream `flush`.

## What both transports share

* **Models**: same `model_name` works on both.
* **Input formats**: PCM (multiple sample rates), WAV, Opus, mu-law, A-law.
* **Tunable options**: `temp`, `language`, `padding_bonus`, `delay_in_frames`, and a `keywords` dictionary for [boosting names and jargon](/guides/transcription-settings#keyword-boosting), all via `json_config`. See [Transcription Settings](/guides/transcription-settings).

## What's transport-specific

* **WebSocket-only**: semantic VAD `step` messages every 80 ms, in-stream `send_flush()` for forced processing, adaptive delay controls (`delay_in_frames`), setup-message stream controls (`send_setup_on_start`, `wait_for_ready_on_start`), browser tokens. See [WebSocket Lifecycle](/guides/websocket-lifecycle).
* **REST-only**: send the full audio as the request body; receive NDJSON over a streaming response.

## Next steps

<CardGroup cols={2}>
  <Card title="Use the WebSocket API" icon="waveform-lines" href="/guides/speech-to-text">
    Streaming audio in, transcripts and VAD signals out, with flush
    control.
  </Card>

  <Card title="Use the REST API" icon="file-audio" href="/guides/speech-to-text-rest">
    One-shot transcription of a complete audio file.
  </Card>

  <Card title="Turn-taking recipe" icon="comments" href="/guides/recipes/turn-taking">
    Use semantic VAD and adaptive delay to decide when an agent should answer.
  </Card>

  <Card title="Keyword boosting recipe" icon="spell-check" href="/guides/recipes/keyword-boosting">
    Recognize names, brands, and jargon by biasing STT toward a custom dictionary.
  </Card>

  <Card title="GitHub examples" icon="github" href="https://github.com/gradium-ai/gradbot/tree/main/demos">
    Browse complete voice-agent demos built with Gradium STT and TTS.
  </Card>

  <Card title="Transcription settings" icon="sliders" href="/guides/transcription-settings">
    `language`, `temp`, `padding_bonus`, `delay_in_frames`.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/guides/errors">
    Error contracts across REST, WebSocket, and streamed responses.
  </Card>
</CardGroup>