> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vivix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create, manage, and close sessions

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

```text wrap theme={null}
POST /v1/realtime-avatar/sessions
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

See [Quickstart](/streaming-avatar/get-started/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

```json wrap theme={null}
{
  "code": 0,
  "message": "success",
  "data": {
    "session_id": "YOUR_SESSION_ID",
    "status": "active",
    "control": {
      "url": "wss://RETURNED_HOST/v1/realtime-avatar/control?session_id=YOUR_SESSION_ID",
      "client_secret": "SESSION_TOKEN"
    },
    "delivery": {
      "media": {
        "transport": "trtc",
        "trtc": {
          "sdk_app_id": 123456,
          "room_id": "RETURNED_ROOM",
          "user_id": "RETURNED_CLIENT",
          "user_sig": "RETURNED_SIGNATURE",
          "publisher_user_id": "RETURNED_PUBLISHER"
        }
      }
    }
  }
}
```

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

```json theme={null}
{
  "max_duration_seconds": 1200,
  "auto_close": {
    "disconnected_timeout_seconds": 60,
    "interaction_idle_timeout_seconds": 300
  }
}
```

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

```text wrap theme={null}
GET /v1/realtime-avatar/sessions/{session_id}
POST /v1/realtime-avatar/sessions/{session_id}/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](/streaming-avatar/integrate/trtc) · [Agora](/streaming-avatar/integrate/agora) · [Characters API](/streaming-avatar/api-references/characters)