Server Events

Server events are JSON messages emitted on the Streaming World control connection. They report Session state, the lifecycle of submitted World Events, media progress, captions, usage, and errors. Every message uses the common envelope below.

Forward compatibility. Vivix may add event types, fields, and enum values over time. Ignore values you do not recognize, retain the fields you need, and use the Session capabilities to decide which optional operations are available.

Common envelope

string

Server-generated unique identifier for this message.

string

Event discriminator, such as session.ready or event.applied.

integer

Monotonically increasing position in this Session’s server-event stream.

integer

Unix timestamp in milliseconds when the server created the event.

optional string

The client event_id that caused this message, when the event is a direct result of a client command.

Two different identifiers. event_id identifies this server message. request_event_id correlates it with a client command. world_event_id, used by the domain Event lifecycle below, identifies the durable steering intent created by event.create.

Ordering and reconnects

Process messages in ascending sequence order. A gap means the client no longer has a complete live view, but sequence is not a replay cursor. After a control connection reconnects, the service sends session.snapshot instead of replaying missed messages. Treat the snapshot sequence as the new baseline. A snapshot is a compact control-state view, not a transcript or a semantic description of everything that has happened in the world. Applications that need a durable audit trail should persist events while the connection is live.

Which event should I listen to?

Need	Listen to
Know the control connection is ready.	`session.ready`
Restore control state after reconnecting.	`session.snapshot`
Know a World Event passed admission.	`event.accepted`
Know a World Event first affected outgoing media.	`event.applied`
Know newer steering replaced the active frontier.	`event.superseded`
Render live or final captions.	`caption.delta` and `caption.completed`
Monitor running, held, stalled, or failed media.	`media.state.updated`
Monitor cumulative billable generation.	`usage.updated`

Session: session.ready, session.snapshot, session.closing, session.closed
World Event: event.accepted, event.applied, event.superseded, event.cancelled, event.failed
Media: media.state.updated
Caption: caption.delta, caption.completed
Usage: usage.updated
Error: error

Session Events

Connection readiness, reconnect state, and terminal Session transitions.

session.ready

Emitted once after a new control connection is established and the Session can accept client events. A reconnect receives session.snapshot instead.

"session.ready"

Event type.

object

Current Session identity and state.

Show properties

string

Session identifier.

"active"

Current REST Session lifecycle status.

object

Current outgoing media state.

Show properties

Current media state.

integer

Current Session media time in milliseconds.

session.ready

{
  "event_id": "evt_server_001",
  "type": "session.ready",
  "sequence": 1,
  "created_at": 1784899200123,
  "session": {
    "session_id": "sws_01K4JH8X9M",
    "status": "active"
  },
  "media": {
    "state": "connecting",
    "media_time_ms": 0
  }
}

session.snapshot

Emitted after a control connection reconnects. It supplies the current control baseline; events missed while disconnected are not replayed.

"session.snapshot"

Event type.

object

Current Session identity and state.

Show properties

string

Session identifier.

"active" | "closing"

Current non-terminal Session status.

object

Current outgoing media state.

Show properties

Current media state.

integer

Current Session media time in milliseconds.

object

Current World Event pointers.

Show properties

nullable string

Most recently applied World Event, if any.

nullable string

Accepted World Event awaiting application, if any.

Snapshot only. Use this state to resume control. Do not infer the missing lifecycle or caption messages from the pointer values.

session.snapshot

{
  "event_id": "evt_server_214",
  "type": "session.snapshot",
  "sequence": 214,
  "created_at": 1784899256123,
  "session": {
    "session_id": "sws_01K4JH8X9M",
    "status": "active"
  },
  "media": {
    "state": "running",
    "media_time_ms": 48620
  },
  "steering": {
    "applied_world_event_id": "world_event_002",
    "pending_world_event_id": null
  }
}

session.closing

Emitted when shutdown has begun. Stop sending new client events and continue reading until session.closed or the connection ends.

"session.closing"

Event type.

string

Session being closed.

string

Shutdown reason, such as client_request, idle_limit, or service_shutdown.

session.closing

{
  "event_id": "evt_server_301",
  "type": "session.closing",
  "sequence": 301,
  "created_at": 1784899310450,
  "session_id": "sws_01K4JH8X9M",
  "reason": "client_request"
}

session.closed

Emitted when the Session reaches its terminal state. No further client event can affect this Session. The final cumulative usage is included for reconciliation.

"session.closed"

Event type.

string

Closed Session identifier.

string

Terminal shutdown reason.

object

Final cumulative generated media usage.

Show properties

integer

Total generated video duration in milliseconds.

integer

