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.

Gradium STT API Reference

Pipecat’s API methods for Gradium STT integration

Example Implementation

Complete example with interruption handling

Gradium Documentation

Official Gradium STT API documentation

Gradium Platform

Access API keys and speech models

Installation

To use Gradium services, install the required dependency:

pip install "pipecat-ai[gradium]"

Prerequisites

Gradium Account Setup

Before using Gradium STT services, you need:

1. Gradium Account: Sign up at Gradium
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

api_key · str · required

Gradium API key for authentication.

api_endpoint_base_url · str · default: "wss://eu.api.gradium.ai/api/speech/asr"

WebSocket endpoint URL. Override for different regions or custom deployments.

params · InputParams · default: "None"

Configuration parameters for language and delay settings. See InputParams below.

json_config · str · default: "None"

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

InputParams

Runtime-configurable parameters that can be set at initialization via the params constructor argument.

Parameter	Type	Default	Description
language	Language	None	Expected language of the audio (e.g., Language.EN, Language.ES). Helps ground the model to a specific language and improve transcription quality.
delay_in_frames	int	None	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).

Usage

Basic Setup

from pipecat.services.gradium import GradiumSTTService

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

With Language and Delay Configuration

from pipecat.services.gradium import GradiumSTTService
from pipecat.transcriptions.language import Language

stt = GradiumSTTService(
    api_key=os.getenv("GRADIUM_API_KEY"),
    params=GradiumSTTService.InputParams(
        language=Language.EN,
        delay_in_frames=8,  # Lower delay for faster response
    ),
)

Notes

• Supported languages: German, English, Spanish, French, and Portuguese.
• Silence flushing: When VAD detects the user has stopped speaking, the service sends silence frames to flush the transcription buffer, resulting in faster final transcripts without closing the connection.
• Audio format: Sends audio as 24 kHz 16-bit PCM in 80ms chunks.

Event Handlers

Gradium STT supports the standard service connection events:

Event	Description
on_connected	Connected to Gradium WebSocket
on_disconnected	Disconnected from Gradium WebSocket

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