> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# LiveAvatar + Cartesia
> Drive a LiveAvatar (by HeyGen) interactive avatar with a Cartesia Sonic TTS voice
Last verified: 2026-08-05
## Overview
Use this integration to speak a [LiveAvatar](https://docs.liveavatar.com) avatar's responses with a [Cartesia Sonic TTS](/build-with-cartesia/tts-models/latest) voice. Set `provider` to `cartesia` in the session's [voice settings](https://docs.liveavatar.com/docs/full-mode/voice-settings) to render the avatar with Sonic — see [Use your own Cartesia voices](#use-your-own-cartesia-voices) to import your own API key and voices.
## Prerequisites
* LiveAvatar API key from [app.liveavatar.com/developers](https://app.liveavatar.com/developers)
* Node.js 22+ and pnpm 9+
* Cartesia API key (`sk_car_...`) from [Cartesia keys](https://play.cartesia.ai/keys) — only for importing your own Cartesia voices
## Quick start
The [LiveAvatar Web SDK](https://github.com/heygen-com/liveavatar-web-sdk) repo ships a Next.js demo app. Point it at your space, switch the TTS provider to Cartesia, and run it.
```bash theme={null}
git clone https://github.com/heygen-com/liveavatar-web-sdk.git
cd liveavatar-web-sdk
pnpm install
```
Set `API_KEY` in `apps/demo/app/api/secrets.ts`. The avatar, voice, and context IDs already point at a working demo persona — swap them for your own once the session runs.
```typescript theme={null}
export const API_KEY = "your-liveavatar-api-key";
export const API_URL = "https://api.liveavatar.com";
// Defaults ship with the demo. Replace with IDs from your own space:
// https://docs.liveavatar.com/docs/full-mode/configuration
export const AVATAR_ID = "dd73ea75-1218-4ef3-92ce-606d5f7fbc0a";
export const VOICE_ID = "c2527536-6d1f-4412-a643-53a3497dada9";
export const CONTEXT_ID = "5b9dba8a-aa31-11f0-a6ee-066a7fa2e369";
export const LANGUAGE = "en";
// Sandbox sessions don't consume credits: https://docs.liveavatar.com/docs/sandbox-mode
export const IS_SANDBOX = true;
```
In `apps/demo/app/api/start-session/route.ts`, add a `voice_settings` block inside the existing `avatar_persona` object in the session token request. The `provider` field selects which TTS engine renders the voice:
```typescript theme={null}
const res = await fetch(`${API_URL}/v1/sessions/token`, {
method: "POST",
headers: {
"X-API-KEY": API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
mode: "FULL",
avatar_id: AVATAR_ID,
avatar_persona: {
voice_id: VOICE_ID,
context_id: CONTEXT_ID,
language: LANGUAGE,
voice_settings: { // <------- Add this block
provider: "cartesia",
model: "sonic-3.5",
speed: 1.0,
},
},
is_sandbox: IS_SANDBOX,
}),
});
```
The route returns `{ session_token, session_id }`, which the demo passes to `LiveAvatarSession` from `@heygen/liveavatar-web-sdk`.
```bash theme={null}
pnpm build
pnpm demo
```
Open [http://localhost:3001](http://localhost:3001), click **Full Mode**, then unmute and talk. The avatar answers in the Sonic voice that is the default voice ID in `secrets.ts`.
The voice ID in `secrets.ts` refers to the ID provided by LiveAvatar. It corresponds to the `provider_voice_id`, which is the voice ID provided by Cartesia. The two IDs are not the same, but they refer to the same voice.
## Use your own Cartesia voices
Register your Cartesia API key as a LiveAvatar [secret](https://docs.liveavatar.com/docs/core-concepts/secrets), then bind a Cartesia voice to it — full flow in [Custom TTS Integration](https://docs.liveavatar.com/docs/full-mode/custom-tts). Get `provider_voice_id` from the [Cartesia playground](https://play.cartesia.ai/voices) or the [list voices endpoint](/api-reference/voices/list).
Set the environment variables used in the requests:
```bash theme={null}
export LIVEAVATAR_API_KEY="your-liveavatar-api-key"
export CARTESIA_API_KEY="your-cartesia-api-key"
```
```bash theme={null}
curl -X POST https://api.liveavatar.com/v1/secrets \
-H "X-API-KEY: $LIVEAVATAR_API_KEY" \
-H "content-type: application/json" \
-d '{
"secret_type": "CARTESIA_API_KEY",
"secret_value": "'"$CARTESIA_API_KEY"'",
"secret_name": "My Cartesia Key"
}'
```
The returned JSON contains a secret `id`:
```json theme={null}
{"code":1000,"data":{"id":"XXXXXXXX-0239-4180-9acd-XXXXXXXXXXX","secret_name":"My Cartesia Key"},"message":"Secret created successfully"}
```
Pass it with the Cartesia voice ID to create a LiveAvatar voice:
```bash theme={null}
curl -X POST https://api.liveavatar.com/v1/voices/third_party \
-H "X-API-KEY: $LIVEAVATAR_API_KEY" \
-H "content-type: application/json" \
-d '{
"secret_id": "",
"provider_voice_id": "",
"name": "My Cartesia Voice"
}'
```
The response returns a LiveAvatar `voice_id` (different from the Cartesia Voice ID you supplied). Use it as `VOICE_ID` in `secrets.ts`. LiveAvatar generates that session's audio with your Cartesia credentials.
The imported voice stops working if the underlying Cartesia voice is deleted or the secret is removed.
## Configuration
`avatar_persona.voice_settings` fields for Cartesia:
| Parameter | Type | Default | Description |
| ---------- | -------- | ------------- | ------------------------------------------------------- |
| `provider` | `string` | — | Set to `cartesia` to render the voice with Cartesia |
| `model` | `string` | `"sonic-3.5"` | One of `sonic-3.5`, `sonic-3`, `sonic-2`, `sonic-turbo` |
| `speed` | `number` | `1` | Speaking speed, `0.6`–`1.5` |
## Resources
* [LiveAvatar voice settings](https://docs.liveavatar.com/docs/full-mode/voice-settings)
* [LiveAvatar custom TTS integration](https://docs.liveavatar.com/docs/full-mode/custom-tts)
* [LiveAvatar create session token API](https://docs.liveavatar.com/api-reference/sessions/create-session-token)
* [LiveAvatar Web SDK](https://github.com/heygen-com/liveavatar-web-sdk)
* [Cartesia Sonic 3.5](/build-with-cartesia/tts-models/latest)
* [Cartesia volume, speed, and emotion controls](/build-with-cartesia/capability-guides/volume-speed-emotion)