Skip to main content
A Session is one live run. Submit images and configuration directly, or reuse a saved Character. A successful create establishes the session; the user sees video only after the client joins media and receives a frame.

​
1. Create

See Quickstart for the complete single-image request. Provide model, a nonempty avatars array, and an output object for video mode. Define avatar_id and source_image_id yourself; each image also needs url and media_type. The example keeps description to describe the person, pose, and 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 control 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 limits the full session, for example to cap a single experience. Omitting it uses the applicable default duration. Set it explicitly when your experience needs a duration limit, and use the returned expires_at as the effective expiry. An explicit value must be an integer of at least 4. Zero is rejected, not interpreted as unlimited. A server limit may shorten the requested duration; use the returned expires_at.

​
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 a closed browser, network failure, or an abandoned experience.
  • 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. Leaving RTC or closing WebSocket is not an explicit Session close. 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