Skip to main content
A session is one live avatar experience. Submit images and configuration directly, or reuse a saved character. After creation, connect the player to receive video and audio.

1. Create

See Quickstart for the complete single-image request. Provide model, a nonempty avatars array, and an output object. Each avatar needs a nonempty persona describing its identity, speech, movement, and listening behavior; Vivix prepares its behavior automatically. Define avatar_id and source_image_id yourself; each image also needs url and media_type. Add the optional description when you need to clarify the visible person, pose, or scene. A single avatar is selected automatically. A single source image is selected when no default image is set. Omitting session.mode selects video_avatar; omitting delivery selects TRTC. The example explicitly chooses 9:16 at 720p instead of relying on omitted output settings.

2. Read the create response

This illustrates the response structure; use the real returned credentials. control is for the WebSocket connection, while delivery.media is for media. Agora returns agora instead of trtc. Pass data to the player, not the whole response envelope. Keep session_id for reads, closure, and troubleshooting. When present, expires_at gives the effective expiry.

3. Limit session duration

max_duration_seconds sets how long a session can run. The standard default is 20 minutes (1200 seconds). Your workspace’s session-duration limit may set a different duration, including when you omit this field. Check the returned expires_at for the session’s actual expiry.
  • Set a value when your experience needs a specific time limit.
  • Use an integer of at least 4 seconds; 0 is not accepted.
  • A requested duration cannot extend the session beyond your workspace’s limit.
The session ends at its expiry even if the user is still connected. Use auto_close below to end unused sessions sooner.

4. Close unused sessions automatically

Add these top-level fields to the create request. The example allows up to 20 minutes and begins closing after 60 seconds without control connections or 5 minutes without accepted interaction. This prevents sessions from lingering after the user closes the browser, loses their connection, or leaves the experience idle.
  • disconnected_timeout_seconds: omission uses platform configuration; 0 disables it; positive values must be 10–3600 seconds.
  • interaction_idle_timeout_seconds: omitted or 0 means disabled; positive values must be 30–3600 seconds.
  • An explicit positive timeout cannot exceed the effective session duration. Configure both on creation; session.update cannot change them.
Disconnection means all control WebSocket connections are absent, not that the RTC room has no viewers. A ready session that never gets a control connection also starts this timer. Reconnecting before closing begins resets the disconnected timer. Accepted interactions refresh the idle timer, including conversation input, response creation or cancellation, session updates, and adding assets or avatars. User speech also refreshes it, and ongoing user speech prevents an idle close. The avatar speaking, playing long audio, or displaying video does not extend this timer. For a performance, you can disable idle closure while keeping a duration limit and disconnection policy. A timeout triggers cleanup; it does not promise that every resource is released at that exact second. Read auto_close from the response to confirm the effective policy. The final close_reason distinguishes disconnected_timeout from interaction_idle_timeout.

5. Read and close

Call read and close from your server using the API key. Disconnecting from RTC or the WebSocket does not explicitly close the session. Call close when the user stops. The close response data contains session_id and status. closed means closure completed; closing means cleanup is still running and can be checked again; failed means cleanup failed and requires retry or investigation, not that resources were released. Create a new session after closure instead of reusing old credentials. TRTC · Agora · Characters API