Skip to main content

Usage guide

Setup, environment variables, and Python/JavaScript/Go usage examples.

​
CartesiaSTTModel

​
CartesiaSTT

Cartesia Speech-to-Text provider. Streams audio to Cartesia’s ink-whisper STT model via WebSocket for low-latency, real-time transcription. Supports 100+ languages in ISO 639-1 format with configurable silence detection and volume thresholds.

​
Constructor

​
api_key
str | None
Cartesia API key for authentication. Falls back to the CARTESIA_API_KEY environment variable when omitted.
​
model
CartesiaSTTModel | str
default:"ink-whisper"
Cartesia STT model identifier. Defaults to "ink-whisper", which is the only currently available model. Accepts a CartesiaSTTModel enum value or a plain string.
​
language
str
default:"en"
ISO 639-1 language code for the spoken audio. Defaults to "en" (English). Over 100 languages are supported, including "fr", "de", "es", "zh", "ja", "pt", "ru", "ko", and "ar".
​
input_sample_rate
int
default:"48000"
Sample rate in Hz of the raw PCM audio sent to the WebSocket. Must match the capture rate of the audio source. Defaults to 48000 (the standard capture rate).
​
output_sample_rate
int
default:"16000"
Sample rate in Hz at which Cartesia processes audio internally. Defaults to 16000.
​
encoding
str
default:"pcm_s16le"
PCM encoding format of the input audio stream. Defaults to "pcm_s16le" (16-bit signed little-endian). Other valid options: "pcm_s32le", "pcm_f16le", "pcm_f32le", "pcm_mulaw", "pcm_alaw".
​
cartesia_version
str
default:"2026-03-01"
Cartesia API version header in "YYYY-MM-DD" format. Defaults to "2026-03-01".
​
min_volume
Optional[float]
Minimum RMS volume threshold (0.0–1.0) below which audio is treated as silence for automatic transcript finalization. Lower values capture quieter speech; higher values filter noisy environments. Defaults to None (Cartesia platform default). Only used by ink-whisper.
​
max_silence_duration_secs
Optional[float]
Maximum duration of continuous silence in seconds before the transcript is automatically finalized. Lower values finalize faster; higher values allow longer pauses. Defaults to None (Cartesia platform default). Only used by ink-whisper.
​
base_url
str | None
Override the Cartesia WebSocket base URL. Defaults to None (uses wss://api.cartesia.ai).

​
aclose

Release any resources held by the provider.

​
emit

Emit an event, invoking all registered handlers with the given arguments. Handlers are called in registration order. Coroutine handlers are scheduled on the running event loop. If the emitter is closed, the call is a no-op.
​
event
T
required
The event to emit.

​
off

Remove a previously registered handler for an event. If the handler is not registered for the event, the call is a no-op.
​
event
T
required
The event the handler was registered for.
​
callback
Callable[..., Any]
required
The handler to remove.

​
on

Register a handler for an event. Can be used directly by passing a callback, or as a decorator when callback is omitted.
​
event
T
required
The event to listen for.
​
callback
Callable[..., Any] | None
The handler to invoke when the event is emitted. If None, a decorator is returned that registers the decorated function.
​
returns
Callable[..., Any]
The registered callback when callback is provided, otherwise a decorator that registers and returns the function it wraps.

​
on_stt_transcript

Register the coroutine invoked when a transcription event is produced.
​
callback
Callable[[STTResponse], Awaitable[None]]
required
An async callable that receives each STTResponse.

​
process_audio

Process a chunk of audio for transcription. Implementations should consume the audio frames and emit transcription results through the registered transcript callback.
​
audio_frames
bytes
required
Raw audio bytes to transcribe.
​
language
Optional[str]
Optional language code to guide recognition.

​
stream_transcribe

Transcribe a continuous audio stream.
​
audio_stream
AsyncIterator[bytes]
required
An async iterator yielding raw audio byte chunks.
​
returns
AsyncIterator[STTResponse]
STTResponse: Transcription events produced as audio is consumed.