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

# Gradium

> Speech-to-text service using Gradium's real-time streaming API

## Overview

`GradiumSTTService` provides real-time speech recognition using Gradium's WebSocket API with support for multilingual transcription, semantic voice activity detection for smart turn-taking, and robust performance in noisy environments.

<CardGroup cols={2}>
  <Card title="Gradium STT API Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.services.gradium.stt.html">
    Pipecat's API methods for Gradium STT integration
  </Card>

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/voice/voice-gradium.py">
    Complete example with interruption handling
  </Card>

  <Card title="Gradium Documentation" icon="book" href="https://gradium.ai/api_docs.html#tag/STT">
    Official Gradium STT API documentation
  </Card>

  <Card title="Gradium Platform" icon="microphone" href="https://gradium.ai/">
    Access API keys and speech models
  </Card>
</CardGroup>

## Installation

To use Gradium services, install the required dependency:

```bash theme={null}
uv add "pipecat-ai[gradium]"
```

## Prerequisites

### Gradium Account Setup

Before using Gradium STT services, you need:

1. **Gradium Account**: Sign up at [Gradium](https://gradium.ai/)
2. **API Key**: Generate an API key from your account dashboard
3. **Region Selection**: Choose your preferred region (EU or US)

### Required Environment Variables

* `GRADIUM_API_KEY`: Your Gradium API key for authentication

## Configuration

### GradiumSTTService

<ParamField path="api_key" type="str" required>
  Gradium API key for authentication.
</ParamField>

<ParamField path="api_endpoint_base_url" type="str" default="wss://eu.api.gradium.ai/api/speech/asr">
  WebSocket endpoint URL. Override for different regions or custom deployments.
</ParamField>

<ParamField path="encoding" type="str" default="pcm">
  Base audio encoding type. One of `"pcm"`, `"wav"`, or `"opus"`. For PCM, the
  sample rate is appended automatically to form the input format (e.g., `"pcm"`
  becomes `"pcm_16000"`). PCM accepts 8000, 16000, and 24000 Hz sample rates.
</ParamField>

<ParamField path="sample_rate" type="int | None" default="None">
  Audio sample rate in Hz. If `None`, uses the pipeline's audio sample rate.
</ParamField>

<ParamField path="params" type="GradiumSTTService.InputParams" default="None" deprecated>
  Configuration parameters for language and delay settings. *Deprecated in
  v0.0.105. Use `settings=GradiumSTTService.Settings(...)` instead.*
</ParamField>

<ParamField path="json_config" type="str" default="None">
  Optional JSON configuration string for additional model settings. Deprecated
  in favor of `params`.
</ParamField>

<ParamField path="settings" type="GradiumSTTService.Settings" default="None">
  Runtime-configurable settings for the STT service. See [Settings](#settings)
  below.
</ParamField>

<ParamField path="ttfs_p99_latency" type="float" default="GRADIUM_TTFS_P99">
  P99 latency from speech end to final transcript in seconds. Override for your
  deployment. See [stt-benchmark](https://github.com/pipecat-ai/stt-benchmark).
</ParamField>

### Settings

Runtime-configurable settings passed via the `settings` constructor argument using `GradiumSTTService.Settings(...)`. These can be updated mid-conversation with `STTUpdateSettingsFrame`. See [Service Settings](/pipecat/fundamentals/service-settings) for details.

| Parameter         | Type              | Default     | Description                                                                                                                                                                                                                                       |
| ----------------- | ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`           | `str`             | `"default"` | STT model identifier. *(Inherited from base STT settings.)*                                                                                                                                                                                       |
| `language`        | `Language \| str` | `None`      | Expected language of the audio. *(Inherited from base STT settings.)* Helps ground the model to a specific language and improve transcription quality.                                                                                            |
| `delay_in_frames` | `int`             | `None`      | Server-side delay in audio frames (80ms each) before text is generated. Higher delays allow more context but increase latency. Allowed values: 7, 8, 10, 12, 14, 16, 20, 24, 36, 48. Default is 10 (800ms). Sent to Gradium API via json\_config. |

## Usage

### Basic Setup

```python theme={null}
from pipecat.services.gradium.stt import GradiumSTTService

stt = GradiumSTTService(
    api_key=os.getenv("GRADIUM_API_KEY"),
)
```

### With Language and Delay Configuration

```python theme={null}
from pipecat.services.gradium.stt import GradiumSTTService
from pipecat.transcriptions.language import Language

stt = GradiumSTTService(
    api_key=os.getenv("GRADIUM_API_KEY"),
    settings=GradiumSTTService.Settings(
        language=Language.EN,
        delay_in_frames=8,
    ),
)
```

## Notes

* **Supported languages**: German, English, Spanish, French, and Portuguese.
* **Audio format**: Configurable via `encoding` and `sample_rate` parameters. Defaults to PCM with the pipeline's sample rate. Supported PCM rates: 8000, 16000, and 24000 Hz. Audio is sent in 80ms chunks.

<Tip>
  The `InputParams` / `params=` pattern is deprecated as of v0.0.105. Use
  `Settings` / `settings=` instead. See the [Service Settings
  guide](/pipecat/fundamentals/service-settings) for migration details.
</Tip>

## Event Handlers

Gradium STT supports the standard [service connection events](/api-reference/server/events/service-events):

| Event             | Description                         |
| ----------------- | ----------------------------------- |
| `on_connected`    | Connected to Gradium WebSocket      |
| `on_disconnected` | Disconnected from Gradium WebSocket |

```python theme={null}
@stt.event_handler("on_connected")
async def on_connected(service):
    print("Connected to Gradium")
```