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

# Cartesia

> Python API reference for the cartesia speech-to-text plugin.

<Card title="Usage guide" icon="book" href="/plugins/stt/cartesia" horizontal>
  Setup, environment variables, and Python/JavaScript/Go usage examples.
</Card>

## CartesiaSTTModel

```python theme={null}
CartesiaSTTModel = typing.Literal['ink-2', 'ink-whisper']
```

***

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

```python theme={null}
CartesiaSTT(*, api_key: 'str | None' = None, model: 'CartesiaSTTModel | str' = 'ink-whisper', language: 'str' = 'en', input_sample_rate: 'int' = 48000, output_sample_rate: 'int' = 16000, encoding: 'str' = 'pcm_s16le', cartesia_version: 'str' = '2026-03-01', min_volume: 'Optional[float]' = None, max_silence_duration_secs: 'Optional[float]' = None, base_url: 'str | None' = None, **kwargs) -> 'None'
```

<ParamField path="api_key" type="str | None">
  Cartesia API key for authentication.  Falls back to the `CARTESIA_API_KEY` environment variable when omitted.
</ParamField>

<ParamField path="model" type="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.
</ParamField>

<ParamField path="language" type="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"`.
</ParamField>

<ParamField path="input_sample_rate" type="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).
</ParamField>

<ParamField path="output_sample_rate" type="int" default="16000">
  Sample rate in Hz at which Cartesia processes audio internally.  Defaults to `16000`.
</ParamField>

<ParamField path="encoding" type="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"`.
</ParamField>

<ParamField path="cartesia_version" type="str" default="2026-03-01">
  Cartesia API version header in `"YYYY-MM-DD"` format.  Defaults to `"2026-03-01"`.
</ParamField>

<ParamField path="min_volume" type="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`.
</ParamField>

<ParamField path="max_silence_duration_secs" type="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`.
</ParamField>

<ParamField path="base_url" type="str | None">
  Override the Cartesia WebSocket base URL.  Defaults to `None` (uses `wss://api.cartesia.ai`).
</ParamField>

### aclose

```python theme={null}
def aclose(self) -> 'None'
```

Release any resources held by the provider.

### emit

```python theme={null}
def emit(self, event: 'T', *args: 'Any') -> 'None'
```

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.

<ParamField path="event" type="T" required>
  The event to emit.
</ParamField>

### off

```python theme={null}
def off(self, event: 'T', callback: 'Callable[..., Any]') -> 'None'
```

Remove a previously registered handler for an event.

If the handler is not registered for the event, the call is a no-op.

<ParamField path="event" type="T" required>
  The event the handler was registered for.
</ParamField>

<ParamField path="callback" type="Callable[..., Any]" required>
  The handler to remove.
</ParamField>

### on

```python theme={null}
def on(self, event: 'T', callback: 'Callable[..., Any] | None' = None) -> 'Callable[..., Any]'
```

Register a handler for an event.

Can be used directly by passing a callback, or as a decorator when
`callback` is omitted.

<ParamField path="event" type="T" required>
  The event to listen for.
</ParamField>

<ParamField path="callback" type="Callable[..., Any] | None">
  The handler to invoke when the event is emitted. If `None`, a decorator is returned that registers the decorated function.
</ParamField>

<ResponseField name="returns" type="Callable[..., Any]">
  The registered callback when `callback` is provided, otherwise a decorator that registers and returns the function it wraps.
</ResponseField>

### on\_stt\_transcript

```python theme={null}
def on_stt_transcript(self, callback: 'Callable[[STTResponse], Awaitable[None]]') -> 'None'
```

Register the coroutine invoked when a transcription event is produced.

<ParamField path="callback" type="Callable[[STTResponse], Awaitable[None]]" required>
  An async callable that receives each `STTResponse`.
</ParamField>

### process\_audio

```python theme={null}
def process_audio(self, audio_frames: 'bytes', language: 'Optional[str]' = None, **kwargs: 'Any') -> 'None'
```

Process a chunk of audio for transcription.

Implementations should consume the audio frames and emit transcription
results through the registered transcript callback.

<ParamField path="audio_frames" type="bytes" required>
  Raw audio bytes to transcribe.
</ParamField>

<ParamField path="language" type="Optional[str]">
  Optional language code to guide recognition.
</ParamField>

### stream\_transcribe

```python theme={null}
def stream_transcribe(self, audio_stream: 'AsyncIterator[bytes]', **kwargs: 'Any') -> 'AsyncIterator[STTResponse]'
```

Transcribe a continuous audio stream.

<ParamField path="audio_stream" type="AsyncIterator[bytes]" required>
  An async iterator yielding raw audio byte chunks.
</ParamField>

<ResponseField name="returns" type="AsyncIterator[STTResponse]">
  STTResponse: Transcription events produced as audio is consumed.
</ResponseField>