November 18, 2026 · 11 min · api · engineering
.mdHeyGen Streaming Avatar sunset: LiveAvatar or a Next.js switch
HeyGen's v1/v2 API hit its sunset on October 31, 2026, and the old streaming token route now returns 404. What LiveAvatar changes, a call map, a Next.js switch.
HeyGen's v1 and v2 API reached its sunset on October 31, 2026: v3 is the supported API, v1/v2 endpoints are being removed, and HeyGen's v3 table has no streaming avatar endpoint. The old @heygen/streaming-avatar SDK got its session token from POST /v1/streaming.create_token, a v1 route that answered 404 Not Found when we called it on 16 November 2026. HeyGen's realtime avatars now run on LiveAvatar, a separate platform with its own web SDK (@heygen/liveavatar-web-sdk), session tokens that your backend mints with a LiveAvatar API key, and credits that are independent of HeyGen API credits. HeyGen and LiveAvatar avatars are not cross-compatible, so every avatar gets re-created whichever way you go. Moving to LiveAvatar is the like-for-like path. Switching providers is the other: for a Next.js app, Realtime Avatar's App Router adapter keeps the API key on the server, and a new avatar starts from one portrait.
What the October 31, 2026 sunset removed
HeyGen's endpoint version comparison page, read on 16 November 2026, gives the timeline in two rows. Sunset, October 31, 2026: v1/v2 reached end of support and v3 is the supported API. Removal, in progress: v1/v2 endpoints are being removed, calls may fail intermittently until removal is complete, and HeyGen tells developers to route all traffic to v3. The same page explains how to find legacy calls in a running codebase:
- Every v1 and v2 response carries a Deprecation: true header and a Sunset header of Sat, 31 Oct 2026 00:00:00 GMT.
- The JSON body gains a warning object with v3_endpoint, docs_url and sunset_date fields. Logging warning.v3_endpoint across a day of traffic gives you a migration list.
- The v3 table maps video generation, templates, translation, text-to-speech, voices, avatars, webhooks and assets to new endpoints. It has no row for streaming or interactive avatars, so there is no v3 streaming call to move to.
- The old SDK's token request, POST https://api.heygen.com/v1/streaming.create_token with an x-api-key header, is a v1 endpoint. The package README's first section is now a Migration to LiveAvatar notice saying HeyGen will be deprecating Interactive Avatar.
If the interactive avatar in your React app stopped working, check the token call first. We tested it on 16 November 2026 with plain requests and no key: v1 and v2 endpoints that still exist, such as GET /v1/user/me, answered 401 with the Deprecation and Sunset headers, while POST /v1/streaming.create_token, POST /v1/streaming.new and GET /v1/streaming.list answered 404 Not Found with no Sunset header. A 401 means the route exists and wants a key. A 404 on the token route means the route itself is gone, so a new key or a retry will not bring the old flow back; the fix is a new session flow. You can repeat the check:
curl -s -o /dev/null -w "%{http_code}\n" -X POST https://api.heygen.com/v1/streaming.create_token
# 404 on 16 Nov 2026: the old streaming token route is gone
curl -s -D - -o /dev/null https://api.heygen.com/v1/user/me | grep -i -E "^(HTTP|deprecation|sunset)"
# HTTP/2 401, deprecation: true, sunset: Sat, 31 Oct 2026 00:00:00 GMT
Moving to LiveAvatar: what changes
LiveAvatar is HeyGen's realtime avatar product. Your HeyGen login works there, but it is a separate platform with its own plans and settings, and HeyGen paid plans or avatar slots do not apply to it. As of November 2026, these are the changes an app built on the Streaming Avatar SDK runs into:
- New package and class: @heygen/liveavatar-web-sdk exports LiveAvatarSession, which you construct with a session token and an optional config, start with session.start() and close with session.stop().
- Tokens come from your backend. For FULL mode it calls POST https://api.liveavatar.com/v1/sessions/token with your LiveAvatar API key in the X-API-KEY header and an avatar_id, and receives a session_id and session_token. Minting requires an API key, and LITE mode has its own token endpoint.
- Session settings move to the server. The token request takes the avatar_id, an optional stored voice agent for the persona, an optional custom LLM configuration and a max_session_duration capped by your plan. The old SDK took most of this in createStartAvatar on the client.
- Two modes. FULL is the managed agent: LiveAvatar runs speech recognition, the LLM and the voice. LITE is bring your own agent: you run the voice stack and LiveAvatar renders and streams the avatar.
- Credits are per minute of session time. LiveAvatar's FAQ puts 1 credit at 30 seconds of streaming in FULL mode and 1 minute in LITE mode, so FULL costs 2 credits a minute.
- Plans on liveavatar.com: Free gives 10 credits a month, 1 concurrent session, 2 minutes per session and a watermark. Essential is $99 a month for 1,100 credits, unlimited concurrency, sessions up to 20 minutes and one 720p custom avatar. Business is $475 a month for 6,000 credits, unlimited concurrency, sessions up to 60 minutes and one 1080p custom avatar. Overage is $0.095 a credit on Essential and $0.09 on Business, per the LiveAvatar FAQ.
Re-creating your avatars on LiveAvatar
LiveAvatar's FAQ says HeyGen and LiveAvatar avatars are trained on different models and are not cross-compatible, so the Interactive Avatars you built at labs.heygen.com have to be made again. There are two creation routes. The video route needs one continuous, uncut recording of at least 2 minutes: 15 silent seconds of listening, 90 seconds of talking and 15 silent seconds of idling. The photo route takes a single JPEG or PNG of at least 1080p in 16:9 or 9:16, head and shoulders, mouth closed, and the guide says to avoid cartoons, anime and illustrations because the model is optimized for human-like features. Essential and Free users give live consent by webcam; Business and Enterprise users can upload a pre-recorded consent video. The creation guide also limits training to twice per avatar slot per month, so get the footage or photo right before you upload.
Old call to new call
Each line maps a call from the @heygen/streaming-avatar 2.1.1 README to its equivalent in the LiveAvatar web SDK README, the FULL session token reference or the FULL mode events reference. LiveAvatar commands go to the LiveKit room topic agent-control, and events come back on agent-response.
- Token: POST /v1/streaming.create_token (a one-time token) becomes POST /v1/sessions/token on api.liveavatar.com, called from your server with mode FULL and an avatar_id.
- Start: new StreamingAvatar({ token }) followed by createStartAvatar({ avatarName, voice, language, ... }) becomes new LiveAvatarSession(sessionToken, config) followed by await session.start().
- Say exact text: speak({ text, task_type: TaskType.REPEAT }) becomes the avatar.speak_text command, which makes the avatar speak the text you provide.
- Ask the LLM: speak({ text }) with the default TALK type becomes the avatar.speak_response command, which generates an LLM response to your text and speaks it.
- Voice chat: startVoiceChat() becomes the voiceChat session config, applied on connect. The microphone is on by default, and voiceChat: { defaultMuted: true } gives a text-only session.
- Push-to-talk: pushToTalkStart() and pushToTalkStop() become the user.start_push_to_talk and user.stop_push_to_talk commands, and your server mints the token with interactivity_type PUSH_TO_TALK instead of the default CONVERSATIONAL.
- Interrupt and listening: interrupt(), startListening() and stopListening() become the avatar.interrupt, avatar.start_listening and avatar.stop_listening commands.
- Events: StreamingEvents.AVATAR_START_TALKING becomes avatar.speak_started. For StreamingEvents.STREAM_DISCONNECTED, the closest FULL mode event is session.stopped, whose end reason tells you why, such as IDLE_TIMEOUT, MAX_DURATION_REACHED or NO_CREDITS.
- Stop: stopAvatar() becomes session.stop().
- Keep alive: keepAlive() stays keepAlive(), or set autoKeepAlive: true in the config and the SDK calls keepAlive() every 60 seconds while connected.
A minimal version of the new flow, with the key in a Next.js route handler. Add your own sign-in check before minting, or anyone who can call the route spends your credits.
// app/api/liveavatar-token/route.ts (server only)
export async function POST() {
// check the signed-in user here before spending credits
const res = await fetch("https://api.liveavatar.com/v1/sessions/token", {
method: "POST",
headers: {
"X-API-KEY": process.env.LIVEAVATAR_API_KEY!,
"Content-Type": "application/json",
},
body: JSON.stringify({ mode: "FULL", avatar_id: process.env.LIVEAVATAR_AVATAR_ID }),
});
if (!res.ok) return new Response("Token request failed", { status: 502 });
const { data } = await res.json(); // { session_id, session_token }
return Response.json({ sessionToken: data.session_token });
}
// lib/start-live-avatar.ts (browser)
import { LiveAvatarSession } from "@heygen/liveavatar-web-sdk";
export async function startLiveAvatar() {
const res = await fetch("/api/liveavatar-token", { method: "POST" });
const { sessionToken } = await res.json();
const session = new LiveAvatarSession(sessionToken, { autoKeepAlive: true });
await session.start();
return session; // call session.stop() to end the call
}LiveAvatar migration checklist
- Get a LiveAvatar API key and pick a plan. The free tier is for testing; LiveAvatar's FAQ says you need a paid LiveAvatar plan to stream your avatar past basic free testing, and HeyGen plans do not count.
- Re-create each avatar on LiveAvatar from a 2-minute video or a photo. Essential and Business each include one custom avatar; more are paid add-ons.
- Replace the HeyGen token call with a server route that calls POST /v1/sessions/token with X-API-KEY, mode FULL and an avatar_id, and set max_session_duration within your plan's cap (20 minutes on Essential). A session that hits it ends with the MAX_DURATION_REACHED reason, so long calls need Business or a reconnect flow.
- Swap @heygen/streaming-avatar for @heygen/liveavatar-web-sdk and rewrite each call with the map above.
- Decide on overage. With it on, avatars stay online after the monthly credits run out and you pay the per-credit overage rate; without it, a session can end with the NO_CREDITS reason.
- Remove the HeyGen API key from the realtime path. HeyGen API credits do not pay for LiveAvatar sessions.
Switching instead: what you redo either way
Most of the migration work is not a switching cost, because LiveAvatar requires it too: the old avatar IDs, the createStartAvatar options and the HeyGen token call go away on every path.
- New avatars on any platform, because HeyGen avatars do not carry over to LiveAvatar either.
- A server route that mints sessions, because both LiveAvatar and Realtime Avatar keep the API key off the browser.
- A new pricing model: LiveAvatar credits per minute of session, or Realtime Avatar credits metered by the second.
What a switch to Realtime Avatar buys: TypeScript, React and React Native SDKs; full-duplex conversation with interruption, backchannel and semantic end-of-turn; tool calling with your own handlers and no hosted function registry; and your own text-to-speech through a signed voice webhook. Avatar creation is image-only: one portrait in, and the platform generates the idle, listening and gesture states. LiveAvatar also accepts a photo, so that alone is not a reason to switch; the SDK, the billing model and the price usually are.
The Next.js path on Realtime Avatar
The realtime-avatar package ships an App Router adapter, so the server half is one route file: the browser talks to your app, and your app talks to the platform.
npm install realtime-avatar livekit-client @livekit/components-react zod
# .env.local, read on the server only (no NEXT_PUBLIC_ prefix)
REALTIME_AVATAR_API_KEY=your_key// 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!,
// Return a Response to refuse, or nothing to allow.
authorize: async ({ request, operation }) => {
const user = await currentUser(request); // your auth
if (!user) return new Response("Sign in", { status: 401 });
if (operation === "connect" && !user.credits) {
return Response.json({ code: "insufficient_credits" }, { status: 402 });
}
},
// What the character knows, decided on the server.
session: async ({ avatarId }) => ({
instructions: promptFor(avatarId), // your prompt
}),
});The NEXT_PUBLIC_ prefix inlines a value into the client bundle, so the key must not wear it. The [...path] catch-all is required: without it the route answers 404 for connect, end, avatars and credits. Connect is the only operation that costs money to start, so that is where the balance check belongs, while the sign-in check covers every operation; currentUser and promptFor stand in for your own code. The client half is one component:
// app/call.tsx
"use client";
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} />;
}The use client directive is required because the call holds a WebRTC room and browser media. On serverless hosting, back ownsSession with your own session-to-user records: the SDK's default in-process ownership tracking fits a single process and does not span serverless instances. The Next.js guide linked below adds a downloadable starter and server-side call recording.
Cost at 600 minutes a month
A worked example at 600 call minutes a month, one call at a time, before taxes. LiveAvatar figures are from liveavatar.com and the LiveAvatar FAQ as of November 2026; Realtime Avatar figures are from its billing catalog.
- LiveAvatar FULL on Essential: $99 buys 1,100 credits, which is 550 FULL minutes at 2 credits a minute. The other 50 minutes use 100 overage credits at $0.095, which is $9.50. Total $108.50 a month, with no single session longer than 20 minutes.
- LiveAvatar LITE on Essential: the same $99 covers 1,100 LITE minutes, so 600 minutes fit inside the plan. LITE prices the video only, so add what your own speech recognition, LLM and voice cost.
- Realtime Avatar Starter: $9 a month includes 120 minutes, and the other 480 minutes at $0.095 a minute add $45.60. Total $54.60.
- Realtime Avatar Developer: $24 a month includes 600 minutes. Total $24. The platform handles listening, the reply and the video, and without a voice webhook its built-in voices are included in the per-second rate.
- Avatars on top: LiveAvatar Essential includes one custom avatar. Realtime Avatar Developer includes 25, and its credits also cover generation (images, idle clips, avatars), so building avatars in a month draws on the same balance as the 600 minutes; avatars beyond the included count are $3 each.
Concurrency cuts the other way. LiveAvatar's paid plans state unlimited concurrency; Realtime Avatar Developer allows 10 concurrent sessions, Studio ($119 a month for 3,000 minutes, $0.08 a minute after) allows 20, and the Scale plan is quoted by sales. To test first, Realtime Avatar's free Sandbox grants 480 credits once per account, no card (8 realtime minutes, or a first avatar plus 2 minutes of calls); LiveAvatar Free gives 10 credits a month (5 FULL minutes) with 2-minute sessions and a watermark.
Which path fits
- You already make recorded videos in HeyGen, or want to keep one vendor: migrate to LiveAvatar FULL. It is the direct successor, and the call map above covers most of the rewrite.
- You need more than 20 simultaneous sessions without a sales quote, or sessions of up to an hour: LiveAvatar's paid plans state unlimited concurrency, and Business allows 60-minute sessions. Realtime Avatar's self-serve plans top out at 20 concurrent sessions on Studio.
- You already run your own voice agent on LiveKit Agents, Pipecat or OpenAI Realtime and only need a face for it: LiveAvatar LITE, or another face-only renderer such as Simli. Realtime Avatar has no renderer-only mode that lip-syncs audio streamed from your own voice agent.
- You want a managed conversation billed by the second, React and React Native SDKs, tool calls handled by your own code and a Next.js adapter that keeps the key server-side: Realtime Avatar.
- You want your own model behind the avatar: both work. LiveAvatar's FULL token request accepts a custom LLM configuration ID, and Realtime Avatar points a call at an OpenAI-compatible endpoint you host, enabled per workspace on request.
Migration questions developers ask
Is the old Streaming Avatar API part of the October 31, 2026 sunset?
Yes. The sunset covers HeyGen's v1 and v2 API, and the SDK's token call, POST /v1/streaming.create_token, is a v1 endpoint with no v3 streaming replacement in HeyGen's table. On 16 November 2026 that route answered 404 Not Found, while v1 routes that still exist answered with Deprecation and Sunset headers, so treat the old flow as gone.
Has the Streaming Avatar SDK been replaced by LiveAvatar, and how do session tokens work now?
Yes. The old package's README points to LiveAvatar, whose client SDK is @heygen/liveavatar-web-sdk. Your server calls POST https://api.liveavatar.com/v1/sessions/token with a LiveAvatar API key and an avatar_id, passes the returned session_token to the browser, and the browser starts a LiveAvatarSession with it.
My Interactive Avatars are not in LiveAvatar. Can I make a live avatar from a single image?
They will not appear there: the two platforms' avatars are not cross-compatible. LiveAvatar's photo route takes one head-and-shoulders photo of at least 1080p, and Realtime Avatar creates an avatar from one portrait. Neither needs the 2-minute recording.
Is LiveAvatar the only option with a React SDK and a server-side session route?
No. Realtime Avatar's TypeScript SDK, the realtime-avatar package, covers React and React Native and includes createRealtimeAvatarRoute for the Next.js App Router, so the key stays on your server. With LiveAvatar you write the token route yourself, as in the example above.
What is HeyGen's realtime API and live avatar SDK called now?
HeyGen's realtime avatar API is now the LiveAvatar API at api.liveavatar.com, and its browser SDK is the @heygen/liveavatar-web-sdk npm package, billed in LiveAvatar credits rather than HeyGen API credits.
¿Cómo migro de HeyGen Streaming Avatar a otra API en Next.js sin exponer la API key?
Crea un route handler en app/api/realtime-avatar/[...path]/route.ts con createRealtimeAvatarRoute de realtime-avatar/nextjs y guarda la clave en REALTIME_AVATAR_API_KEY, sin el prefijo NEXT_PUBLIC_. En el navegador, AvatarCall y createProxyClient de realtime-avatar/react hablan solo con esa ruta. Los avatares de HeyGen no se trasladan, así que crea uno nuevo a partir de un retrato.
- Next.js guide: full route file, starter and troubleshooting
- React SDK: AvatarCall and the hook underneath it
- Creating an avatar from one portrait
- Realtime Avatar vs HeyGen LiveAvatar: price per minute and limits
- All-in cost per hour, dated vendor table
- HeyGen alternative for realtime avatars
- HeyGen API pricing explained
- Realtime Avatar vs Simli
- LiveAvatar API billing: credits, conversation modes, and total cost
- HeyGen: endpoint version comparison and deprecation timeline (read 2026-11-16)
- HeyGen Help Center: LiveAvatar FAQ (read 2026-11-16)
- HeyGen Help Center: custom LiveAvatar creation guide, video and photo (read 2026-11-16)
- LiveAvatar plans and session limits (read 2026-11-16)
- LiveAvatar docs: Create FULL session token (read 2026-11-16)
- LiveAvatar docs: FULL mode events (read 2026-11-16)
- LiveAvatar Web SDK README on GitHub (read 2026-11-16)
Compare and cost guides
- Realtime Avatar pricing
- Avatar API cost calculator
- Realtime Avatar vs Tavus, HeyGen LiveAvatar, Anam and Simli
- Realtime AI avatar APIs compared
- Realtime avatar API pricing, worked out
- HeyGen and LiveAvatar API pricing explained
- Choosing a HeyGen alternative for realtime avatars
- Tavus pricing per minute
- A Tavus alternative for live AI characters
- Meta Muse Realtime Avatar vs Realtime Avatar
- A realtime AI avatar in React Native or Expo
- Live avatars in 2026: a field guide to the research