Gradium Speech-to-Text

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. Transcribes English by default. Set settings.language to one of the other supported languages (German, Spanish, French, Portuguese), or to "any" to have Gradium detect the language. By default the pipeline’s VAD closes each utterance. With enable_turn_detection=True the server’s end-pointing signal drives turns instead: the service broadcasts ProposedUserStartedSpeakingFrame and ProposedUserStoppedSpeakingFrame, and recommends ExternalUserTurnStrategies to resolve them.

Gradium STT API Reference

Pipecat’s API methods for Gradium STT integration

Example Implementation

Complete example with interruption handling

Turn Detection Example

Server-side turn detection example

Gradium Documentation

Official Gradium STT API documentation

Gradium Platform

Access API keys and speech models

Installation

To use Gradium services, install the required dependency:

uv add "pipecat-ai[gradium]"

Prerequisites

Gradium Account Setup

Before using Gradium STT services, you need:

Gradium Account: Sign up at Gradium
API Key: Generate an API key from your account dashboard
Region Selection: Choose your preferred region (EU or US)

Required Environment Variables

GRADIUM_API_KEY: Your Gradium API key for authentication

Configuration

GradiumSTTService

str

required

Gradium API key for authentication.

str

default:"wss://api.gradium.ai/api/speech/asr"

WebSocket endpoint URL. Gradium automatically routes traffic to the nearest endpoint. Override to pin to a specific region or custom deployment.

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.

int | None

default:"None"

Audio sample rate in Hz. If None, uses the pipeline’s audio sample rate.

GradiumSTTService.InputParams

default:"None"

deprecated

Configuration parameters for language and delay settings. Deprecated in v0.0.105. Use settings=GradiumSTTService.Settings(...) instead.

str

default:"None"

Optional JSON configuration string for additional model settings. Deprecated in favor of params.

bool

default:"False"

Whether the server’s end-pointing signal decides when user turns start and end, instead of the pipeline’s VAD. When on, the service proposes turn boundaries (ProposedUserStartedSpeakingFrame and ProposedUserStoppedSpeakingFrame) and recommends ExternalUserTurnStrategies to the user aggregator.

GradiumSTTService.Settings

default:"None"

Runtime-configurable settings for the STT service. See Settings below.

float

default:"GRADIUM_TTFS_P99"

P99 latency from speech end to final transcript in seconds. Override for your deployment. See stt-benchmark.

Settings

Runtime-configurable settings passed via the settings constructor argument using GradiumSTTService.Settings(...). These can be updated mid-conversation with STTUpdateSettingsFrame. See Service Settings for details. The turn detection settings (eot_horizon_s, eot_threshold, post_flush_cooldown_frames) are None unless the service is constructed with enable_turn_detection=True, which gives them their defaults.

Parameter	Type	Default	Description
`model`	`str`	`"default"`	STT model identifier. (Inherited from base STT settings.)
`language`	`Language \| str`	`Language.EN`	Expected language of the audio. (Inherited from base STT settings.) Helps ground the model to a specific language and improve transcription quality. Defaults to `Language.EN`; `"any"` asks Gradium to detect the language.
`delay_in_frames`	`int`	`12`	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 12 (960ms). Sent to Gradium API via json_config.
`eot_horizon_s`	`float \| None`	`3.0`	Which end-pointing horizon drives turn decisions; the step entry with the closest `horizon_s` is used. (Only set when `enable_turn_detection=True`.)
`eot_threshold`	`float \| None`	`0.5`	Inactivity probability on that horizon at or above which an open turn ends, and below which a turn opens once the signal has read inactive. (Only set when `enable_turn_detection=True`.)
`post_flush_cooldown_frames`	`int \| None`	`8`	Number of step messages to ignore after a flush completes before the next turn may start or end. A flush feeds the model `delay_in_frames` of silence, and the end-pointing signal is unreliable on the frames that follow: it can dip as if speech resumed, then fire again on the first real frames. (Only set when `enable_turn_detection=True`.)

Usage

Basic Setup

from pipecat.services.gradium.stt import GradiumSTTService

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

With Language and Delay Configuration

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,
    ),
)

With Server-Side Turn Detection

from pipecat.services.gradium.stt import GradiumSTTService

stt = GradiumSTTService(
    api_key=os.getenv("GRADIUM_API_KEY"),
    enable_turn_detection=True,
    settings=GradiumSTTService.Settings(
        eot_horizon_s=3.0,
        eot_threshold=0.5,
    ),
)

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.
Turn detection: With enable_turn_detection=True, the server’s end-pointing signal decides when user turns start and end. The service broadcasts ProposedUserStartedSpeakingFrame when a turn opens and ProposedUserStoppedSpeakingFrame when it closes, then flushes the server. The final TranscriptionFrame follows once the flush is acknowledged. Local VAD frames are ignored. The service recommends ExternalUserTurnStrategies, which resolve the proposals into user turn frames and hold the turn open until the transcript arrives.

The InputParams / params= pattern is deprecated as of v0.0.105. Use Settings / settings= instead. See the Service Settings guide for migration details.

Event Handlers

Gradium STT supports the standard service connection events:

Event	Description
`on_connected`	Connected to Gradium WebSocket
`on_disconnected`	Disconnected from Gradium WebSocket
`on_turn_start`	The end-pointing signal opened a turn (turn detection only)
`on_turn_end`	The end-pointing signal closed the turn (turn detection only)

@stt.event_handler("on_connected")
async def on_connected(service):
    print("Connected to Gradium")

@stt.event_handler("on_turn_start")
async def on_turn_start(service):
    print("Turn started")

@stt.event_handler("on_turn_end")
async def on_turn_end(service):
    print("Turn ended")

Get Started

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

Gradium Speech-to-Text

Overview

Gradium STT API Reference

Example Implementation

Turn Detection Example

Gradium Documentation

Gradium Platform

Installation

Prerequisites

Gradium Account Setup

Required Environment Variables

Configuration

GradiumSTTService

Settings

Usage

Basic Setup

With Language and Delay Configuration

With Server-Side Turn Detection

Notes

Event Handlers

​Overview

Gradium STT API Reference

Example Implementation

Turn Detection Example

Gradium Documentation

Gradium Platform

​Installation

​Prerequisites

​Gradium Account Setup

​Required Environment Variables

​Configuration

​GradiumSTTService

​Settings

​Usage

​Basic Setup

​With Language and Delay Configuration

​With Server-Side Turn Detection

​Notes

​Event Handlers

Overview

Installation

Prerequisites

Gradium Account Setup

Required Environment Variables

Configuration

GradiumSTTService

Settings

Usage

Basic Setup

With Language and Delay Configuration

With Server-Side Turn Detection

Notes

Event Handlers