Quickstart

npm install realtime-avatar

Self-contained: the contracts package is bundled into the build, so there is no private dependency to resolve. Pin an exact version for reproducible CI.

pip install httpx

There is no Python SDK — the live call is rendered by a browser or native client, so Python's half is plain HTTP and one dependency.

// app/api/realtime-avatar/[...path]/route.ts
import { createRealtimeAvatarRoute } from "realtime-avatar/nextjs";

export const { GET, POST } = createRealtimeAvatarRoute({
  apiKey: process.env.REALTIME_AVATAR_API_KEY!,

  // Who may do this. "connect" is the only operation that costs money to start,
  // so that is where the wallet check belongs; the reads stay cheap.
  authorize: async ({ request, operation }) => {
    const user = await currentUser(request);
    if (!user) return new Response("Unauthorized", { status: 401 });
    if (operation === "connect" && !(await hasCredits(user))) {
      return Response.json({ code: "insufficient_credits" }, { status: 402 });
    }
  },

  // What the character knows for THIS call. Whatever the browser sent for these
  // concerns is discarded — this callback is the only source.
  session: async ({ request, avatarId, mode }) => {
    const user = await currentUser(request);
    const character = await db.character(avatarId);
    return {
      instructions: character.prompt,
      context: await db.recentTurns(user.id, avatarId),
      maxSeconds: secondsTheBalanceAffords(user, mode),
    };
  },
});

The catch-all segment matters — the route answers four paths under one prefix (POST /connect, POST /end, GET /avatars, GET /credits), so a single [...path] segment serves all of them.

// src/routes/api/realtime-avatar/$.ts
import { createFileRoute } from "@tanstack/react-router";
import { realtimeAvatarServerRoute } from "realtime-avatar/tanstack-start";

const handlers = realtimeAvatarServerRoute({
  apiKey: process.env.REALTIME_AVATAR_API_KEY!,
  authorize: async ({ request, operation }) => {
    const user = await requireUser(request);
    if (!user) return new Response("Unauthorized", { status: 401 });
    if (operation === "connect" && !(await hasCredits(user))) {
      return Response.json({ code: "insufficient_credits" }, { status: 402 });
    }
  },
  session: async ({ request, avatarId, mode }) => {
    const user = await requireUser(request);
    const character = await loadCharacter(avatarId);
    return {
      instructions: buildPrompt(character),
      context: await loadRecentTurns(user.id, avatarId),
      maxSeconds: secondsTheBalanceAffords(user, mode),
    };
  },
});

export const Route = createFileRoute("/api/realtime-avatar/$")({
  server: { handlers },
});

The trailing $ is Start's splat segment — without it the handler only ever sees the mount path and answers 404. Build the handlers once at module scope. On Cloudflare Workers pass a factory — apiKey: () => getEnv().KEY — since there is no process.env.

# Your backend decides; the browser renders. Same split, no SDK needed.
import os, httpx
from fastapi import Depends, FastAPI
from fastapi.responses import JSONResponse
from pydantic import BaseModel

BASE = "https://realtimeavatar.ai/api/v1"
client = httpx.Client(base_url=BASE, timeout=30.0, headers={
    "Authorization": f"Bearer {os.environ['REALTIME_AVATAR_API_KEY']}"})

app = FastAPI()


class StartCallRequest(BaseModel):
    avatar_id: str
    mode: str = "avatar"                          # "avatar" | "voice"
    queue_ticket_id: str | None = None            # a client retrying after a 429 hands its ticket back


@app.post("/api/calls")
def start_call(req: StartCallRequest, user=Depends(current_user)):
    if not has_credits(user):
        return JSONResponse({"code": "insufficient_credits"}, 402)

    character = load_character(req.avatar_id)
    seconds = int(seconds_the_balance_affords(user, req.mode))   # wire: int, 1..1800
    body = {
        "avatar_id": character.avatar_id,
        "mode": req.mode,
        "stt_mode": "server",
        # Decided HERE. The client sends none of this.
        "instructions": build_prompt(character),
        # ≤32 of exactly {"role": "system" | "user" | "assistant", "content": 1..4000 chars} —
        # strict: any other key is a 422
        "initial_context": [{"role": t.role, "content": t.text}
                            for t in recent_turns(user.id, character.avatar_id)][-32:],
        "max_session_seconds": max(1, min(seconds, 1800)),
        # Optional: a signed POST of the transcript when the call ends (receiver: Tool calling).
        "transcript_webhook": {"url": "https://your.app/api/rta/transcript",   # https only
                               "secret": os.environ["TRANSCRIPT_SECRET"]},     # 16..200 chars
        "client_metadata": {"user_id": str(user.id),                           # ≤16 string pairs,
                            "character_id": character.avatar_id},              # echoed back to you
    }
    if req.queue_ticket_id:
        body["queue_ticket_id"] = req.queue_ticket_id

    r = client.post("/realtime/livekit/session", json=body)
    data = r.json()
    if r.status_code == 429 and "queue_ticket_id" in data:
        # Every slot busy — the queue, not an error. Relay it VERBATIM: the busy body
        # carries queue_ticket_id (the only handle that RELEASES the slot when the
        # caller gives up) and recommended_retry_ms (when to come back). The client
        # retries WITH the ticket; reshaping this strands it for its whole TTL.
        return JSONResponse(data, 429)
    if not r.is_success:
        # 402 / 409 / 422 — and the 429s that are NOT the queue (plan concurrency
        # ceiling, rate limit). Forward {error, code?}, but not at 429: an SDK
        # client reads every 429 as the queue.
        return JSONResponse(data, 503 if r.status_code == 429 else r.status_code)
    return data                                   # return this VERBATIM

