npm install realtime-avatar
Entry points
Pick the import for your context — the default entry is runtime-free and
edge-safe, and secret handling is isolated so it never reaches the browser.
| Import | Use from | Contains |
|---|
realtime-avatar | browser or server | RealtimeAvatarClient, AvatarSession, readAvatarMux, types |
realtime-avatar/browser | browser | AvatarPlayer (canvas + WebAudio playback) |
realtime-avatar/react | browser | useAvatarSession, AvatarStage |
realtime-avatar/server | backend only | API-key hashing/verification (secret pepper) |
Client modes
import { RealtimeAvatarClient } from "realtime-avatar";
// Backend with a trusted key. Defaults to https://realtimeavatar.ai:
const server = RealtimeAvatarClient.platform({ apiKey });
// Browser via your same-origin proxy (no key in the client):
const web = RealtimeAvatarClient.webProxy();
// Directly against a Modal deployment:
const modal = RealtimeAvatarClient.modal({ baseUrl, apiKey });
Core methods
| Method | Purpose |
|---|
prepare(input) | Warm/register an avatar before turns. |
turn(input) | Stream a realtime turn (application/x-avatar-mux). |
lipsync({ audioUrl, avatarId | portraitUrl }) | Render audio → MP4 URL (non-streaming). |
chat(...) / speak(...) | Sugar over turn for persona reply / verbatim TTS. |
session(config) | Reusable session bound to one avatar. |
createImageAvatar / createVideoAvatarFromUrl | Create avatars. |
listAvatars / getAvatar / updateAvatar / deleteAvatar | Manage avatars. |
creditBalance() | Read the wallet balance. |
pipecatTurn() is a deprecated alias for turn() and will be removed in a future
release.
Streaming protocol
turn() returns a RealtimeTurnStream. Decode events with readAvatarMux, or
play them with AvatarPlayer — see Web playback.
Type safety
Request/response types are generated from the platform OpenAPI spec (the single
source of truth) and JSON responses are runtime-validated at the boundary, so a
drifted backend is caught instead of silently mis-typed.