> ## 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.
# Avaturn + Cartesia Line
> Connect an Avaturn avatar session to a deployed Cartesia Line agent for voice conversations.
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
```bash theme={null}
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`):
```json theme={null}
{
"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
```javascript theme={null}
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:
```html theme={null}
```
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.
```typescript theme={null}
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("#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
* Avaturn Cartesia integration guide
* Cartesia Line quickstart
* Cartesia authentication guide
* Avaturn Web SDK integration guide