Two rules when hand-rolling. First, casing is per endpoint, and every endpoint is strict — an unknown or mis-cased key is a rejected call. The two realtime routes shown here (/realtime/livekit/session and its /release) are snake_case; every REST resource endpoint — avatars, clips, keys, assets — is camelCase. Measured against the published spec: 2 of the 9 request bodies are snake_case at the top level and the other 7 are camelCase — except POST /avatars, which is camelCase outside and snake_case inside voice (auto_description, voice_id), as the sample above shows. And the SDK's policy names are not the wire names: context is initial_context, maxSeconds is max_session_seconds, transcript is transcript_webhook, metadata is client_metadata. Second, if your client uses this SDK the response must reach it byte-for-byte — the SDK hands the body to the room unvalidated, so a wrapped grant never connects: the token and URL read as undefined and the call sits in connecting with no error. A client driving the room directly reads only the fields it needs and tolerates extras, but relaying verbatim keeps both paths working. The same goes for a busy 429: it is the queue only when the body carries queue_ticket_id, and a retry that does not present that ticket mints a fresh one every poll — its position never advances.

import { AvatarCall, createProxyClient } from "realtime-avatar/react";

const client = createProxyClient({ proxyUrl: "/api/realtime-avatar" });

export function Call({ avatarId }: { avatarId: string }) {
  return (
    <AvatarCall
      client={client}
      avatarId={avatarId}
      idleVideoUrl="https://realtimeavatar.ai/api/assets/public/characters/rin-ashfall/idle-10s.mp4"
      poster="https://realtimeavatar.ai/api/assets/public/characters/rin-ashfall/portrait.png"
      onEnded={({ reason }) => showEndScreen(reason)}
    >
      {(call) =>
        call.status === "waiting" ? <Banner>In line: {call.queuePosition}</Banner> : null
      }
    </AvatarCall>
  );
}

Live media needs the DOM. In Next.js mark the file "use client" and import it with { ssr: false }; in TanStack Start gate it on a mounted flag or load it lazily.

import {
  AvatarVideoSurface,
  RealtimeAvatarLiveKitRoom,
  SessionLifecycleRoomBridge,
  createProxyClient,
  registerGlobals,
  useSessionLifecycle,
} from "realtime-avatar/react-native";

registerGlobals();                                  // once, at app startup

// Native has no page origin — the proxy URL must be ABSOLUTE.
const client = createProxyClient({
  proxyUrl: "https://your-app.example.com/api/realtime-avatar",
});

export function Call({ avatarId }: { avatarId: string }) {
  const lifecycle = useSessionLifecycle({ client, session: { avatarId } });
  if (!lifecycle.grant) return null;                // map lifecycle.phase to your UI

  return (
    <RealtimeAvatarLiveKitRoom
      grant={lifecycle.grant}
      onConnected={lifecycle.onConnected}
      onDisconnected={lifecycle.onDisconnected}
      onError={lifecycle.onConnectionError}
    >
      <SessionLifecycleRoomBridge lifecycle={lifecycle} />
      <AvatarVideoSurface
        idleVideoUrl={idleClipUrl}
        poster={posterUrl}
        // Native has no <video> — hand the idle clip to YOUR player, looped and muted.
        renderIdleVideo={({ url, style }) => <IdleClip url={url} style={style} />}
      />
    </RealtimeAvatarLiveKitRoom>
  );
}

Native is the lower-level surface today. <AvatarCall> is web-only — the session brain is the same module, but you compose the native room and video surface yourself, and you pick the video player (expo-video, react-native-video). Live media does not run in Expo Go; you need a dev client or an EAS build.

import { RealtimeAvatar } from "realtime-avatar";

const rta = new RealtimeAvatar({ apiKey: process.env.REALTIME_AVATAR_API_KEY! });

// Upload the portrait, then create the avatar from it.
const asset = await rta.uploadAsset(portraitBlob, { kind: "image", filename: "rin.png" });

const avatar = await rta.createAvatar({
  displayName: "Rin",
  sourceKind: "image",                    // one frontal portrait: jpeg/png/webp, up to 8MB
  sourceAssetId: asset.id,
  voice: { auto_description: "Warm, clear, mid-pitch — natural and conversational." },
});

console.log(avatar.id);      // ava_…
console.log(avatar.status);  // "preprocessing" — generation has started

import os, time, httpx

client = httpx.Client(
    base_url="https://realtimeavatar.ai/api/v1", timeout=60.0,
    headers={"Authorization": f"Bearer {os.environ['REALTIME_AVATAR_API_KEY']}"})

# Register the portrait, then create the avatar from it.
asset = client.post("/assets/remote", json={
    "kind": "image",
    "remoteUrl": "https://cdn.example.com/rin/portrait.png",
}).json()

avatar = client.post("/avatars", json={
    "displayName": "Rin",
    "sourceAssetId": asset["id"],
    "voice": {"auto_description": "Warm, clear, mid-pitch — natural and conversational."},
}).json()

print(avatar["id"])      # ava_…
print(avatar["status"])  # "preprocessing" — generation has started
                         # ("failed" + avatar["error"] if it could not be queued)

# Poll until the loop and clips have rendered — a minute or two.
while avatar["status"] == "preprocessing":
    time.sleep(15)
    avatar = client.get(f"/avatars/{avatar['id']}").json()
print(avatar["status"])  # "ready" — mint calls; "failed" — avatar["error"] says why