Sessions

A session is one continuously generated story. Start it over HTTP, control it over WebSocket, and inspect its final timeline over HTTP.

HTTP responses use the API platform envelope {code, message, data}. The endpoint payload described below is inside data.

Endpoints

Method	Path	Purpose
`POST`	`/v1/streaming-world/sessions`	Start a session.
`GET`	`/v1/streaming-world/sessions/{session_id}`	Read status, final video information, and timeline.
`POST`	`/v1/streaming-world/sessions/{session_id}/stop`	Stop immediately or request a closing.

Create a session

POST /v1/streaming-world/sessions The endpoint prepares the requested assets and opens a video session. A successful response is 201 Created.

Request fields

string

Public model name. Use vivix-w1-stream. If omitted, the service uses the default public model.

string

required

Initial story setup. Include the setting, characters, tone, visual direction, opening action, and continuity rules in natural language.

array

Named session assets. Each item must use exactly one of file_id or url.

Show Asset item

{
  "name": "detective",
  "type": "image",
  "file_id": "file_img_detective",
  "description": "The detective's face and coat"
}

Field	Required	Description
`name`	Yes	Unique name within this session.
`type`	Yes	`image` or `audio`.
`file_id`	One of `file_id` / `url`	Existing uploaded file.
`url`	One of `file_id` / `url`	HTTP or HTTPS source URL.
`description`	No	Short description of how the asset should be used.

object

Optional visual starting point. Upload the image with POST /v1/files/images first, then pass the returned data.url here. The object contains one url field.

string

16:9, 9:16, or 1:1. Defaults to 16:9.

integer

Maximum video time. Defaults to 600 seconds. The current upper bound is 3600 seconds.

object

Initial application state. Use it for numeric values and structured rules that your client needs to display or update. The object must fit within the request size limit.

Example request

curl -X POST https://api.vivix.ai/v1/streaming-world/sessions \\
  -H "Authorization: Bearer $VIVIX_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "vivix-w1-stream",
    "instructions": "A detective investigates a locked room during a storm. Use Chinese dialogue and keep both characters consistent.",
    "opening_image": {"url": "https://static.vivi-x.ai/images/2026/08/03/650665979f5d095f.jpg"},
    "aspect_ratio": "16:9",
    "max_duration_seconds": 120,
    "state": {
      "detective": {"hp": 100},
      "witness": {"hp": 100}
    }
  }'

Example response

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "sw_example",
    "model": "vivix-w1-stream",
    "status": "starting",
    "control": {
      "url": "wss://sw.vivix.ai/v1/streaming-world/sessions/sw_example/control",
      "client_secret": "session_secret_example",
      "expires_at": "2026-10-28T08:00:00Z"
    },
    "assets": []
  }
}

Show Response fields

Field	Description
`id`	Opaque session identifier.
`model`	Public model name selected for the session.
`status`	`starting`, `live`, `ending`, or `ended`.
`control.url`	WebSocket URL for this session.
`control.client_secret`	Session-specific control credential.
`control.expires_at`	Expiration time for the control credential.
`assets`	Opaque `asset_id`, name, and type for prepared assets.

Get a session

GET /v1/streaming-world/sessions/{session_id} Returns the latest persisted session status. Use it after a reconnect or after session.ended to retrieve the final timeline.

Response fields

Field	Description
`id`	Session identifier.
`model`	Public model name.
`status`	Current status.
`ended_reason`	`stopped`, `duration_limit`, `disconnect_timeout`, or `error` when the session ended.
`created_at`	Session creation time.
`ended_at`	End time, when available.
`video.status`	`pending`, `processing`, `completed`, or `failed`.
`video.url`	Present when the completed video is available.
`timeline`	Story entries with video-time positions and descriptions. While an instruction is still being prepared, the service may first play a short transition that continues the current shot without advancing the story; it appears as an entry with no `instruction_id` and the description `过渡`.

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "sw_example",
    "model": "vivix-w1-stream",
    "status": "ended",
    "ended_reason": "stopped",
    "created_at": "2026-10-28T08:00:00Z",
    "ended_at": "2026-10-28T08:02:08Z",
    "video": {"status": "completed", "url": "https://media.vivi-x.ai/videos/sw_example.mp4"},
    "timeline": [
      {
        "start_seconds": 0,
        "end_seconds": 8,
        "instruction_id": "",
        "instruction_text": "",
        "description": "The detective approaches the locked room."
      }
    ]
  }
}

The video object is asynchronous. Treat pending and processing as normal intermediate states and only use video.url when it is present.

Stop a session

POST /v1/streaming-world/sessions/{session_id}/stop The request is accepted with HTTP 202.

Immediate stop

curl -X POST "https://api.vivix.ai/v1/streaming-world/sessions/sw_example/stop" \\
  -H "Authorization: Bearer $VIVIX_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"immediate":true}'

Stop with a closing

{
  "closing": {
    "text": "The detective secures the evidence and leaves the room.",
    "duration_seconds": 8
  }
}

Use the control channel to observe session.ending and session.ended.

HTTP errors

HTTP	`code`	Meaning
`400`	`invalid_request`	Request shape or value is invalid.
`401`	`unauthorized`	The API key or request credential is not valid.
`404`	`not_found`	Session does not exist or is not accessible.
`429`	`concurrency_limit`	Your account cannot start another session right now.
`503`	`capacity_unavailable`	Video capacity is temporarily unavailable. Retry later.
`502`	`upstream_failed`	The session could not be started.
`500`	`internal_error`	The service could not complete the request.

Use the stable code for program logic. Treat message as display text and do not parse it for routing or retry decisions.

Overview

A1: Streaming Avatar

W1: Streaming World

Blazing Fast Video Generation

Endpoints

Create a session

Request fields

Example request

Example response

Get a session

Response fields

Stop a session

Immediate stop

Stop with a closing

HTTP errors