Breakthrough AI

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.

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

QueryDefaultMeaning
roommain Which live room to listen on. Give each embed its own room to drive them apart.
compose1 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.

javascript
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:

http
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

POST/api/v1/say

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

FieldTypeMeaning
textstring optional The exact words to speak. Skips the language model entirely.
promptstring optional What to talk about, if she should compose the line herself.
gesturestring optional An expression to play while she speaks. Otherwise inferred from the line.

Send neither text nor prompt and she greets the viewer.

curl
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:

HeaderMeaning
X-Briana-TextThe words she speaks, URL-encoded.
X-Briana-GestureThe expression chosen, if any.
javascript
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

GET/api/v1/health

Liveness, the gesture list, and whether a token is required.

response
{ "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.

GET/api/v1/gestures

The gestures this build can play.

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

mcp client config
{
  "mcpServers": {
    "briana": {
      "type": "http",
      "url": "/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Claude Code, in one line:

shell
claude mcp add --transport http avatar-ai /mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Tools

ToolArgumentsDoes
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

NameReads as
winkOne eye closes and opens, through a travelling lid.
flirtyA smile, a wink, and back to the smile.
smileA warm closed-mouth smile, held.
delightA wide open smile settling into a softer one.
blinkAn 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

StatusMeans
401No token, a wrong token, or a cross-site browser request.
413Body over 64 KB. A line of speech is not this big.
429Over the rate limit — 20 requests a minute per address by default.
502The speech or language model failed. Usually the free tier shedding load; retry.