Live avatars
Everything an application needs to build on real-time conversational avatars (HeyGen LiveAvatar, Tavus, Runway Characters, Vidu S2 and more): open and manage sessions, read transcripts, choose avatars and voices, save personas, and hand browsers a short-lived token. For how to choose a model and an AI-interviewer walkthrough, see the Live avatars guide; sessions are also covered in Live video.
All calls use Authorization: Bearer llmr_sk_live_... against https://videorouter.sh/api/v1 and need the live_video scope, which new keys have. Browser tokens can call the session calls only; the management calls (avatars, personas, voices, languages) are for your server. Lists return {"object": "list", "has_more": bool, "data": [...]}: sessions and personas page with limit and starting_after=<last id>, avatars and voices with page and limit (those are the host’s own libraries).
Sessions
POST/v1/live-video/sessions
Open a session. Holds max_duration_seconds x the per-second price against your credits (402 if you cannot cover it) and returns the credentials to join, once.
Parameters
modelstringA live avatar model, e.g. heygen/liveavatar or tavus/cvi (GET /live-avatar/models).max_duration_secondsintegerHard cap on the session; the host ends the call at it. Default and ceiling are per model.options.session_paramsobjectThe persona and settings, per model (see the sections above). persona_id loads a saved persona for LiveAvatar, Tavus, Anam and Runway; anything named here wins over the persona.Example request
{"model": "tavus/cvi", "max_duration_seconds": 600,
"options": {"session_params": {"persona_id": "lap_Hk3...", "greeting": "Hi, I'm Alex."}}}Example response
{"id": "lvs_Aqbx9zd0reoRz7Mu", "object": "live_video.session", "model": "tavus/cvi", "kind": "avatar", "status": "ready",
"price_per_second_usd": 0.006321, "reserved_usd": 3.79, "max_duration_seconds": 600,
"created_at": "2026-11-10T05:46:01Z", "ready_at": "2026-11-10T05:46:03Z", "expires_at": "2026-11-10T05:56:03Z",
"heartbeat_interval_seconds": 5,
"connect": {"protocol": "daily", "conversation_url": "https://tavus.daily.co/c...", "meeting_token": "...", "room_url": "https://maker.tavus.io/room/c..."}}connect is in this response only. It holds a LiveKit server_url and token (LiveAvatar, Runway), a Daily conversation_url and meeting_token (Tavus), or a session_token for Anam’s JavaScript SDK (Anam).
GET/v1/live-video/sessions
List your organization’s sessions, newest first. A browser token sees only the sessions it opened itself.
Parameters
statusstringwaiting, ready or ended.modelstringOnly sessions of this model.limitinteger1-100, default 20.starting_afterstringA session id; returns the sessions created before it.Example request
curl -s https://videorouter.sh/api/v1/live-video/sessions?status=ended&model=heygen/liveavatar&limit=2 -H "Authorization: Bearer llmr_sk_live_..."Example response
{"object": "list", "has_more": true, "data": [
{"id": "lvs__IZcfBmkeVRRMusz", "object": "live_video.session", "model": "heygen/liveavatar", "status": "ended",
"billed_seconds": 30.0, "cost_usd": 0.097375, "end_reason": "client", ...}, ...]}GET/v1/live-video/sessions/{id}
One session: status, the price, and once it has ended billed_seconds, cost_usd and end_reason.
Example request
curl -s https://videorouter.sh/api/v1/live-video/sessions/lvs_Aqbx9zd0reoRz7Mu -H "Authorization: Bearer llmr_sk_live_..."Example response
{"id": "lvs_Aqbx9zd0reoRz7Mu", "status": "ended", "billed_seconds": 34.0, "cost_usd": 0.214908, "end_reason": "client", ...}Statuses: waiting (a host is still preparing, nothing metered), ready (live, the meter runs), ended (settled). End reasons include client, max_duration, heartbeat_timeout and host_error.
POST/v1/live-video/sessions/{id}/heartbeat
Tell us the tab is still open. Send it about every 5 seconds; if the beats stop, we end the session for you and settle.
Example request
curl -s -X POST https://videorouter.sh/api/v1/live-video/sessions/lvs_.../heartbeat -H "Authorization: Bearer llmr_sk_live_..."Example response
the session objectPOST/v1/live-video/sessions/{id}/end
End the session now. The host call is stopped, the real cost is debited and the unused part of the hold is released. Ending an ended session returns it unchanged.
Example request
curl -s -X POST https://videorouter.sh/api/v1/live-video/sessions/lvs_.../end -H "Authorization: Bearer llmr_sk_live_..."Example response
the settled session objectTranscripts
HeyGen LiveAvatar, Tavus and Anam produce a transcript of the conversation. We keep a copy on the session when it ends so you can read it afterwards, and you can delete it.
GET/v1/live-video/sessions/{id}/transcript
The conversation so far (a running LiveAvatar session) or in full (an ended session). available is false when the model has no transcript or nothing was said.
Parameters
data[].rolestringuser or avatar.data[].textstringWhat was said.data[].timestampnumber | nullSeconds into the call (LiveAvatar); null where the host does not give one.Example request
curl -s https://videorouter.sh/api/v1/live-video/sessions/lvs_.../transcript -H "Authorization: Bearer llmr_sk_live_..."Example response
{"object": "live_video.transcript", "session_id": "lvs_...", "session_status": "ended", "available": true,
"data": [{"role": "avatar", "text": "Hello! Thanks for joining. Shall we begin?", "timestamp": 3},
{"role": "user", "text": "Yes, please.", "timestamp": 9}]}Tavus publishes its transcript a moment after the call ends; we wait for it when the session ends, so it is normally there as soon as /end returns.
DELETE/v1/live-video/sessions/{id}/transcript
Delete the stored transcript, and the host’s own copy where it keeps one (LiveAvatar). Use it to honour a deletion request.
Example request
curl -s -X DELETE https://videorouter.sh/api/v1/live-video/sessions/lvs_.../transcript -H "Authorization: Bearer llmr_sk_live_..."Example response
{"object": "live_video.transcript", "session_id": "lvs_...", "deleted": true}Avatars
The characters you can put in a session: HeyGen LiveAvatar’s public library (around 300 avatars), Anam’s 120 stock avatars, Tavus’s stock faces, your own custom avatars, Runway’s nine presets and Boson’s three. Pass the id as avatar_id (LiveAvatar, Anam), face_id (Tavus) or avatar (Runway) in session_params.
GET/v1/live-avatar/avatars
List avatars for a model.
Parameters
modelstringDefault heygen/liveavatar. Also anam/cara, tavus/cvi, runway/characters, boson/higgs-avatar-live.scopestringpublic (default) or mine, the custom avatars your organization created.page, limitintegerPage number and size, limit up to 100.Example request
curl -s https://videorouter.sh/api/v1/live-avatar/avatars?model=heygen/liveavatar&limit=2 -H "Authorization: Bearer llmr_sk_live_..."Example response
{"object": "list", "model": "heygen/liveavatar", "scope": "public", "page": 1, "has_more": true, "data": [
{"id": "513fd1b7-7ef9-466d-9af2-344e51eeb833", "object": "live_avatar.avatar", "name": "Ann Therapist", "status": "active",
"preview_url": "https://files2.heygen.ai/...webp", "default_voice_id": "de5574fc-...", "is_1080p": true, "owned": false}, ...]}GET/v1/live-avatar/avatars/{id}
One avatar (?model= as above). Another organization’s custom avatar is a 404.
Example request
curl -s https://videorouter.sh/api/v1/live-avatar/avatars/513fd1b7-... -H "Authorization: Bearer llmr_sk_live_..."Example response
the avatar objectPOST/v1/live-avatar/avatars
Create a custom avatar from one image (anam/cara or heygen/liveavatar). Multipart form. It may start as init; poll GET .../{id} until it is active.
Parameters
filefile (multipart)Required. anam/cara: JPEG, PNG or WebP up to 4.5 MB. heygen/liveavatar: JPEG or PNG up to 10 MB, exactly 16:9 or 9:16, short side at least 1080 px, one clearly framed person. A failing image returns 400 with the reason.namestringDisplay name. Required for Anam (3-50 characters), optional for LiveAvatar.modelstringanam/cara or heygen/liveavatar, the models that support custom avatars.Example request
curl -s https://videorouter.sh/api/v1/live-avatar/avatars -H "Authorization: Bearer llmr_sk_live_..." \
-F model=heygen/liveavatar -F name="Alex" -F file=@portrait.jpgExample response
{"id": "9c1e...", "object": "live_avatar.avatar", "model": "heygen/liveavatar", "name": "Alex", "status": "init", "owned": true, ...}Availability. anam/cara custom avatars work today. heygen/liveavatar needs a free avatar slot on our host plan, which we do not have yet: until we do, that model returns 503 custom_avatars_unavailable.
PATCH/v1/live-avatar/avatars/{id}
Change one of your own avatars.
Parameters
namestringNew name, up to 120 characters. The only field Anam avatars accept.default_voice_idstringheygen/liveavatar only: a public voice id from GET /live-avatar/voices.is_deactivatedbooleanheygen/liveavatar only: true to take it out of use without deleting it.Example request
{"name": "Alex, senior engineer", "default_voice_id": "de5574fc-009e-4a01-a881-9919ef8f5a0c"}Example response
the avatar objectDELETE/v1/live-avatar/avatars/{id}
Delete one of your own avatars (for Anam the stored picture is deleted too).
Example request
curl -s -X DELETE https://videorouter.sh/api/v1/live-avatar/avatars/9c1e... -H "Authorization: Bearer llmr_sk_live_..."Example response
{"id": "9c1e...", "object": "live_avatar.avatar", "model": "heygen/liveavatar", "deleted": true}Voices, languages and language models
GET/v1/live-avatar/voices
Stock voices for heygen/liveavatar and anam/cara (Tavus and the others pair the voice with the face). Pass the id as voice_id.
Parameters
languagestringFilter by language code, e.g. en.genderstringmale or female.page, limitintegerPaging, limit up to 100.Example request
curl -s https://videorouter.sh/api/v1/live-avatar/voices?language=en&limit=2 -H "Authorization: Bearer llmr_sk_live_..."Example response
{"object": "list", "model": "heygen/liveavatar", "page": 1, "has_more": true, "data": [
{"id": "a3abc0cd-26d0-4661-aaf5-af10e3cec175", "object": "live_avatar.voice", "name": "Wolf Spencer", "language": "en", "gender": "male", "tags": ["Preset"]}, ...]}GET/v1/live-avatar/languages
The languages a model can speak (heygen/liveavatar, tavus/cvi). Use the code as language (LiveAvatar) or in languages (Tavus).
Example request
curl -s https://videorouter.sh/api/v1/live-avatar/languages?model=tavus/cvi -H "Authorization: Bearer llmr_sk_live_..."Example response
{"object": "list", "model": "tavus/cvi", "data": [{"code": "ar"}, {"code": "bg"}, {"code": "bn"}, ...]}GET/v1/live-avatar/llm-models
The language models a model can think with: heygen/liveavatar (for llm_model) and anam/cara (for llm_id, with the model name and tags).
Example request
curl -s https://videorouter.sh/api/v1/live-avatar/llm-models -H "Authorization: Bearer llmr_sk_live_..."Example response
{"object": "list", "model": "heygen/liveavatar", "data": [{"id": "gpt-4o-mini", "provider": "openai", "default": true}, {"id": "gpt-4o", ...}]}GET/v1/live-avatar/models
The live avatar models, with their price, session limits and which of these calls each supports.
Example request
curl -s https://videorouter.sh/api/v1/live-avatar/models -H "Authorization: Bearer llmr_sk_live_..."Example response
{"object": "list", "data": [{"id": "tavus/cvi", "kind": "avatar", "price_per_second_usd": 0.006321, "max_session_sec": 1800,
"supports": {"avatars": "list the stock faces ...", "voices": false, "languages": true, "llm_models": false, "personas": true, "transcripts": true}}, ...]}Personas
A persona is a saved set of defaults for a session: the prompt, the opening line, the language and optionally an avatar, voice, language model and quality. Save your interviewer once, then open sessions with {"persona_id": "lap_..."}. Personas belong to your organization and nobody else can read them. Works with heygen/liveavatar, tavus/cvi, anam/cara and runway/characters; the prompt becomes the system prompt (LiveAvatar, Tavus, Anam) or the personality (Runway).
POST/v1/live-avatar/personas
Create a persona.
Parameters
namestringRequired. Up to 120 characters.promptstringRequired. The persona, up to 20,000 characters.opening_textstringWhat it says first (up to 1,000).languagestringLanguage code.modelstringThe model the avatar_id and voice_id belong to. Without it those two are ignored.avatar_id, voice_idstringDefaults for that model.llm_model, qualitystringheygen/liveavatar settings (see above). Anam picks its language model per session with llm_id.Example request
{"name": "Backend interviewer", "prompt": "You are Alex, a friendly senior engineer interviewing for a backend role...",
"opening_text": "Hi, I'm Alex. Ready to begin?", "language": "en",
"model": "heygen/liveavatar", "avatar_id": "513fd1b7-7ef9-466d-9af2-344e51eeb833", "quality": "high"}Example response
{"id": "lap_Hk3p9ZxQ2mTn5w", "object": "live_avatar.persona", "name": "Backend interviewer", "prompt": "...", "opening_text": "Hi, I'm Alex. Ready to begin?",
"language": "en", "model": "heygen/liveavatar", "avatar_id": "513fd1b7-...", "voice_id": null, "llm_model": null, "quality": "high",
"created_at": "2026-11-10T05:40:12Z", "updated_at": "2026-11-10T05:40:12Z"}GET/v1/live-avatar/personas
List your personas, newest first.
Parameters
limitinteger1-100, default 20.starting_afterstringA persona id.Example request
curl -s https://videorouter.sh/api/v1/live-avatar/personas?limit=20 -H "Authorization: Bearer llmr_sk_live_..."Example response
{"object": "list", "has_more": false, "data": [ ...persona objects... ]}GET/v1/live-avatar/personas/{id}
One persona.
Example response
the persona objectPATCH/v1/live-avatar/personas/{id}
Change any of the fields above; send null to clear an optional one.
Example request
{"prompt": "You are Alex... (revised)", "opening_text": null}Example response
the persona objectDELETE/v1/live-avatar/personas/{id}
Delete a persona. Sessions already open are not affected.
Example response
{"id": "lap_...", "object": "live_avatar.persona", "deleted": true}Browser tokens
POST/v1/live-video/tokens
Mint a short-lived key for a browser or mobile app, so your real key never leaves your server. It can open, list, heartbeat and end sessions (only the ones it opened) and read their transcripts, and nothing else.
Parameters
modelsarrayModels it may open.expires_inintegerSeconds until it stops working.max_sessionsintegerHow many sessions it may hold open at once.max_session_duration_secondsintegerCeiling on each session.Example request
{"models": ["tavus/cvi"], "expires_in": 300, "max_sessions": 1, "max_session_duration_seconds": 600}Example response
{"token": "llmr_sk_live_...", "expires_at": "...", "models": ["tavus/cvi"], "max_sessions": 1}Errors
Errors are {"error": {"message", "type", "code"}}. The ones specific to live avatars:
max_duration_seconds.session_params key or value was refused: unknown key, an avatar or voice that is not public or yours, text too long.persona_id does not name one of your personas.Retry-After is set).Content you send as a prompt, greeting or persona is moderated like any other request. If it is refused you get the same moderation error as the other endpoints.