Docs

Add a Live AI Avatar to a Lovable App (Copy-Paste Prompt)

A copy-paste prompt, and a link that opens it in Lovable, that adds a live AI avatar video call to a Lovable app. The API key stays in a Lovable secret on the server; the page only renders the call.

This prompt makes Lovable add a live AI avatar to your app: a Call Rin button that opens a two-way voice and video call with a talking character, who listens while she speaks and stops when you interrupt. Lovable writes both halves. A server route holds your API key and starts the call, and the page renders it with 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. Open the prompt in Lovable

  1. Open the prompt in Lovable. The link fills Lovable's prompt box with the prompt below, and nothing is built until you press send. To add the call to an existing project, paste the prompt into that project's chat instead.
  2. When Lovable asks for REALTIME_AVATAR_API_KEY, paste your key into the secret form it shows, never into the chat. If it does not ask, ask it to add REALTIME_AVATAR_API_KEY as a secret. On a Lovable Cloud project you can also add it yourself: More, Cloud, Secrets, Add secret.
  3. Open the preview, press Call Rin, 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

How to build the server route depends on this project's stack. Check which one it is.

IF this project uses TanStack Start (new Lovable projects do):
Server: create the file src/routes/api/realtime-avatar/$.ts

    import { createFileRoute } from "@tanstack/react-router";
    import { realtimeAvatarServerRoute } from "realtime-avatar/tanstack-start";

    const handlers = realtimeAvatarServerRoute({
      // A factory, read per request. Read the secret the way this project reads other server secrets.
      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 }),
    });

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

The trailing $ in the filename matters: it is the splat that lets one file answer /connect and /end.

Client: a page with a "Call Rin" button. Clicking it mounts the call component below (render it only in the browser, after mount, never during server rendering). 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.

OTHERWISE (a React + Vite project with Lovable Cloud):
Server: a Supabase Edge Function named "realtime-avatar".

supabase/functions/realtime-avatar/index.ts:

    import { realtimeAvatarHono } from "npm:realtime-avatar@0.26.0/hono";

    const cors = {
      "Access-Control-Allow-Origin": "*",
      "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type",
      "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
    };

    const route = realtimeAvatarHono({
      apiKey: () => Deno.env.get("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 }),
    });

    Deno.serve(async (req) => {
      if (req.method === "OPTIONS") return new Response(null, { status: 204, headers: cors });
      const res = await route({ req: { raw: req } });
      const headers = new Headers(res.headers);
      for (const [k, v] of Object.entries(cors)) headers.set(k, v);
      return new Response(res.body, { status: res.status, headers });
    });

In supabase/config.toml add:

    [functions.realtime-avatar]
    verify_jwt = false

(The gateway's JWT check rejects the browser's CORS preflight; the function does its own checks.)
Store REALTIME_AVATAR_API_KEY as an Edge Function secret.

Client: a page with a "Call Rin" button. Clicking it mounts the call component below (it only runs in the browser). When the call ends, show the button again.

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

    const base = import.meta.env.VITE_SUPABASE_URL + "/functions/v1/realtime-avatar";
    const key = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY ?? import.meta.env.VITE_SUPABASE_ANON_KEY;
    const client = createProxyClient({
      proxyUrl: base,
      // Supabase's gateway wants the project's public key on every request.
      fetch: (input, init) => {
        const headers = new Headers(init?.headers);
        headers.set("apikey", key);
        headers.set("authorization", "Bearer " + key);
        return fetch(input, { ...init, headers });
      },
    });

    <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

Only on the server. The prompt names it REALTIME_AVATAR_API_KEY and has Lovable store it as a secret that server code reads. The browser never receives it: it gets a session grant for one call, which the route passes through unchanged.

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

  • No VITE_ variable holds the key. Vite ships every VITE_ variable to the browser, where anyone can read it and start calls on your balance.
  • 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

New Lovable projects use TanStack Start (Lovable's docs date the switch to May 13, 2026), and a TanStack Start project lists @tanstack/react-start in its package.json. Older projects are React and Vite with a Lovable Cloud backend. The prompt carries both versions and has Lovable check which one it is in:

  • TanStack Start: one server route file, src/routes/api/realtime-avatar/$.ts, built with realtimeAvatarServerRoute from realtime-avatar/tanstack-start. The trailing $ lets one file answer both /connect and /end. See TanStack Start for the adapter.
  • React and Vite on Lovable Cloud: a Supabase Edge Function named realtime-avatar, built with realtimeAvatarHono. JWT verification is turned off for that one function, because the gateway would otherwise reject the browser's CORS preflight; the function runs its own checks.

The page is the same in both: a Call Rin button that mounts AvatarCall in the browser only. Lovable does not redeploy an Edge Function from a commit synced from GitHub, so ask it in chat to deploy the function after you change it.

The starter repo

realtime-avatar-starter-vite (MIT) is the React and Vite shape Lovable generates, with the same Edge Function the prompt asks for in supabase/functions/realtime-avatar/index.ts. Use it as the reference for what Lovable should produce. Lovable cannot link an existing GitHub repo; it can import a ZIP of one (Import project, then Upload code), but that path has not been tested with this starter.

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 (realtimeAvatarServerRoute, realtimeAvatarHono, AvatarCall and createProxyClient).
  • Checked on 2026-10-05: the starter's Edge Function, the code the prompt asks for on Lovable Cloud, passes deno check, and a live call started through the starter's server route returned a complete session grant.
  • Not covered by those checks: a run of this prompt inside Lovable. Lovable 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 Lovable 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