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

> Use the Cartesia text-to-speech plugin in a Zero Runtime pipeline. Setup and usage in Python and JavaScript.

Cartesia is a **text-to-speech** plugin. It turns the LLM's reply into audio the caller
hears.

## Setup

Set your Cartesia API key in the worker environment. Generate a key from the [Cartesia dashboard](https://play.cartesia.ai/keys):

```bash theme={null}
export CARTESIA_API_KEY=<key>
```

## Usage

Import the plugin and pass it to the pipeline's `tts` slot.

<CodeGroup>
  ```python Python theme={null}
  from zeroruntime.plugins import CartesiaTTS

  tts = CartesiaTTS()

  # Pipeline(tts=tts, ...)
  ```

  ```typescript Node JS theme={null}
  import { CartesiaTTS } from '@zeroruntime/js-sdk/plugins';

  const tts = CartesiaTTS();

  // Pipeline({ tts, ... })
  ```
</CodeGroup>

## Parameters

*Constructor parameters for `CartesiaTTS`. The Python and Node JS SDKs share these field names.*

| Parameter                | Type                 | Default                                  | Description                                                                             |
| ------------------------ | -------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------- |
| `api_key`                | `str`                | `None`                                   | Cartesia API key. Falls back to the `CARTESIA_API_KEY` environment variable when unset. |
| `model`                  | `str`                | `"sonic-2"`                              | Cartesia voice model.                                                                   |
| `voice_id`               | `str \| list[float]` | `"f8f5f1b2-f02d-4d8e-a40d-fd850a487b3d"` | Voice to speak with: a voice ID or an embedding vector.                                 |
| `language`               | `str`                | `"en"`                                   | Language of the spoken output.                                                          |
| `generation_config`      | `GenerationConfig`   | `None`                                   | Fine-grained synthesis settings such as speed, volume, and emotion.                     |
| `pronunciation_dict_id`  | `str`                | `None`                                   | ID of a custom pronunciation dictionary to apply.                                       |
| `max_buffer_delay_ms`    | `int`                | `None`                                   | Maximum time to buffer text before synthesizing, trading latency for smoother audio.    |
| `enable_word_timestamps` | `bool`               | `False`                                  | Return per-word timing alongside the audio.                                             |

`generation_config` can be passed as a dictionary with Cartesia's supported voice-shaping fields:

* `speed`: `0.6` to `1.5` (`1.0` = default speed)
* `volume`: `0.5` to `2.0` (`1.0` = default volume)
* `emotion`: one of `"neutral"`, `"calm"`, `"angry"`, `"content"`, or `"sad"`

```python theme={null}
from zeroruntime.plugins import CartesiaTTS

tts = CartesiaTTS(
    generation_config={
        "speed": 0.9,
        "volume": 1.2,
        "emotion": "calm",
    }
)
```

## Import paths

| SDK     | Import                                                      | Constructor     |
| ------- | ----------------------------------------------------------- | --------------- |
| Python  | `from zeroruntime.plugins import CartesiaTTS`               | `CartesiaTTS()` |
| Node JS | `import { CartesiaTTS } from '@zeroruntime/js-sdk/plugins'` | `CartesiaTTS()` |

Spoken replies support interruptions. When the caller talks over the agent, the runtime
stops the audio and listens again.