Skip to main content

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.

Community integration by Avaturn. Last verified: 2026-05-26.

​
Overview

Use this integration to run a deployed Cartesia Line agent behind an Avaturn avatar. Your Cartesia agent handles prompts, tools, voice, and LLM behavior, while Avaturn handles the avatar session and rendering.

​
Prerequisites

  • Cartesia Line agent deployed with an agent_id (quickstart)
  • Cartesia API key (CARTESIA_API_KEY) from Cartesia keys
  • Avaturn API key (AVATURN_API_KEY) from the Avaturn dashboard
  • Node.js 18+ for the backend token/session endpoint
  • A frontend app that can render Avaturn Web SDK (integration guide)

​
Installation

npm install express @avaturn-live/web-sdk
Set your Node project to ESM so the backend and frontend snippets work as written (import syntax and top-level await): 
{
  "type": "module"
}

​
Quick start

Create a Cartesia access token with the Auth API, create an Avaturn session with the Cartesia engine, then initialize the avatar in the browser with the returned session token.

​
1) Backend: mint Cartesia token and create Avaturn session

import express from "express";

const app = express();
app.use(express.json());

app.post("/api/avaturn-session", async (req, res) => {
  const { cartesiaAgentId } = req.body;
  if (!cartesiaAgentId) {
    return res.status(400).json({ error: "cartesiaAgentId is required" });
  }

  const cartesiaTokenResponse = await fetch("https://api.cartesia.ai/access-token", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CARTESIA_API_KEY}`,
      "Cartesia-Version": "2025-04-16",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      grants: { agent: true },
      expires_in: 300,
    }),
  });

  if (!cartesiaTokenResponse.ok) {
    return res.status(502).json({ error: "Failed to mint Cartesia access token" });
  }

  const { token: cartesiaAccessToken } = await cartesiaTokenResponse.json();

  const avaturnSessionResponse = await fetch("https://api.avaturn.live/api/v1/sessions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.AVATURN_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      conversation_engine: {
        type: "cartesia",
        access_token: cartesiaAccessToken,
        agent_id: cartesiaAgentId,
      },
    }),
  });

  if (!avaturnSessionResponse.ok) {
    return res.status(502).json({ error: "Failed to create Avaturn session" });
  }

  const session = await avaturnSessionResponse.json();
  return res.json(session); // { session_id, token }
});

app.listen(3000);

​
2) Frontend: initialize Avaturn with session token

Add a container in your page HTML where AvaturnHead renders the video stream: 
<div id="avaturn-video"></div>
The sample below uses top-level await and requires an ES module entry file. Wrap the call in an async function if your frontend is not a module. 
import { AvaturnHead } from "@avaturn-live/web-sdk";

async function startAvatar(cartesiaAgentId: string) {
  const response = await fetch("/api/avaturn-session", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ cartesiaAgentId }),
  });

  if (!response.ok) {
    throw new Error("Failed to create avatar session");
  }

  const session = await response.json(); // { session_id, token }
  const root = document.querySelector<HTMLDivElement>("#avaturn-video");

  if (!root) {
    throw new Error("Missing #avaturn-video container");
  }

  const avatar = new AvaturnHead(root, {
    sessionToken: session.token,
    audioSource: true, // required for voice conversation
  });

  await avatar.init();
  return avatar;
}

const cartesiaAgentId = "your-cartesia-agent-id";
await startAvatar(cartesiaAgentId);

​
Resources