Build a realtime avatar language-practice app in Next.js

A useful first avatar app is a short language-practice conversation: order a drink, ask a follow-up question and get one specific correction. The scope is small enough to test, while exercising the same connection, text, microphone and session-ending paths a larger app needs.

This tutorial uses a ready Realtime Avatar character and a complete local Next.js project. It does not require creating an avatar or building a separate speech pipeline. You need Node.js 22 or newer, a session-capable API key and available call credits.

1. Run the starter

Download the source archive, then run:

unzip nextjs-avatar-starter.zip
cd nextjs-avatar-starter
npm ci
cp .env.example .env.local
# Add REALTIME_AVATAR_API_KEY to .env.local
npm run dev

Open http://127.0.0.1:3000. Start a call and send a text message first. This separates connection problems from microphone permissions. When that works, end the call, enable the microphone and start another one. Calls are capped at 60 seconds and consume account credits.

2. Give the character one job

The server decides what the character knows. In app/api/realtime-avatar/[...path]/route.ts, keep the existing authorization and avatar checks, and replace the returned instructions value with this prompt:

You are Rin, a friendly café barista helping an adult practice English.
Say clearly that this is a practice conversation.
Use short, everyday sentences and ask one question at a time.
Help the learner order one drink, choose its size, and ask the price.
Use this fictional menu only: tea $3, coffee $4; a large drink costs $1 more.
After the order, give one specific language correction if needed.
If the learner says "feedback", give one thing they did well and one suggestion.
If the learner corrects the order, use the latest choice.
Do not claim to place a real order, accept payment, or assess proficiency formally.

The menu is fictional test data, not product pricing. Keeping it fixed gives you an answer key. The 60-second limit also makes it obvious whether your instructions ask for more conversation than the session allows. Keep the prompt short enough for the intended exercise.

3. Keep session ownership in your app

The browser uses createProxyClient and useAvatarCall. The hook returns call for status and controls, and view for the video surface. Mount it after Start, send text through call.say, and end with call.end. The included page implements those controls and removes the call after onEnded.

The API key stays in .env.local, without a NEXT_PUBLIC_ prefix. The starter's proxy allows local development only. For a hosted app, implement user authorization, balance and rate checks, and persistent session ownership before enabling production calls. The Next.js guide explains the server adapter and common errors.

4. Test the exercise, not just the video

These are acceptance criteria, not claimed results. Run the script with several phrasing variations and note failures. A prompt can guide behavior; it does not guarantee it. For a real learning product, have a qualified educator review the exercise and learner feedback.

5. Capture evidence before expanding

The starter can download each run's browser and startup observations as JSON. It distinguishes SDK readiness from a displayed remote frame; neither measures how quickly a spoken question receives an audible answer. Use the measurement guide to design that separate test.

Once this small exercise behaves consistently, estimate monthly minutes and peak simultaneous calls in the cost calculator. Expand to another scenario only after you have a rubric for what a good conversation should do.