Quickstart

This guide uses direct mode: Talking Avatar streams the avatar’s video and your agent’s voice to your page over WebRTC. Already using LiveKit? See LiveKit instead.

Before you start

A Talking Avatar account. Sign up to get $1 of free credits.
Node.js 22 or later on your server (or Node.js 18 or 20 with the ws package). Another language? Use the realtime avatar API instead.
A voice: any TTS or voice agent that gives you raw 16-bit PCM audio. See Stream audio for provider settings.

Steps

Create an API key

In the dashboard, open API keys → Create key. Copy the key and set it on your server:

.env

TALKING_AVATAR_API_KEY=tav_…

Install the SDK

In your server and in your web app:

npm install @interviewflowai/talking-avatar

Pick an avatar

Choose an avatar ID from Avatars, such as ava4 (professional, office) or ava6 (casual, home study). You can try each one live on the dashboard’s Avatars page.

Start the avatar and add one route

server.js

import express from "express";
import { LiveAvatar } from "@interviewflowai/talking-avatar/server";

// 1. Start the avatar: we stream its video and your agent's voice over WebRTC.
const avatar = await LiveAvatar.start({
  apiKey: process.env.TALKING_AVATAR_API_KEY, // tav_…
  avatar: "ava4",
  sampleRate: 24000,                          // your TTS audio's sample rate
});

// 2. One route for your page: the WebRTC offer, then the browser's answer.
const app = express().use(express.json());
app.post("/avatar", async (req, res) => {
  try { res.json(await avatar.handleView(req.body)); }
  catch (error) { res.status(503).json({ error: error.message }); }
});
app.listen(3000);

// 3. Your TTS audio as it streams (PCM16 mono: Int16Array, Buffer or base64).
tts.on("audio", (pcm) => avatar.pushAudio(pcm));

// The user interrupts: drop what wasn't heard yet.
const heardMs = await avatar.clear();

avatar.on("speechEnded", (playedMs) => {});
avatar.on("close", (code, reason) => {}); // 4002: out of credits
// avatar.close() when the conversation is over: billing stops.

handleView answers your page’s WebRTC requests. One route serves any number of viewers, and your API key never reaches the browser.

Show it on your page

index.html

<div id="avatar" style="width: 640px; aspect-ratio: 16 / 9"></div>
<button id="watch">Start</button>

page.js

import { LiveAvatarView } from "@interviewflowai/talking-avatar/live";

// Plays the avatar's video and voice, fitted in the element, and reconnects by itself.
const view = new LiveAvatarView({
  container: document.getElementById("avatar"),
  endpoint: "/avatar",                       // the route on your server
  onStatus: (status) => console.log(status), // connecting, live, reconnecting…
});

// From a click, so the browser lets the voice play.
document.getElementById("watch").onclick = () => view.connect();

Talk to it

Click Start, then make your agent speak. The avatar plays the voice in sync with its lips.

Play the voice once. The avatar plays your agent’s voice itself, in sync with its lips. Remove any other playback of the same audio (an <audio> element, a speaker stream, track.attach()), or users hear it twice.

One avatar per conversation

Keep one LiveAvatar per conversation: start it when the conversation starts, and close() it when it ends, so billing stops. Running several conversations at once? Give each its own route, such as /avatar/:conversationId, that looks up that conversation’s avatar.

const avatars = new Map(); // conversationId → LiveAvatar

app.post("/avatar/:id", async (req, res) => {
  const avatar = avatars.get(req.params.id);
  if (!avatar) return res.status(404).json({ error: "No such conversation" });
  try { res.json(await avatar.handleView(req.body)); }
  catch (error) { res.status(503).json({ error: error.message }); }
});

Protect the route with your app’s existing authentication.

Next steps

Stream audio

Audio formats and settings for OpenAI, ElevenLabs, Azure and Cartesia.

Interruptions

Barge-in, speech events and keeping your transcript accurate.

Sessions and errors

Billing, limits and close codes.

Production checklist

Before you go live.

Get started

Your account

Voice Agents (no code)

Realistic Avatars (API)

Open Source (3D, free)

Help

Before you start

Steps

One avatar per conversation

Next steps

Stream audio

Interruptions

Sessions and errors

Production checklist

​Before you start

​Steps

​One avatar per conversation

​Next steps

Stream audio

Interruptions

Sessions and errors

Production checklist

Before you start

Steps

One avatar per conversation

Next steps