Developers

Developer reference

Everything you need to put a Liveface avatar on a page and drive it from code. The widget is plain JavaScript and the API is plain REST: no framework, no build step.

Request free access Book a demo call

A portrait with the face mesh traced over it: one photo becomes a face that talks

Embed

The widget draws a canvas right after its script tag and exposes window.Liveface. The key travels in a header, never in a URL; each key has its own domain allow-list and usage limit.

<script
  src="https://liveface.io/api/liveface.js"
  data-avatar="YOUR_AVATAR_ID"
  data-key="YOUR_API_KEY"
  data-api="https://liveface.io/api"
></script>

Script tag attributes

Attribute	Meaning
data-avatar	The avatar's id (required).
data-key	An embed key from API keys (required).
data-api	Where the API is: https://liveface.io/api.
data-voice, data-provider, data-locale	Override the avatar's published voice.
data-speed	Voice speed for server voices, 0.7 to 1.3.
data-size	Width in CSS pixels; the canvas stays square and shrinks with its container.
data-zoom, data-framing	The view: closer on the face, or wider.
data-head-motion	"3d" turns a photo's face in depth, "2d" moves it as a flat layer.
data-expressions	"tags" (default), "auto" or "off".
data-idle-expressions	"off" removes the resting micro-expressions.
data-ai-label	"off" hides the AI label under an AI-made face.
data-debug	Puts the engine on the console for debugging.

JavaScript API

Expression tags in spoken text, such as [happy] or [surprised:0.6], set the face in time with the voice and are never read aloud. A word can carry its own pronunciation: "[Liveface](/lˈaɪvfeɪs/)".

Call	What it does
Liveface.speak(text)	Says the text with lip-sync. Long text is chunked and prefetched. Resolves when done.
Liveface.stream()	Speaks text while it is being written: live.write(piece), then await live.end(); live.stop().
Liveface.stop()	Stops speaking.
Liveface.isSpeaking()	Whether it is speaking now.
Liveface.setSpeed(n)	The voice's speed from now on, 0.7 to 1.3.
Liveface.listen({lang})	Browser speech recognition; resolves with the transcript.
Liveface.sttSupported()	Whether this browser can listen.
Liveface.express(name, intensity)	An expression: happy, surprised, concerned, thinking, serious; neutral releases.
Liveface.tune({...})	Adjusts the animation live, for example tune({ mouthOpen: 1.3 }).
Liveface.get(target), Liveface.all()	With several widgets: one by avatar id, canvas or script tag, or all of them.

Events

liveface:ready: the widget is up; event.detail is its handle (the same calls as above).
liveface:error: it could not be shown (a refused key, a picture that did not load); a short note appears under the canvas and nothing is thrown into your page.

REST API

For your own renderer, or a server that prepares speech. Authenticate with the X-Api-Key header.

Endpoint	Returns
GET /api/embed/v1/avatars/{id}	The published avatar: its picture, rig, voice, mouth and scene, with signed file URLs.
POST /api/embed/v1/synthesize	Speech audio for text, with timed viseme cues for the lips (text, provider, voice, locale).
POST /api/embed/v1/cues	Viseme cues for text without audio, for your own speech.

Limits during the beta

A free organization makes two avatars and speaks with the built-in voices; each organization has a monthly speech allowance. Paid speech providers are for organizations without a limit.

Make your own talking avatar

Upload a photo, choose a voice and hear it speak. Free during the beta.

Request free access Book a demo call

Updated 2026-10-27