Discord

← API reference

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

ParameterTypeDescription
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

ParameterTypeDescription
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 object

POST/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 object

Transcripts

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

ParameterTypeDescription
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

ParameterTypeDescription
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 object

POST/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

ParameterTypeDescription
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.jpg

Example 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

ParameterTypeDescription
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 object

DELETE/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

ParameterTypeDescription
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

ParameterTypeDescription
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

ParameterTypeDescription
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 object

PATCH/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 object

DELETE/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

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

codeHTTPMeaning
insufficient_credits402Your balance cannot cover the hold for this session. Top up, or lower max_duration_seconds.
max_duration_exceeds_host_limit400Asked for longer than the model allows.
invalid_session_params400A session_params key or value was refused: unknown key, an avatar or voice that is not public or yours, text too long.
persona_not_found400persona_id does not name one of your personas.
concurrency_limit429Too many sessions open for your organization. End one, then retry (Retry-After is set).
host_capacity429The host has no capacity right now. Retry shortly.
host_unavailable502The model is temporarily unavailable on our side. Not your fault; retry later.
custom_avatars_unavailable503Custom avatars cannot be created right now (see Avatars).
unsupported_model400That call is not supported for the model you named.

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.