Sessions

A session connects your character configuration to a live conversation and video stream. Create it from an image and a Persona, or reuse a saved character. The response includes the credentials for its WebSocket control channel and RTC media connection.

Create Session

Start with an image, a Persona, and a voice.

Create from Character

Reuse a saved character’s configuration.

Get Session

Check status and effective settings.

List Sessions

Find open sessions in your workspace.

Close Session

End a session and release its resources.

Authentication and responses

Send your Vivix API key as Authorization: Bearer <VIVIX_API_KEY>. REST calls belong on your backend. Responses use the {code, message, data} envelope. code: 0 means success; a nonzero code indicates an error. Session fields are inside data.

Connect and control

Use delivery.media to join the TRTC or Agora room. Connect to control.url with control.client_secret to exchange client events and server events. For a browser, add the credential as the token query parameter:

const controlUrl = new URL(session.control.url);
controlUrl.searchParams.set("token", session.control.client_secret);
const ws = new WebSocket(controlUrl.toString());

Close the session when the user leaves. A close request may return closing; use Get Session to confirm closed. See session management for duration limits and automatic closure.

Persona

Use avatars[].persona to describe each character’s personality, replies, movement, and listening habits. See Write a Persona for examples.

Pipeline configuration

Set pipeline_config when creating the session. It cannot be changed through session.update. The Create Session reference defines its fields; these guides explain when to use each section:

tts_config: choose the voice and speech service.
asr_config: choose the speech recognition service.
llm_config: connect a custom dialogue model or adjust generation settings.
a2a_config: render an avatar from audio generated by your application.
tag_audio_enabled: play short vocal cues before the main answer.

Errors

Code	Meaning	What to do
`10001`, `10003`	Missing or invalid API key	Check the authorization header.
`10004`, `10005`	Billing inactive or insufficient balance	Check your workspace billing.
`10008`	API rate limit exceeded	Honor `Retry-After` and retry with backoff.
`10009`	API access denied	Check your API key’s model and endpoint permissions.
`20004`, `30004`	Invalid request	Check the fields identified in the error response.
`20012`	Missing avatars	Supply at least one avatar.
`20013`	Invalid avatar configuration	Check avatar IDs and the selected active avatar.
`20014`	Missing video output settings	Include `output` in the create request.
`20021` (HTTP 422)	The avatar’s face is too small in the final opening image	Use a closer shot with the full face clearly visible. See the first-image guide.
`20022` (HTTP 422)	The opening image has a solid-color background	Use an image with a background that has some detail. See the first-image guide.
`20005`	Session not found	Check the session ID and whether it has expired.
`30006`	Workspace concurrency limit reached	Close unused sessions or request a higher limit.
`30008`	Model capacity unavailable	Retry with backoff; contact support if it persists.

Overview

A1: Streaming Avatar

W1: Streaming World

Blazing Fast Video Generation