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

# Cartesia

> Speech-to-text service implementation using Cartesia's real-time transcription API

## Overview

`CartesiaSTTService` provides real-time speech recognition using Cartesia's WebSocket API with the `ink-whisper` model, supporting streaming transcription with both interim and final results for low-latency applications.

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

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/transcription/transcription-cartesia.py">
    Complete example with transcription logging
  </Card>

  <Card title="Cartesia Documentation" icon="book" href="https://docs.cartesia.ai/api-reference/stt/stt">
    Official Cartesia STT documentation and features
  </Card>

  <Card title="Cartesia Platform" icon="microphone" href="https://cartesia.ai/">
    Access API keys and transcription models
  </Card>
</CardGroup>

## Installation

To use Cartesia services, install the required dependency:

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

## Prerequisites

### Cartesia Account Setup

Before using Cartesia STT services, you need:

1. **Cartesia Account**: Sign up at [Cartesia](https://cartesia.ai/)
2. **API Key**: Generate an API key from your account dashboard
3. **Model Access**: Ensure access to the ink-whisper transcription model

### Required Environment Variables

* `CARTESIA_API_KEY`: Your Cartesia API key for authentication

## Configuration

### CartesiaSTTService

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

<ParamField path="base_url" type="str" default="">
  Custom API endpoint URL. If empty, defaults to `"api.cartesia.ai"`. Override
  for proxied deployments.
</ParamField>

<ParamField path="encoding" type="str" default="pcm_s16le">
  Audio encoding format.
</ParamField>

<ParamField path="sample_rate" type="int" default="None">
  Audio sample rate in Hz.
</ParamField>

<ParamField path="live_options" type="CartesiaLiveOptions | None" default="None" deprecated>
  Configuration options for the transcription service. *Deprecated in v0.0.105.
  Use `settings=CartesiaSTTService.Settings(...)` for model/language and direct
  init parameters for encoding/sample\_rate instead.*
</ParamField>

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

<ParamField path="ttfs_p99_latency" type="float" default="CARTESIA_TTFS_P99">
  P99 latency from speech end to final transcript in seconds. Override for your
  deployment.
</ParamField>

### Settings

Runtime-configurable settings passed via the `settings` constructor argument using `CartesiaSTTService.Settings(...)`. These can be updated mid-conversation with `STTUpdateSettingsFrame`, which triggers an automatic reconnection with the new parameters. See [Service Settings](/pipecat/fundamentals/service-settings) for details.

| Parameter  | Type              | Default         | Description                                                              |
| ---------- | ----------------- | --------------- | ------------------------------------------------------------------------ |
| `model`    | `str`             | `"ink-whisper"` | The transcription model to use. *(Inherited from base STT settings.)*    |
| `language` | `Language \| str` | `"en"`          | Target language for transcription. *(Inherited from base STT settings.)* |

## Usage

### Basic Setup

```python theme={null}
from pipecat.services.cartesia.stt import CartesiaSTTService

stt = CartesiaSTTService(
    api_key=os.getenv("CARTESIA_API_KEY"),
)
```

### With Custom Options

```python theme={null}
from pipecat.services.cartesia.stt import CartesiaSTTService

stt = CartesiaSTTService(
    api_key=os.getenv("CARTESIA_API_KEY"),
    settings=CartesiaSTTService.Settings(
        model="ink-whisper",
        language="es",
    ),
    sample_rate=16000,
)
```

## Notes

* **Inactivity timeout**: Cartesia disconnects WebSocket connections after 3 minutes of inactivity. The timeout resets with each message sent. Silence-based keepalive is enabled by default to prevent disconnections.
* **Auto-reconnect on send**: If the connection is closed (e.g., due to timeout), the service automatically reconnects when the next audio data is sent.
* **Runtime settings updates**: Changing settings (e.g., `language` or `model`) via `STTUpdateSettingsFrame` triggers a reconnection with the new parameters. To avoid audio loss, reconnection is deferred until the current user turn ends (i.e., until `UserStoppedSpeakingFrame` is received). Audio frames arriving during the reconnect are buffered and replayed once the new connection is ready. This enables safe dynamic language switching mid-conversation.
* **Finalize on VAD stop**: When the pipeline's VAD detects the user has stopped speaking, the service sends a `"finalize"` command to flush the transcription session and produce a final result.

<Tip>
  The `InputParams` / `params=` / `live_options=` 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

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

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

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