Server Events

Server events are JSON messages emitted on the control WebSocket. Historical events have a numeric id that is monotonic within the session.

Common envelope

Every historical event has this shape:

{
  "id": 42,
  "type": "instruction.started",
  "time": "2026-10-28T08:00:24.123Z"
}

The remaining fields are placed at the same level as id, type, and time.

Field	Meaning
`id`	Event cursor for reconnecting. `state.snapshot` has no historical id.
`type`	Event name.
`time`	Event creation time in RFC 3339 format.

Session lifecycle

`session.ready`

Sent when the opening media is ready to play.

{
  "id": 2,
  "type": "session.ready",
  "time": "2026-10-28T08:00:18.000Z",
  "playback": {
    "type": "hls",
    "url": "https://media.vivi-x.ai/streams/sw_example/master.m3u8"
  },
  "model": "vivix-w1-stream"
}

Start the player from playback.url. The playback URL is for this session; do not construct it yourself.

`session.ending`

Sent when a closing instruction or another terminal condition has started.

{
  "id": 41,
  "type": "session.ending",
  "time": "2026-10-28T08:02:00.000Z",
  "reason": "stopped",
  "estimated_end_seconds": 128.0
}

Stop sending new instructions after this event. A message that arrives after ending begins may be cancelled.

`session.ended`

Sent when the session is terminal.

{
  "id": 47,
  "type": "session.ended",
  "time": "2026-10-28T08:02:08.000Z",
  "reason": "stopped",
  "end_seconds": 128.0
}

Possible reason values are stopped, duration_limit, disconnect_timeout, and error.

Instruction lifecycle

`instruction.received`

{
  "id": 10,
  "type": "instruction.received",
  "time": "2026-10-28T08:00:30.000Z",
  "instruction_id": "ins_001",
  "client_request_id": "choice_001",
  "text": "The detective opens the hidden drawer.",
  "duration_seconds": 10,
  "estimated_start_seconds": 18.0
}

The instruction has passed basic validation and entered the session queue.

`instruction.scheduled`

{
  "id": 11,
  "type": "instruction.scheduled",
  "time": "2026-10-28T08:00:31.000Z",
  "instruction_id": "ins_001",
  "start_seconds": 18.0,
  "end_seconds": 28.0
}

This is a current position estimate on the session video timeline. A later instruction.scheduled event can revise it.

`instruction.started`

{
  "id": 18,
  "type": "instruction.started",
  "time": "2026-10-28T08:00:50.000Z",
  "instruction_id": "ins_001",
  "start_seconds": 18.0
}

The session playback position has reached the instruction’s start.

`instruction.completed`

{
  "id": 26,
  "type": "instruction.completed",
  "time": "2026-10-28T08:01:00.000Z",
  "instruction_id": "ins_001",
  "start_seconds": 18.0,
  "end_seconds": 28.0
}

The session playback position has reached the instruction’s end.

`instruction.cancelled` and `instruction.failed`

{
  "id": 29,
  "type": "instruction.cancelled",
  "time": "2026-10-28T08:01:04.000Z",
  "instruction_id": "ins_002",
  "reason": "session_ending"
}

{
  "id": 30,
  "type": "instruction.failed",
  "time": "2026-10-28T08:01:05.000Z",
  "instruction_id": "ins_003",
  "reason": "preparation_failed"
}

A failed or cancelled instruction does not apply state changes tied to its start or end.

Asset events

`assets.added`

{
  "id": 34,
  "type": "assets.added",
  "time": "2026-10-28T08:01:10.000Z",
  "client_request_id": "asset_002",
  "assets": [
    {"asset_id":"asset_hidden_photo","name":"hidden_photo","type":"image"}
  ]
}

`assets.failed`

{
  "id": 35,
  "type": "assets.failed",
  "time": "2026-10-28T08:01:11.000Z",
  "client_request_id": "asset_003",
  "error": {"code":"asset_preparation_failed","message":"could not prepare the requested assets"}
}

State events

`state.updated`

Sent when one or more state changes become effective. The state object is the complete current state.

{
  "id": 38,
  "type": "state.updated",
  "time": "2026-10-28T08:01:20.000Z",
  "state": {
    "characters": {
      "detective": {"hp": 85, "location": "warehouse"}
    },
    "clue_count": 1
  },
  "changes": [
    {
      "op": "set",
      "path": ["characters", "detective", "hp"],
      "value": 85,
      "instruction_id": "ins_001"
    }
  ],
  "media_seconds": 28.0
}

changes can include client_request_id and/or instruction_id for correlation. It does not include internal processing source information.

`state.snapshot`

Returned only to the connection that sent state.get. It is not part of the event history and has no id.

{
  "type": "state.snapshot",
  "time": "2026-10-28T08:01:22.000Z",
  "client_request_id": "state_read_001",
  "state": {"clue_count": 1},
  "media_seconds": 28.0,
  "last_event_id": 38
}

`error`

Errors are returned on the control channel as events and include the request id when one was supplied.

{
  "id": 45,
  "type": "error",
  "time": "2026-10-28T08:01:40.000Z",
  "client_request_id": "state_004",
  "error": {
    "code": "invalid_request",
    "message": "invalid state update"
  }
}

Use error.code for application behavior. Messages are short user-facing explanations and may change.

Ordering and reconnects

Process historical events in ascending id order.
Save the last processed id after handling an event.
Reconnect with ?last_event_id=<id> to receive events after that cursor.
Use state.snapshot.last_event_id to align a point-in-time state read with later events.
Unknown event types should be ignored safely so a client can remain forward compatible.

Overview

A1: Streaming Avatar

W1: Streaming World

Blazing Fast Video Generation

Common envelope

Session lifecycle

`session.ready`

`session.ending`

`session.ended`

Instruction lifecycle

`instruction.received`

`instruction.scheduled`

`instruction.started`

`instruction.completed`

`instruction.cancelled` and `instruction.failed`

Asset events

`assets.added`

`assets.failed`

State events

`state.updated`

`state.snapshot`

`error`

Ordering and reconnects

Common envelope

Session lifecycle

session.ready

session.ending

session.ended

Instruction lifecycle

instruction.received

instruction.scheduled

instruction.started

instruction.completed

instruction.cancelled and instruction.failed

Asset events

assets.added

assets.failed

State events

state.updated

state.snapshot

error

Ordering and reconnects

`session.ready`

`session.ending`

`session.ended`

`instruction.received`

`instruction.scheduled`

`instruction.started`

`instruction.completed`

`instruction.cancelled` and `instruction.failed`

`assets.added`

`assets.failed`

`state.updated`

`state.snapshot`

`error`