Docs

Add a Live AI Avatar to a Replit App (Import the Starter)

Import the Realtime Avatar starter into Replit in one click, or give Replit Agent a prompt, to add a live AI avatar video call. The API key goes in Replit Secrets and stays on the server.

Replit imports a public GitHub repo from a link, so the fastest start is the starter repo: a Vite, React and TypeScript page that renders a live AI avatar call through the AvatarCall component, served by a small Node server (Hono) on the same port that holds your API key. Press Call, allow the microphone, and talk; the avatar listens while she speaks and stops when you interrupt.

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. Import the starter

  1. Import the starter to Replit. Its .replit file runs npm run dev, which serves the page and the API route on one port.
  2. Open the Secrets tool and add REALTIME_AVATAR_API_KEY.
  3. Press Run, then Call Rin in the webview, and allow the microphone.
  4. To publish, deploy it: .replit already sets the build to npm run build and the run command to npm start. Check that the deployment has the same secret.

Where the API key goes

In Replit Secrets, as REALTIME_AVATAR_API_KEY. Secrets reach the app as environment variables, read by the starter's server (server/app.ts, and server/node.ts behind npm start). The browser receives only a session grant for one call. Never prefix the key with VITE_: Vite ships those variables to the browser.

With Replit Agent

To have Replit Agent build the call into an existing app instead, give it this prompt. It builds the same shape as the starter: a Vite and React page with a Hono server on the same port.

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

Build it as a Vite + React + TypeScript app with a small Node server (Hono) on the same port.

Server: mount the SDK's route on Hono:

    import { Hono } from "hono";
    import { realtimeAvatarHono } from "realtime-avatar/hono";

    const app = new Hono();
    app.all(
      "/api/realtime-avatar/*",
      realtimeAvatarHono({
        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 }),
      }),
    );

Serve the built page from the same server, listen on 0.0.0.0, and read REALTIME_AVATAR_API_KEY from Replit Secrets.

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 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.

What works and what has not been tested

  • Checked on 2026-10-05: the starter installs and builds cleanly, and a live call started through its Node route on a local machine returned a complete session grant.
  • Checked on 2026-11-15: the SDK version the starter and the prompt pin, realtime-avatar 0.26.0, exports every function they use.
  • Not covered by those checks: a run inside a Replit workspace or a Replit deployment, and a run of the prompt through Replit Agent, which writes its own code from it. If you use the prompt, check that no VITE_ variable holds the key and that the route returns the SDK's answer unchanged.

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 put its ava_… id in VITE_REALTIME_AVATAR_ID and REALTIME_AVATAR_IDS, and swap the poster and idleVideoUrl in src/avatar.ts for your avatar's own, or remove them.

Other builders

Compare and cost guides