W1: Streaming World

Streaming World lets an application start a continuously generated story and steer what happens next while the video is playing. You use three public surfaces:

Surface	Purpose
HTTP	Start, inspect, and stop a session.
WebSocket	Send story instructions, add references, update world state, and receive progress events.
HLS playback	Play the video returned when the first playable media is ready.

Start with one session

A session contains one continuous story. Create it with a natural-language setup, then keep the returned id and control object.

Upload the image material

Upload an image to your workspace first. Keep both file_id and url from the response. The file_id is used for named assets; the returned url is used by opening_image.

curl -X POST https://api.vivix.ai/v1/files/images \\
  -H "Authorization: Bearer $VIVIX_API_KEY" \\
  -F "file=@locked-room.jpg"

{
  "code": 0,
  "message": "success",
  "data": {
    "file_id": "file_img_locked_room",
    "file_type": "image",
    "mime_type": "image/jpeg",
    "url": "https://static.vivi-x.ai/images/2026/08/03/650665979f5d095f.jpg"
  }
}

For an audio asset, use the matching upload endpoint and keep the returned file_id:

curl -X POST https://api.vivix.ai/v1/files/audios \
  -H "Authorization: Bearer $VIVIX_API_KEY" \
  -F "file=@witness-voice.wav"

Create the session

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. Keep the detective and the witness visually consistent, use Chinese dialogue, and begin outside the room.",
    "aspect_ratio": "16:9",
    "max_duration_seconds": 120
  }'

Connect the control channel

Use the control.url and the session-specific control.client_secret to open the WebSocket. The secret is only for this session; keep it private.

Load the player

Wait for session.ready. Its playback.url is an HLS address. Give that URL to an HLS-capable player and start playback.

Create request

{
  "model": "vivix-w1-stream",
  "instructions": "A detective investigates a locked room during a storm. Keep the detective and the witness visually consistent, use Chinese dialogue, and begin outside the room.",
  "opening_image": {
    "url": "https://static.vivi-x.ai/images/2026/08/03/650665979f5d095f.jpg"
  },
  "assets": [
    {
      "name": "detective",
      "type": "image",
      "file_id": "file_img_detective",
      "description": "The detective's face and coat"
    },
    {
      "name": "witness_voice",
      "type": "audio",
      "file_id": "file_aud_witness",
      "description": "The witness's voice reference"
    }
  ],
  "aspect_ratio": "16:9",
  "max_duration_seconds": 120,
  "state": {
    "characters": {
      "detective": {"hp": 100, "location": "outside the room"},
      "witness": {"hp": 100, "location": "inside the room"}
    },
    "clue_count": 0
  }
}

Field	Required	Description
`model`	No	Public model name. Use `vivix-w1-stream`. If omitted, the service uses the default public model.
`instructions`	Yes	The initial story setup. Describe the world, characters, tone, point of view, opening action, and any rules that should remain consistent.
`opening_image.url`	No	The `url` returned by `POST /v1/files/images`. The opening image is fetched from that uploaded file.
`assets`	No	Named image and audio references that the story may use later. A reference becomes available after the session is created successfully.
`aspect_ratio`	No	`16:9`, `9:16`, or `1:1`. Defaults to `16:9`.
`max_duration_seconds`	No	Maximum video time for the session. Defaults to 600 seconds; the current upper bound is 3600 seconds.
`state`	No	A JSON object for application state such as health, score, location, inventory, or quest progress.

Generation details are selected by the service. There is no public inference-parameter object in this API.

References and opening images

An opening image answers “where should the story begin visually?” A named asset answers “which image or sound should later story segments refer to?” They are different inputs and can be used together. Assets can be registered before the first frame or added during playback. A session asset pool may be larger than the number of references used in one generated segment. The service selects the references needed for each segment; applications should use stable names and descriptions so the story can refer to them naturally. Each asset uses exactly one source:

Source	Example
Existing file	`{"file_id":"file_img_detective"}`
Direct URL	A public HTTP(S) URL. The examples on this page use the upload response instead.

The public response contains an opaque asset_id, name, and type. It does not return source URLs or storage details.

Initial state and numeric rules

Use state for values that your application needs to display or enforce. For example, a fighting game can start with both characters at 100 health points, then attach a state update to an instruction that describes a hit. The service sends the full current state in every state.updated event. Your client can replace its local copy with that object instead of trying to reconstruct state from individual changes.

The state object is application data. The service does not infer your schema. If you use hp, keep the path and value type consistent in every update.

Response

Successful creation returns HTTP 201:

{
  "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": [
      {"asset_id": "asset_detective", "name": "detective", "type": "image"}
    ]
  }
}

Response field	Use
`data.id`	Use it to query or stop the session.
`data.status`	Usually `starting` first, then `live`, `ending`, or `ended`.
`data.control.url`	WebSocket endpoint for this session.
`data.control.client_secret`	Secret for the control connection. Do not expose it in logs or URLs that other users can access.
`data.assets`	The opaque asset identifiers available to later instructions.

What happens next

The service prepares the opening media.
The control channel emits session.ready with an HLS playback URL.
Your client starts the player and listens for instruction and state events.
New instructions affect future story content; already published video is not rewritten.

Continue with Streaming Control, or use the complete Sessions reference.

Complete example

const createResponse = await fetch(
  "https://api.vivix.ai/v1/streaming-world/sessions",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.VIVIX_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "vivix-w1-stream",
      instructions: "A detective investigates a locked room during a storm. Use Chinese dialogue and keep the characters consistent.",
      aspect_ratio: "1:1",
      max_duration_seconds: 120,
      state: {
        detective: { hp: 100, location: "hallway" },
        witness: { hp: 100, location: "room" }
      }
    })
  }
);

const envelope = await createResponse.json();
const session = envelope.data;
console.log(session.id, session.status);

Overview

A1: Streaming Avatar

Blazing Fast Video Generation

W1: Streaming World

Start with one session

Create request

References and opening images

Initial state and numeric rules

Response

What happens next

Complete example