LiveAvatar + Cartesia - Cartesia Docs

Last verified: 2026-08-05

Overview

Use this integration to speak a LiveAvatar avatar’s responses with a Cartesia Sonic TTS voice. Set provider to cartesia in the session’s voice settings to render the avatar with Sonic — see Use your own Cartesia voices to import your own API key and voices.

Prerequisites

LiveAvatar API key from app.liveavatar.com/developers
Node.js 22+ and pnpm 9+
Cartesia API key (sk_car_...) from Cartesia keys — only for importing your own Cartesia voices

Quick start

The LiveAvatar Web SDK repo ships a Next.js demo app. Point it at your space, switch the TTS provider to Cartesia, and run it.

Clone the SDK repo and install

git clone https://github.com/heygen-com/liveavatar-web-sdk.git
cd liveavatar-web-sdk
pnpm install

Add your LiveAvatar API key

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.

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;

Set Cartesia as the TTS provider

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:

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.

Run the demo

pnpm build
pnpm demo

Open 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, then bind a Cartesia voice to it — full flow in Custom TTS Integration. Get provider_voice_id from the Cartesia playground or the list voices endpoint. Set the environment variables used in the requests:

export LIVEAVATAR_API_KEY="your-liveavatar-api-key"
export CARTESIA_API_KEY="your-cartesia-api-key"

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:

{"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:

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": "<secret_id>",
    "provider_voice_id": "<cartesia_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`

​Overview

​Prerequisites

​Quick start

Clone the SDK repo and install

Add your LiveAvatar API key

Set Cartesia as the TTS provider

Run the demo

​Use your own Cartesia voices

​Configuration

​Resources

Overview

Prerequisites

Quick start

Use your own Cartesia voices

Configuration

Resources