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

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

## GenerationConfig

Grouped generation settings for CartesiaTTS. Flat options on
`CartesiaTTSOptions` take precedence over the matching field here.

### Constructor

```typescript theme={null}
new GenerationConfig(opts: { speed?: number | null; emotion?: string | null; volume?: number | null; pronunciationDictId?: string | null; maxBufferDelayMs?: number | null; enableWordTimestamps?: boolean; })
```

<ParamField path="speed" type="number | null" />

<ParamField path="emotion" type="string | null" />

<ParamField path="volume" type="number | null" />

<ParamField path="pronunciationDictId" type="string | null" />

<ParamField path="maxBufferDelayMs" type="number | null" />

<ParamField path="enableWordTimestamps" type="boolean" />

***

## CartesiaTTS

Cartesia text-to-speech provider.

Creates a configured Cartesia TTS provider for use in a voice agent.

### Constructor

```typescript theme={null}
new CartesiaTTS(opts: CartesiaTTSOptions)
```

<ParamField path="apiKey" type="string">
  Cartesia API key. Falls back to the `CARTESIA_API_KEY` env var.
</ParamField>

<ParamField path="voice" type="string | number[] | null">
  Voice as a catalog UUID (string) or a cloning embedding (non-empty number array). Default: a built-in voice UUID.
</ParamField>

<ParamField path="voiceId" type="string | number[] | null">
  Alias for `voice`; used when `voice` is not set.
</ParamField>

<ParamField path="model" type="CartesiaTTSModel | string">
  Synthesis model. Default: `'sonic-2'`.
</ParamField>

<ParamField path="language" type="string">
  Synthesis language code. Default: `'en'`.
</ParamField>

<ParamField path="sampleRate" type="number">
  Output audio sample rate in Hz. Default: `24000`. (The effective rate is fixed; other values are ignored.)
</ParamField>

<ParamField path="speed" type="number | null">
  Speaking speed. Default: `null` (or `generationConfig.speed`).
</ParamField>

<ParamField path="volume" type="number | null">
  Output volume. Default: `null` (or `generationConfig.volume`).
</ParamField>

<ParamField path="emotion" type="string | null">
  Emotion tag. Default: `null` (or `generationConfig.emotion`).
</ParamField>

<ParamField path="pronunciationDictId" type="string | null">
  Pronunciation dictionary ID. Default: `null` (or `generationConfig.pronunciationDictId`).
</ParamField>

<ParamField path="maxBufferDelayMs" type="number | null">
  Max buffering delay in ms. Default: `null` (or `generationConfig.maxBufferDelayMs`).
</ParamField>

<ParamField path="enableWordTimestamps" type="boolean | null">
  Emit per-word timestamps. Default: `false` (or `generationConfig.enableWordTimestamps`).
</ParamField>

<ParamField path="generationConfig" type="GenerationConfig | null">
  Grouped generation settings; flat options above take precedence. Default: `null`.
</ParamField>

### close

```typescript theme={null}
close(): Promise<void>
```

Release any resources held by the provider.

### closeEmitter

```typescript theme={null}
closeEmitter(): Promise<void>
```

Close the emitter: drop all handlers and stop emitting. Waits up to 2 seconds
for in-flight async handlers to settle before returning.

### emit

```typescript theme={null}
emit(event: string, ...args: any[]): void
```

<ParamField path="event" type="string" required />

### getRuntimeConfig

```typescript theme={null}
getRuntimeConfig(): Record<string, any>
```

<ResponseField name="returns" type="Record<string, any>" />

### interrupt

```typescript theme={null}
interrupt(): Promise<void>
```

Stop the current synthesis.

### listenerCount

```typescript theme={null}
listenerCount(event: string): number
```

<ParamField path="event" type="string" required />

<ResponseField name="returns" type="number" />

### off

```typescript theme={null}
off(event: string, handler: EventHandler): void
```

<ParamField path="event" type="string" required />

<ParamField path="handler" type="EventHandler" required />

### on

```typescript theme={null}
on(event: string, handler: EventHandler): EventHandler
```

<ParamField path="event" type="string" required />

<ParamField path="handler" type="EventHandler" required />

<ResponseField name="returns" type="EventHandler" />

### once

```typescript theme={null}
once(event: string, handler: EventHandler): EventHandler
```

<ParamField path="event" type="string" required />

<ParamField path="handler" type="EventHandler" required />

<ResponseField name="returns" type="EventHandler" />

### onFirstAudioByte

```typescript theme={null}
onFirstAudioByte(callback: FirstAudioByteCallback): void
```

Register a callback fired when the first synthesized audio byte is emitted.

<ParamField path="callback" type="FirstAudioByteCallback" required />

### removeAllListeners

```typescript theme={null}
removeAllListeners(event?: string): void
```

<ParamField path="event" type="string" />

### synthesize

```typescript theme={null}
synthesize(text: any, ..._extra: any[]): Promise<void>
```

Synthesize and speak `text` on the active session.

<ParamField path="text" type="any" required />

***

## CartesiaTTSModel

Supported Cartesia text-to-speech model names.

```typescript theme={null}
type CartesiaTTSModel = 'sonic-3.5' | 'sonic-3' | 'sonic-2' | 'sonic-turbo'
```