# Cartesia (/en/ai/platform/models/tts/cartesia)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

> Documentation: Conversational AI.
> Documentation version: Preview.
> This document describes only this version. [Version index](/llms/doc-versions-convoai-guides-v2.txt).


Cartesia provides ultra-fast, low-latency text-to-speech with real-time streaming capabilities, optimized for interactive conversational AI applications.

## Sample configuration

The following example shows how to configure Cartesia as the agent's TTS when you create or update an agent. For a complete example, see [Create an agent and start a session](/en/ai/platform/get-started/start-stop-agent#create-an-agent).

Cartesia supports BYOK only. It isn't available in managed mode. Store your Cartesia API key in a secret set, and refer to it from the agent. For details, see [Use your own provider keys](/en/ai/platform/build/use-your-own-keys).

**Python SDK**

```python
from agora_agent import Agent, CartesiaTTS, secret_ref

# client is your configured Agora client
agent = (
    Agent(client=client)
    .with_stt(...)  # configure your ASR vendor
    .with_llm(...)  # configure your LLM vendor
    .with_tts(
        CartesiaTTS(
            api_key=secret_ref("support_prod", "cartesia"),
            base_url="wss://api.cartesia.ai",
            model_id="sonic-2",
            voice_id="<voice_id>",
            sample_rate=16000,
            language="en",
        )
    )
)
```

**TypeScript SDK**

```ts
import { Agent, CartesiaTTS, secretRef } from 'agora-agents';

// client is your configured Agora client
const agent = new Agent({ client })
  .withStt(/* configure your ASR vendor */)
  .withLlm(/* configure your LLM vendor */)
  .withTts(
    new CartesiaTTS({
      apiKey: secretRef('support_prod', 'cartesia'),
      baseUrl: 'wss://api.cartesia.ai',
      modelId: 'sonic-2',
      voiceId: '<voice_id>',
      sampleRate: 16000,
      language: 'en',
    }),
  );
```

**Go SDK**

```go
// client is your configured Agora client
sampleRate := vendors.SampleRate16kHz
agent := agentkit.NewAgent(client).
	WithStt( /* configure your ASR vendor */ ).
	WithLlm( /* configure your LLM vendor */ ).
	WithTts(vendors.NewCartesiaTTS(vendors.CartesiaTTSOptions{
		APIKey:     agentkit.SecretRef("support_prod", "cartesia"),
		BaseURL:    "wss://api.cartesia.ai",
		ModelID:    "sonic-2",
		VoiceID:    "<voice_id>",
		SampleRate: &sampleRate,
		Language:   "en",
	}))
```

**REST API**

Set `credential.mode` to `byok` and `credential.fields.api_key` to a reference to your Cartesia API key. In the following example, the key is stored as `cartesia` in the `support_prod` set:

```json
"tts": {
  "credential": {
    "mode": "byok",
    "fields": {
      "api_key": "$secrets.support_prod.cartesia"
    }
  },
  "vendor": "cartesia",
  "url": "wss://api.cartesia.ai",
  "params": {
    "model_id": "sonic-2",
    "voice": {
      "mode": "id",
      "id": "<voice_id>"
    },
    "output_format": {
      "container": "raw",
      "sample_rate": 16000
    },
    "language": "en"
  }
}
```

## Key parameters

The `tts` block takes the following fields. In the SDKs, `CartesiaTTS` sets them from its options.

**tts**

**`vendor` (string) required**

Set to `cartesia`.

**`credential` (object) required**

Set `mode` to `byok` and `fields.api_key` to a `$secrets.<set>.<key>` reference to your Cartesia API key. Get your API key from the [Cartesia Console](https://play.cartesia.ai/sign-up).

**`url` (string) optional**

The WebSocket URL for the Cartesia streaming API. For example, `wss://api.cartesia.ai`.

**`params` (object) required**

**`model_id` (string) required**

The identifier of the TTS model to use. For example, `sonic-2`.

**`voice` (object) required**

Voice configuration object.

**`mode` (string) required**

Voice selection mode. Use `id` to select by voice identifier.

**`id` (string) required**

The identifier of the selected voice for speech synthesis.

**`output_format` (object) optional**

Audio output format configuration

**`container` (string) optional**

Audio container format for the output stream.

**`sample_rate` (number) optional**

Default value: `16000`

Possible values: `8000, 16000, 22050, 24000, 44100, 48000`

Audio sampling rate in Hz

**`language` (string) optional**

Target language for speech synthesis.

> **Caution**
>
> The parameters listed on this page are validated for use with the Conversational AI Platform. Required parameters must be provided as documented. Any additional parameters in `params` are passed through directly to Cartesia without validation. For a full list of supported options, refer to the [Cartesia TTS documentation](https://docs.cartesia.ai/).

This integration is fully supported for use with the Conversational AI Platform. While it has completed functional validation, it is newer to the platform, and additional provider-specific edge cases may be identified as usage scales across a broader range of applications and workloads.