Documentation
Avatar AI
Live speaking avatars you can embed in a page, or drive from an agent over MCP. An avatar is a face and a voice, not a chat log.
These docs use Briana, the first live agent, which is what a default install serves.
Base URL — every example on this page is already pointed at it.
Embed her
One iframe. She is 450 × 600 with rounded corners and a transparent page behind her, so she takes your own background.
<iframe
src="/widget.html"
width="450" height="600"
style="border:0;background:transparent"
allow="autoplay"
></iframe>
Keep allow="autoplay".
Without it the browser blocks her voice and she mouths silently — which looks like a
broken animation rather than a blocked sound.
Widget options
| Query | Default | Meaning |
|---|---|---|
room | main |
Which live room to listen on. Give each embed its own room to drive them apart. |
compose | 1 |
0 removes the chooser and button, leaving a display-only avatar driven entirely by your agent. |
greeting | — | The status line shown while she is idle. |
Drive her from the host page
No token needed: the message goes to the iframe, and the iframe's own origin authorises it.
const briana = document.querySelector("iframe").contentWindow;
// Play one of the built-in lines by id.
briana.postMessage({ briana: "say", text: "welcome" }, "*");
briana.postMessage({ briana: "gesture", gesture: "wink" }, "*");
The widget ships with a short set of ready lines so a visitor has something to press
straight away, with no wait and nothing to think up. Their ids are
hello, what, voice, charm,
welcome, custom, ask and counting.
To make her say something of your own, use the API.
postMessage reaches the widget from a page with no credentials, so it
can only pick from lines that already exist — otherwise any page embedding her could
spend your quota on arbitrary text. Arbitrary speech goes through
/api/v1/say or MCP, both of which need a token.
Authentication
The widget authenticates by origin — a browser sets Sec-Fetch-Site
and no page can forge it, so Briana's own page gets in and another site does not.
A browser cannot hold a secret, so the widget carries no token.
Everything else — your server, your agent, this API — presents a bearer token:
Authorization: Bearer YOUR_TOKEN
A token that is offered and wrong is rejected outright; it never falls back to the
origin check. Requests without either get 401.
Make her speak
/api/v1/sayThe whole round trip in one call: a line is written if you do not supply one, rendered to speech, and returned as audio. The response body is the mp3.
| Field | Type | Meaning |
|---|---|---|
text | string optional | The exact words to speak. Skips the language model entirely. |
prompt | string optional | What to talk about, if she should compose the line herself. |
gesture | string optional | An expression to play while she speaks. Otherwise inferred from the line. |
Send neither text nor prompt and she greets the viewer.
curl -X POST /api/v1/say \
-H "Authorization: Bearer $BRIANA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"prompt":"Introduce yourself to a new visitor."}' \
--output briana.mp3
Response headers carry what the body cannot:
| Header | Meaning |
|---|---|
X-Briana-Text | The words she speaks, URL-encoded. |
X-Briana-Gesture | The expression chosen, if any. |
const res = await fetch("/api/v1/say", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.BRIANA_TOKEN}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ text: "Good morning." }),
});
const said = decodeURIComponent(res.headers.get("X-Briana-Text"));
const audio = Buffer.from(await res.arrayBuffer());
Other routes
/api/v1/healthLiveness, the gesture list, and whether a token is required.
{ "ok": true,
"gestures": ["blink","delight","flirty","smile","wink"],
"secured": true }
"secured": false means no token is configured and the API is open. In
production that is a misconfiguration, not a mode.
/api/v1/gesturesThe gestures this build can play.
/api/v1/live?room=…The widget's event stream. You do not normally call this — the widget opens it and keeps it open. It is documented because an intermediary that buffers it will make a live widget look dead.
MCP
Streamable HTTP. Point any MCP client at it.
{
"mcpServers": {
"briana": {
"type": "http",
"url": "/mcp",
"headers": { "Authorization": "Bearer YOUR_TOKEN" }
}
}
}
Claude Code, in one line:
claude mcp add --transport http avatar-ai /mcp \
--header "Authorization: Bearer YOUR_TOKEN"
Tools
| Tool | Arguments | Does |
|---|---|---|
speak |
text, prompt, gesture, room |
Makes her say something out loud in the live widget. Returns the words she speaks. |
gesture |
name, room |
Plays one expression. |
status |
room |
How many widgets are listening, and which gestures exist. |
Why speak returns text, not audio.
An MCP tool result is text or a base64 blob, and a minute of speech inside a JSON-RPC
envelope is both enormous and useless to an agent, which has no speakers. The line is
queued to the live widget and the audio travels to the browser instead. If nothing is
listening, speak tells you so rather than rendering speech nobody can hear.
Rooms
A room is just a name. A widget opened at ?room=lobby receives everything
addressed to lobby and nothing else, so one server can drive several
Brianas on several pages. Omit it and everyone shares main.
Call status before speak if you need to know anyone is
watching — rendering speech into an empty room costs a model call and reaches nobody.
Gestures
| Name | Reads as |
|---|---|
wink | One eye closes and opens, through a travelling lid. |
flirty | A smile, a wink, and back to the smile. |
smile | A warm closed-mouth smile, held. |
delight | A wide open smile settling into a softer one. |
blink | An ordinary blink, on demand. |
A gesture is a deliberate act, kept separate from whatever she is saying — so she will never wink or smile at random in the middle of a word. Ask for one when you want one.
What the browser can see
Everything that decides what she says happens on the server. The page never receives the text she is about to speak, the model that wrote it, or any key — it receives a sound and a picture, and nothing that explains either. The embed build ships none of the development tooling.
What is still public. Anything a browser has to download in order to draw her — her artwork — can be opened by anyone who can open the page. That is true of every avatar rendered in a browser. If your character's artwork has to stay private, say so before a build starts: it needs a different delivery and it is not what the monthly plans cover.
Limits and errors
| Status | Means |
|---|---|
401 | No token, a wrong token, or a cross-site browser request. |
413 | Body over 64 KB. A line of speech is not this big. |
429 | Over the rate limit — 20 requests a minute per address by default. |
502 | The speech or language model failed. Usually the free tier shedding load; retry. |
- A line is one or two sentences. She is built to talk, not to read a document aloud.
- Every
saycosts a model call and a speech render, so cache anything you repeat.