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

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

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

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

  const tts = CartesiaTTS({
    generation_config: {
      speed: 0.9,
      volume: 1.2,
      emotion: 'calm',
    },
  });
  ```
</CodeGroup>

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.