Avatars (ScaiVatars)

ScaiVatars turns any ScaiBot into a 3D-rendered avatar. The user sees a face, hears synthesized speech, and watches the mouth move in sync — all driven by the same persona, voice, and knowledge configuration that backs your text and voice modes.

When to use an avatar#

Your product surface is a kiosk, in-store display, museum exhibit, or live demo where a face + voice feels more natural than a chat bubble.
Customers expect a "talking head" — receptionist, brand mascot, learning companion, virtual host.
You're building an installation or experience where the avatar replaces a human presenter for repeatable interactions.

If you only need voice (no face), use the voice widget. If you only need chat, use the embed widget. The avatar adds a 3D rendering layer; everything else underneath is shared.

What you get#

Visual presence. Load any GLB / GLTF / VRM model the customer hosts. The avatar renders client-side in Three.js (or any WebGL framework the customer prefers) using a blendshape stream that ScaiGrid generates server-side.
Real-time lip-sync. Audio and blendshapes are produced together from the bot's TTS output; mouth movements track the spoken words sample-accurate.
Same persona stack. Tone, knowledge base, escalation, voice ID — all inherited from the existing ScaiBot configuration. Avatars are a presentation layer, not a parallel product.
Public WebSocket gateway. One stable URL per ScaiGrid deployment. Clients connect with the bot's existing embed token; no second credential store to manage.
Per-bot origin allow-list. Cross-origin connections are accepted only from origins you explicitly approve, per-bot — your customer site, your kiosk hostname, etc.

Two-minute mental model#

You manage two new things on top of an existing bot:

A 3D model URL — a GLB / GLTF / VRM your client loads and animates. ScaiGrid doesn't host the model; you point at whatever CDN or storage you already use.
An allowed origins list — the customer origins the public WebSocket will accept connections from.

Everything else (voice, persona, prompt, knowledge, model) comes from the bot's existing configuration. Toggling avatars on for an existing bot is a single switch, not a re-setup.

How a session works#

The customer's web page loads your 3D client (Three.js, react-three-fiber, Unity-on-Web, whatever).
The client opens a WebSocket to ScaiGrid's public avatar gateway, presenting the bot's embed token.
ScaiGrid validates the token, checks the browser's Origin against the bot's allow-list, and accepts the WebSocket.
The client sends start_session(avatar_id=<bot.slug>) to identify the avatar.
The server pushes an avatar_update event carrying the bot's 3D config — model_url, blendshape_profile, idle_animation. The client uses this to load the right model without an extra HTTP fetch.
The client sends send_text or text_to_speech requests as the user interacts.
ScaiGrid streams back response chunks containing text, voice (base64 PCM), and a blendshape track — all synchronized in time.
The client plays the audio and drives the 3D model's blendshape weights from the same stream. Mouth movements track the audio sample-accurate.

The wire protocol is documented in Avatar API reference.

Security model#

The avatar surface has three distinct security layers, deliberately separated:

Layer	What it is	Public-safe?
`?token=…` (embed token)	Credential. Per-bot, revocable from the Embed & Deploy page.	NO — secret
`Origin` header → allow-list	Scope gate. Per-bot list of customer origins.	n/a
`avatar_id` (the bot's slug)	Identifier the client passes in `start_session`.	YES — safe to bake into client code

The embed token is the actual credential — losing it gives an attacker WebSocket access from any allowed origin. The slug is just a name the client uses to confirm which bot it's talking to; two tenants can have a bot with the same slug, and the embed token resolves which tenant's bot is meant.

What it doesn't do (yet)#

No avatar marketplace. You provide the 3D model URL; we don't host or curate models in v1.
One avatar per bot. Multiple avatar variants per bot ("Poolnoodle in business", "Poolnoodle casual") would need a separate Avatar entity — deferred per v1 scope.
No sentence-level streaming yet. Each conversational turn produces a single response chunk after the full TTS + lipsync pipeline completes. Sentence-level streaming (lower time-to-first-audio) is a v1.2 follow-up when latency calls for it; today's avatar surface is closer to "say a paragraph" than "rapid-fire back-and-forth".