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

# LiveKit

> Use Gradium speech models in LiveKit Agents

LiveKit Agents is a framework for realtime voice AI over WebRTC, SIP, and streaming media. The Gradium plugin lets a LiveKit agent use Gradium for speech-to-text, text-to-speech, or both inside the same `AgentSession`.

<CardGroup cols={2}>
  <Card title="Gradium TTS plugin" icon="volume-2" href="https://docs.livekit.io/agents/models/tts/gradium/">
    LiveKit's guide to Gradium text-to-speech.
  </Card>

  <Card title="Gradium STT plugin" icon="mic" href="https://docs.livekit.io/agents/models/stt/gradium/">
    LiveKit's guide to Gradium speech-to-text.
  </Card>

  <Card title="Plugin reference" icon="code" href="https://docs.livekit.io/reference/python/livekit/plugins/gradium/index.html">
    Python API reference for `livekit.plugins.gradium`.
  </Card>

  <Card title="Gradium guide" icon="book" href="https://gradium.ai/content/how-to-build-voice-ai-agent-gradium-livekit">
    End-to-end Gradium and LiveKit voice agent walkthrough.
  </Card>
</CardGroup>

## Install

Install LiveKit Agents with the Gradium plugin extra:

```bash theme={null}
pip install "livekit-agents[gradium]~=1.5"
```

Set the required credentials in your environment:

```bash theme={null}
export LIVEKIT_URL=wss://your-project.livekit.cloud
export LIVEKIT_API_KEY=your-livekit-api-key
export LIVEKIT_API_SECRET=your-livekit-api-secret
export GRADIUM_API_KEY=gd_your_api_key_here
```

## Basic agent session

Use `gradium.STT()` to transcribe user audio and `gradium.TTS()` to synthesize agent replies.

```python theme={null}
from livekit.agents import AgentSession
from livekit.plugins import gradium

session = AgentSession(
    stt=gradium.STT(),
    tts=gradium.TTS(
        voice_id="YTpq7expH9539ERJ",
    ),
    # ... llm, vad, tools, and other session options
)
```

You can also use only one side of Gradium. For example, keep an existing STT provider and use Gradium just for speech output:

```python theme={null}
session = AgentSession(
    tts=gradium.TTS(),
    # ... llm, stt, etc.
)
```

## Configuration

Common Gradium options in LiveKit Agents:

| Setting            | Applies to | Description                                                                      |
| ------------------ | ---------- | -------------------------------------------------------------------------------- |
| `api_key`          | STT, TTS   | Gradium API key. Defaults to `GRADIUM_API_KEY`.                                  |
| `model_endpoint`   | STT, TTS   | Gradium WebSocket endpoint. Use the US endpoint when you need US-region routing. |
| `model_name`       | STT, TTS   | Gradium model name. Defaults to `default`.                                       |
| `voice_id`         | TTS        | Gradium voice ID for synthesized replies. Defaults to Emma.                      |
| `pronunciation_id` | TTS        | Optional Gradium pronunciation dictionary ID.                                    |
| `json_config`      | TTS        | Advanced TTS settings such as speed and rewrite rules.                           |
| `vad_threshold`    | STT        | Semantic VAD threshold for detecting when the user has finished speaking.        |
| `vad_bucket`       | STT        | Semantic VAD timing bucket.                                                      |

## Custom pronunciation

Pass a Gradium pronunciation dictionary ID into the TTS plugin when an agent needs brand names, product names, or domain-specific terms spoken consistently.

```python theme={null}
tts = gradium.TTS(
    voice_id="YTpq7expH9539ERJ",
    pronunciation_id="pronunciation_dictionary_id",
)
```

For lower-level pronunciation and rewrite behavior, see [Pronunciation Dictionaries](/guides/text-to-speech#pronunciation-dictionary) and [Voice Settings](/guides/voice-settings).

## When to use LiveKit with Gradium

* **Realtime voice agents**: run a complete STT, LLM, and TTS loop in `AgentSession`.
* **WebRTC applications**: connect browser and mobile users to Gradium-powered speech through LiveKit rooms.
* **Telephony agents**: use LiveKit SIP while keeping Gradium as the speech model layer.
* **Production deployments**: deploy LiveKit agents with managed rooms, credentials, and worker processes.