Total generated audio duration in milliseconds.

session.closed

{
  "event_id": "evt_server_302",
  "type": "session.closed",
  "sequence": 302,
  "created_at": 1784899310820,
  "session_id": "sws_01K4JH8X9M",
  "reason": "client_request",
  "usage": {
    "generated_video_ms": 81240,
    "generated_audio_ms": 79820
  }
}

World Event Lifecycle

These messages describe the lifecycle of the domain Event submitted with event.create. They use world_event_id so the domain identifier cannot be confused with the common-envelope event_id.

There is no event.completed. A World Event is an open-ended steering intent. Its influence may continue until newer steering takes over, so semantic completion would be misleading.

event.accepted

Emitted after event.create passes validation and admission. The service has taken responsibility for processing the World Event, but outgoing media has not necessarily changed.

"event.accepted"

Event type.

string

The event_id of the accepted event.create client message.

string

Server-assigned identifier for the World Event.

event.accepted

{
  "event_id": "evt_server_120",
  "type": "event.accepted",
  "sequence": 120,
  "created_at": 1784899230105,
  "request_event_id": "evt_world_020",
  "world_event_id": "world_event_020"
}

event.applied

Emitted when the first media causally influenced by the World Event enters the server-side outgoing media path. This is the earliest stable application boundary exposed by the API.

What applied does not mean. It does not confirm that a viewer rendered the media, that every requested development occurred, or that the Event stopped influencing the world.

"event.applied"

Event type.

string

The event_id of the event.create client message.

string

World Event that first affected outgoing media.

object

Server-observed application boundary.

Show properties

integer

Session media time at which the first influenced media entered the outgoing path.

event.applied

{
  "event_id": "evt_server_127",
  "type": "event.applied",
  "sequence": 127,
  "created_at": 1784899231440,
  "request_event_id": "evt_world_020",
  "world_event_id": "world_event_020",
  "effective_at": {
    "media_time_ms": 18420
  }
}

event.superseded

Emitted when a newer World Event takes over the active steering frontier. If the older Event was already applied, its published consequences remain part of Session history.

No rollback. Superseding changes the unpublished future. It does not withdraw published media, erase established continuity, or make the world forget prior consequences.

"event.superseded"

Event type.

string

The event_id of the newer client command that caused the transition.

string

World Event that lost the active frontier.

string

Newer World Event that took over steering.

boolean

Whether the superseded World Event had already crossed its application boundary.

object

Boundary where newer steering took over.

Show properties

integer

Session media time for the transition.

event.superseded

{
  "event_id": "evt_server_148",
  "type": "event.superseded",
  "sequence": 148,
  "created_at": 1784899236740,
  "request_event_id": "evt_world_021",
  "world_event_id": "world_event_020",
  "by_world_event_id": "world_event_021",
  "was_applied": true,
  "effective_at": {
    "media_time_ms": 23580
  }
}

event.cancelled

Emitted when event.cancel successfully removes a pending, unapplied World Event. Cancellation is available only when the Session advertises the corresponding capability.

Applied Events cannot be cancelled. Once influence has entered outgoing media, send a newer World Event to redirect what happens next.

"event.cancelled"

Event type.

string

The event_id of the successful event.cancel client message.

string

World Event removed before application.

event.cancelled

{
  "event_id": "evt_server_165",
  "type": "event.cancelled",
  "sequence": 165,
  "created_at": 1784899240120,
  "request_event_id": "evt_cancel_022",
  "world_event_id": "world_event_022"
}

event.failed

Emitted when an accepted World Event cannot reach its application boundary. Validation and admission failures that occur before a World Event exists use the generic error event instead. After event.applied, later Session or media problems are reported through media.state.updated or error; they do not retroactively fail the World Event.

"event.failed"

Event type.

string

The event_id of the original event.create client message.

string

Accepted World Event that could not be applied.

object

Structured error details.

Show properties

string

Broad error category, such as invalid_request_error or server_error.

string

Stable, machine-readable error code.

string

Human-readable diagnostic message.

optional string

Related request field, when known.

boolean

Whether retrying after correcting transient conditions can succeed.

event.failed

{
  "event_id": "evt_server_171",
  "type": "event.failed",
  "sequence": 171,
  "created_at": 1784899242350,
  "request_event_id": "evt_world_023",
  "world_event_id": "world_event_023",
  "error": {
    "type": "server_error",
    "code": "event_application_failed",
    "message": "The accepted World Event could not be applied.",
    "retryable": true
  }
}

Media Events

State transitions for the Session’s outgoing media.

media.state.updated

Emitted when outgoing media changes state. A transition caused by session.hold or session.resume includes the triggering request_event_id; autonomous transitions may omit it.

