LiveAvatar + Cartesia Line

Last verified: 2026-08-05

Overview

Use this integration to put a streaming LiveAvatar avatar in front of a deployed Cartesia Line agent. Your Line agent owns the prompt, tools, voice, and turn-taking; LiveAvatar’s Cartesia Agent Connector runs the bridge and renders lip-synced video from the agent’s audio. You pass an agent_id and a stored Cartesia API key when creating the session — no audio pipeline of your own.

Prerequisites

Cartesia Line agent deployed with an agent_id (Line quickstart, agents listed at play.cartesia.ai/agents)
Cartesia API key (sk_car_...) from Cartesia keys
LiveAvatar API key from app.liveavatar.com/developers
Node.js 22+ and pnpm 9+

Quick start

The LiveAvatar Web SDK repo ships a Next.js demo app with a LITE Mode session route. Add your Cartesia agent config to that route and run it.

Store your Cartesia API key with LiveAvatar

LiveAvatar keeps the key by reference, so session requests carry a secret_id instead of the key itself.Set the environment variables used in the request:

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": "Cartesia Agent Key"
  }'

The response returns an id. Use it as secret_id in the next step.

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 demo ships with a working AVATAR_ID — swap it for one of your own avatars later.

export const API_KEY = "your-liveavatar-api-key";
export const API_URL = "https://api.liveavatar.com";
export const AVATAR_ID = "dd73ea75-1218-4ef3-92ce-606d5f7fbc0a";

// Sandbox sessions don't consume credits: https://docs.liveavatar.com/docs/sandbox-mode
export const IS_SANDBOX = true;

Point the LITE session at your Line agent

Add cartesia_agent_config to the session token request in apps/demo/app/api/start-lite-session/route.ts:

import { API_KEY, API_URL, AVATAR_ID, IS_SANDBOX } from "../secrets";

const CARTESIA_SECRET_ID = "your-liveavatar-secret-id";
const CARTESIA_AGENT_ID = "your-cartesia-agent-id";

export async function POST() {
  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: "LITE",
      avatar_id: AVATAR_ID,
      is_sandbox: IS_SANDBOX,
      cartesia_agent_config: {
        secret_id: CARTESIA_SECRET_ID,
        agent_id: CARTESIA_AGENT_ID,
      },
    }),
  });

  if (!res.ok) {
    return new Response(
      JSON.stringify({ error: "Failed to retrieve session token" }),
      { status: res.status },
    );
  }

  const { data } = await res.json();
  return new Response(
    JSON.stringify({
      session_token: data.session_token,
      session_id: data.session_id,
    }),
    { status: 200, headers: { "Content-Type": "application/json" } },
  );
}

Both secret_id and agent_id are required. LiveAvatar provisions a LiveKit room and dispatches a worker that talks to your Line agent.

Run the demo

pnpm build
pnpm demo

Open http://localhost:3001, click Lite Mode, then unmute and speak. Your Line agent answers and the avatar lip-syncs to its audio.

Session events

Cartesia connector sessions use LiveAvatar’s FULL Mode event system over the LiveKit data channel, not LITE Mode WebSocket events. LiveAvatarSession emits them as typed events. Run this in an ES module (for example, a "use client" module in the demo app) or wrap the body in an async function — the snippet uses top-level await.

import {
  AgentEventsEnum,
  LiveAvatarSession,
} from "@heygen/liveavatar-web-sdk";

// sessionToken from the start-lite-session route response
const session = new LiveAvatarSession(sessionToken, { voiceChat: true });

session.on(AgentEventsEnum.USER_TRANSCRIPTION, ({ text }) => {
  console.log("user:", text);
});

session.on(AgentEventsEnum.AVATAR_TRANSCRIPTION, ({ text }) => {
  console.log("agent:", text);
});

// Fires with stop_reason "AGENT_HANG_UP" when the Line agent ends the call.
session.on(AgentEventsEnum.SESSION_STOPPED, ({ stop_reason }) => {
  console.log("session stopped:", stop_reason);
});

await session.start();

Configuration

cartesia_agent_config fields on the create session token request:

Parameter	Type	Default	Description
`secret_id`	`string`	—	LiveAvatar secret holding your `CARTESIA_API_KEY`
`agent_id`	`string`	—	Cartesia Line agent to connect to

Your Line agent owns its voice, prompt, and language, so LiveAvatar takes no per-session overrides for them. To keep the config server-side, save it once as a stored voice agent of type cartesia_agent and reference it by id instead — see the connector docs for that payload.

​Overview

​Prerequisites

​Quick start

Store your Cartesia API key with LiveAvatar

Clone the SDK repo and install

Add your LiveAvatar API key

Point the LITE session at your Line agent

Run the demo

​Session events

​Configuration

​Resources

Overview

Prerequisites

Quick start

Session events

Configuration

Resources