Add a talking avatar to your React or Next.js app

One iframe or one script tag puts a live avatar in your app. It listens, answers out loud and moves its lips in sync.

How the embed works

There is no npm package: the embed is an iframe in any framework. The embed URL is https://www.bithuman.ai/embed/<CODE>, and the avatar listens and answers. With the web embed, the conversation runs on bitHuman's servers, so there is no voice stack for you to build.

Choose render=cloud to stream the avatar from the bitHuman cloud, or render=local to request rendering in the visitor's tab after a device check.

React: one component

Pass an agent code. Keep microphone * in allow, or the microphone is blocked. The visitor sees the avatar's picture with Tap to talk; after they allow the microphone, the avatar greets them and answers when they speak.

React

export function Avatar({ code }) {
  return <iframe src={`https://www.bithuman.ai/embed/${code}`} allow="microphone *" style={{ width: "100%", height: 600, border: 0 }} title="Talking avatar" />;
}

Next.js: the floating widget

For a floating avatar in the corner of every page, load the widget script with next/script and call init when it has loaded. Render <AvatarWidget code="A23WJF0199" /> once, in your root layout. A second init call is ignored, so a re-render does not add a second widget.

Next.js

"use client";
import Script from "next/script";

declare global {
  interface Window { BitHumanGadget?: { init: (options: Record<string, unknown>) => void } }
}

export function AvatarWidget({ code }: { code: string }) {
  return (
    <Script
      src="https://www.bithuman.ai/widgets/bithuman-gadget.js"
      strategy="afterInteractive"
      onLoad={() => window.BitHumanGadget?.init({ agentUrl: `https://bithuman.ai/${code}?deployment=gadget` })}
    />
  );
}

Your persona, your model, your secret

The persona and the model are settings on the agent, not code on your page. Set the persona as the agent's system prompt, and to answer with your own model, connect any OpenAI-compatible endpoint as a provider.

A public agent needs no credential in the page. For a private agent, your server mints an embed token with your API secret and passes it to the page, so the secret stays on your server.

Embed tokens

Common fixes

If the avatar does not appear or cannot hear the visitor:

The microphone never activates: serve the page over HTTPS, or http://localhost while you build.
The frame says embedding is disabled: turn Anonymous Share back on in the agent's sharing settings.
The frame shows a browser error page: remove the Cross-Origin-Embedder-Policy header from your page.
The session ends after a minute: the embed points at a sample agent, so point it at your own.

Choose a model

The embed renders Essence 2 and Expression 2 agents. Essence 2 renders a photoreal person from one portrait. Expression 2 renders any character, from people to animals and cartoons, from one portrait. The wise-pup sample ends each session after a minute; sessions on your own agent have no such limit.

What it costs

From 12 October 2026, API and SDK use requires the Creator plan or higher.

Sessions on your own agent bill your account per second, voice and AI included, at the managed voice chat rate. Creating your own agent needs a paid plan, Creator or higher.

See pricing

Every step, with troubleshooting, is in the docs. React guide in the docs