"media.state.updated"

Event type.

object

Updated media state.

Show properties

New media state.

optional string

State immediately before this transition.

integer

Current Session media time in milliseconds.

optional string

Machine-readable reason for the transition.

media.state.updated

{
  "event_id": "evt_server_190",
  "type": "media.state.updated",
  "sequence": 190,
  "created_at": 1784899249870,
  "request_event_id": "evt_hold_001",
  "media": {
    "state": "held",
    "previous_state": "running",
    "media_time_ms": 33120,
    "reason": "client_hold"
  }
}

Caption Events

Incremental and final caption text aligned to Session media time.

caption.delta

Emitted as caption text becomes available. Append deltas with the same caption_id in sequence order to render low-latency text.

"caption.delta"

Event type.

string

Identifier shared by all messages for this caption.

string

Text fragment to append.

integer

Approximate Session media time at which the caption begins.

caption.delta

{
  "event_id": "evt_server_201",
  "type": "caption.delta",
  "sequence": 201,
  "created_at": 1784899252010,
  "caption_id": "caption_014",
  "delta": "I knew there was",
  "start_media_time_ms": 35640
}

caption.completed

Emitted with the authoritative final text for a caption. Replace any locally assembled deltas for the same caption_id with text.

"caption.completed"

Event type.

string

Completed caption identifier.

string

Authoritative final caption text.

integer

Approximate Session media start time for the caption.

integer

Approximate Session media end time for the caption.

caption.completed

{
  "event_id": "evt_server_204",
  "type": "caption.completed",
  "sequence": 204,
  "created_at": 1784899253150,
  "caption_id": "caption_014",
  "text": "I knew there was more to your story.",
  "start_media_time_ms": 35640,
  "end_media_time_ms": 38220
}

Usage Events

Cumulative generated-media usage for metering and live cost displays.

usage.updated

Emitted periodically as generated-media usage changes. Values are cumulative for the Session and may grow independently. Replace the previous totals; do not add updates together.

"usage.updated"

Event type.

object

Current cumulative generated-media usage.

Show properties

integer

Cumulative generated video duration in milliseconds.

integer

Cumulative generated audio duration in milliseconds.

usage.updated

{
  "event_id": "evt_server_220",
  "type": "usage.updated",
  "sequence": 220,
  "created_at": 1784899258420,
  "usage": {
    "generated_video_ms": 51240,
    "generated_audio_ms": 49820
  }
}

Error Events

Request-level and Session-level errors that do not belong to an accepted World Event.

error

Emitted when client validation, Session control, or service processing fails. Most errors do not close the Session. If an accepted World Event specifically fails before application, the service emits event.failed instead.

"error"

Event type.

optional string

The client event_id that caused the error, when applicable.

object

Structured error details.

Show properties

string

Broad error category, such as invalid_request_error or server_error.

string

Stable, machine-readable error code.

string

Human-readable diagnostic message.

optional string

Related request field, when known.

boolean

Whether retrying after correcting transient conditions can succeed.

error

{
  "event_id": "evt_server_231",
  "type": "error",
  "sequence": 231,
  "created_at": 1784899261220,
  "request_event_id": "evt_cancel_030",
  "error": {
    "type": "invalid_request_error",
    "code": "event_not_cancelable",
    "message": "The World Event has already been applied.",
    "param": "world_event_id",
    "retryable": false
  }
}

Overview

A1: Streaming Avatar

W1: Streaming World

Blazing Fast Video Generation

Common envelope

Ordering and reconnects

Which event should I listen to?

Session Events

session.ready

session.snapshot

session.closing

session.closed

World Event Lifecycle

event.accepted

event.applied

event.superseded

event.cancelled

event.failed

Media Events

media.state.updated

Caption Events

caption.delta

caption.completed

Usage Events

usage.updated

Error Events

error

​Common envelope

​Ordering and reconnects

​Which event should I listen to?

​Session Events

​session.ready

​session.snapshot

​session.closing

​session.closed

​World Event Lifecycle

​event.accepted

​event.applied

​event.superseded

​event.cancelled

​event.failed

​Media Events

​media.state.updated

​Caption Events

​caption.delta

​caption.completed

​Usage Events

​usage.updated

​Error Events

​error

Common envelope

Ordering and reconnects

Which event should I listen to?

Session Events

session.ready

session.snapshot

session.closing

session.closed

World Event Lifecycle

event.accepted

event.applied

event.superseded

event.cancelled

event.failed

Media Events

media.state.updated

Caption Events

caption.delta

caption.completed

Usage Events

usage.updated

Error Events

error