Docs

Add a Live AI Avatar to a v0 App (Next.js Prompt)

A copy-paste prompt that adds a live AI avatar video call to a v0 Next.js app: one route handler holds the API key from the Vars panel, and a client component renders the call.

v0 generates Next.js App Router apps, where the SDK's server route is one file. This prompt makes v0 add that route and a page with a Call Rin button that opens a two-way voice and video call with a talking character, rendered by the AvatarCall component from the realtime-avatar SDK.

It uses the public example avatar seed-rin-ashfall, so the first call works on a fresh key before you have created a character of your own.

1. Get an API key

Try it free. Create a free account, then create a key in Settings, API keys. The free Sandbox plan includes 8 realtime minutes, once per account, and the prompts here cap every call at 120 seconds.

2. Paste the prompt into v0

  1. Paste the prompt below into a new or existing v0 chat. There is no one-click link for it: v0's Open in v0 button opens content from a URL or a code snippet and takes at most 500 characters of prompt, and this prompt is longer.
  2. Add REALTIME_AVATAR_API_KEY in the Vars panel (or Project settings, Environment Variables). The preview reads the Development value.
  3. Press Call Rin in the preview and allow the microphone.
Add a live AI avatar video call to this app with the Realtime Avatar SDK.

Packages: realtime-avatar (pin exactly 0.26.0), livekit-client, @livekit/components-react, zod.

Rules, do not break them:
1. The API key is a server secret named REALTIME_AVATAR_API_KEY. Never put it in browser code and never in a VITE_ or NEXT_PUBLIC_ variable. Ask me for it as a secret.
2. The browser never calls Realtime Avatar directly. It calls ONE server route of ours that holds the key. The SDK ships that route; it answers POST <base>/connect and POST <base>/end and relays the platform's answer unchanged. Do not wrap or reshape what it returns.
3. The server decides the call: instructions, maxSeconds and which avatar ids are allowed. Ignore anything the browser sends for those.
4. Use the public example avatar "seed-rin-ashfall" and allow only that id for now.
Reference: https://realtimeavatar.ai/llms.txt and https://realtimeavatar.ai/docs/quickstart.md

This is a Next.js App Router project.

Server: create 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 ?? "",
      authorize: ({ operation }) =>
        operation === "connect" || operation === "end" ? undefined : new Response("Not found", { status: 404 }),
      session: ({ avatarId }) =>
        avatarId === "seed-rin-ashfall"
          ? { instructions: "You are Rin, a warm, curious guide. Short spoken sentences, one question at a time.", maxSeconds: 120 }
          : new Response("Avatar not allowed", { status: 403 }),
    });

The [...path] catch-all matters: one file answers /connect and /end.
Read REALTIME_AVATAR_API_KEY from the environment (set in the Vars panel). Never NEXT_PUBLIC_.

Client: a page with a "Call Rin" button. Clicking it mounts the call component below (put it in a "use client" component and load that with next/dynamic and ssr: false). When the call ends, show the button again.

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

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

    <AvatarCall
      client={client}
      avatarId="seed-rin-ashfall"
      poster="https://realtimeavatar.ai/api/assets/public/characters/rin-ashfall/portrait.png"
      idleVideoUrl="https://realtimeavatar.ai/api/assets/public/characters/rin-ashfall/idle-10s.mp4"
      style={{ width: "100%", maxWidth: 420, aspectRatio: "3 / 4" }}
      onEnded={() => setInCall(false)}
    >
      {(call) => (
        <div style={{ position: "absolute", bottom: 16, left: 0, right: 0, textAlign: "center" }}>
          {call.status === "waiting" ? <p>In line: {call.queuePosition}</p> : null}
          <button onClick={call.end}>End call</button>
        </div>
      )}
    </AvatarCall>

The microphone only works on https or http://localhost.

Where the API key goes

In the Vars panel, as REALTIME_AVATAR_API_KEY. The route handler reads it from the server environment on each request, and the browser receives only a session grant for one call. Never name it NEXT_PUBLIC_: Next.js inlines those variables into browser code.

Before your first call, check two things in what v0 wrote:

  • The key is read only in the route handler, never in a component and never through a NEXT_PUBLIC_ variable.
  • The route returns the SDK's answer as it is. The browser SDK validates the session grant strictly, so a route that wraps or reshapes it produces a call that never connects.

What the prompt builds

  • Server: app/api/realtime-avatar/[...path]/route.ts, exporting GET and POST from createRealtimeAvatarRoute (realtime-avatar/nextjs). The [...path] catch-all lets one file answer both /connect and /end. See Next.js for the adapter.
  • Client: a "use client" component loaded with next/dynamic and ssr: false, so the call mounts in the browser only.

For a complete local Next.js app instead, download the Next.js starter. The Vite starter repo is not a Next.js app, so it is a reference for the server half rather than something to open in v0.

What works and what has not been tested

  • Checked on 2026-11-15: the SDK version the prompt pins, realtime-avatar 0.26.0, exports every function the prompt names (createRealtimeAvatarRoute, AvatarCall and createProxyClient).
  • Not covered by that check: a run of this prompt inside v0. v0 writes its own code from the prompt, so the result can differ from run to run; the two checks under Where the API key goes catch the mistakes that leak the key or break the call.

As generated, anyone who can open the app can start a call, and every call spends your balance. Before going public, ask the builder to require a signed-in user in the route's authorize hook (return a 401 when there is none), and set maxSeconds to what you will pay for per call. See Authentication for what authorize gates, and pricing for what a minute costs.

Your own character

Create an avatar from one portrait on the Avatars page, then ask v0 to replace seed-rin-ashfall with its ava_… id in both the allowlist and the page, and to drop the poster and idleVideoUrl, which belong to the example avatar.

Other builders

Compare and cost guides