Sessions and errors

A session is one avatar, live, from LiveAvatar.start() until it closes.

Lifecycle

Start

LiveAvatar.start() checks your API key, your balance and your monthly spending limit, then resolves once the avatar is live. Billing starts here.

Live

You push audio and the avatar speaks it. Running sessions are checked every 30 seconds.

End

You call close(), your server disconnects, or the session is stopped (see the close codes below). Billing stops, and the close event reports why.

Billing

$0.02 per minute, billed per second, from the moment the avatar is live until the session ends.
A session needs a balance of at least $0.02 (one minute) to start.
Each session’s duration, rate and cost appear on the Usage page.

Always close() a session when the conversation ends, the user leaves, or anything fails. A session you forget keeps billing until it reaches its 3-hour limit.

Limits


Session length	Up to 3 hours each
Sessions at once	As many as you need
Viewers per session	Any number (direct mode)

Close codes

LiveAvatar.start() rejects with a LiveAvatarError when a session can’t start, and the close event reports why a session ended. Both carry the same code.

Code	Meaning	What to do
`1000`	You closed the session	Nothing: it’s the normal end
`4001`	Invalid or missing API key	Check `TALKING_AVATAR_API_KEY`. The key may have been revoked.
`4002`	Out of credits (below a minute’s worth at the start, or used up during the session), or the monthly spending limit is reached	Add credits, turn on auto top-up, or raise the limit on Billing
`4003`	The session reached its 3-hour limit	Start a new session
`1011`	The avatar’s stream was lost and couldn’t recover	Start a new session

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

try {
  const avatar = await LiveAvatar.start({ apiKey, avatar: "ava4" });
  avatar.on("close", (code, reason) => {
    if (code === 4002) notifyOps("Talking Avatar: add credits");
  });
} catch (error) {
  if (error instanceof LiveAvatarError && error.code === 4002) {
    showMessage("The avatar is unavailable right now."); // keep the voice agent running
  } else {
    throw error;
  }
}

Never let an avatar failure crash your voice agent. If a session can’t start, carry on with voice only, and show a clear message.

Network drops

If the connection drops, the stream recovers by itself. Your server’s LiveAvatar emits republished when it has recovered, and LiveAvatarView reconnects on its own (its status goes to reconnecting, then back to live).

The watermark

Unless your account has the Remove watermark plan, the video shows a small Powered by Talking Avatar in its bottom-right corner.

Get started

Your account

Voice Agents (no code)

Realistic Avatars (API)

Open Source (3D, free)

Help

Lifecycle

Billing

Limits

Close codes

Network drops

The watermark

​Lifecycle

​Billing

​Limits

​Close codes

​Network drops

​The watermark

Lifecycle

Billing

Limits

Close codes

Network drops

The watermark