Client Events

Client events are JSON messages sent on the Streaming World WSS control connection. Use event.create to guide what happens next, event.cancel to cancel guidance that has not yet been applied, and Session events to control whether the world advances.

One open-ended Event. Keep dialogue, behavior, reactions, movement, ambience, and presentation together in natural language. The API does not expose separate speakers, lines, actions, beats, scenes, shots, tracks, or state patches.

Common event envelope

Every client message has a client-generated event_id and a type. A successful WebSocket write only means the message left your process. Wait for the corresponding server event before treating the request as accepted or effective.

string

A non-empty id generated by the client and unique within the Session. Reuse it when retrying the same message after an uncertain delivery result.

string

One of event.create, event.cancel, session.hold, or session.resume.

Two different ids. The envelope event_id identifies this client message. The world_event_id returned by event.accepted identifies the open-ended Event inside the world. Use the latter in later lifecycle messages and cancellation requests.

Idempotent retries. Repeating the same event_id with the same payload does not apply the request twice and returns the original disposition. Reusing an id with a different payload returns idempotency_conflict.

Forward compatibility. Ignore server event types and fields you do not recognize. Unknown client event types and unsupported enum values return an error event.

Event: event.create, event.cancel
Session: session.hold, session.resume

World Events

event.create

Creates one open-ended Event that steers the unpublished future of the running world. Its ordered content blocks may select named References and describe a multi-character or environmental development as one coherent intent. The entire Event is validated atomically. The server first responds with event.accepted and a world_event_id. Later event.applied reports when the first influenced media enters the outgoing path. An accepted Event is not necessarily visible yet, and an applied Event is not semantically complete.

string

Client-generated message id used for correlation and idempotent retries.

"event.create"

Must be event.create.

object

The open-ended guidance to apply to the world.

Show properties

array

One or more ordered content blocks. Every block must be listed in capabilities.event_content_types. If one block is invalid or unsupported, no world Event is created.

Show properties

object

Natural-language guidance for what should happen next.

Show properties

"input_text"

Must be input_text.

string

A non-empty instruction. It can describe several participants and an extended interaction without assigning individual lines or actions.

object

Selects a named Reference declared at Session creation. A Reference is a conditioning anchor, not an entity or mutable world-state record.

Show properties

"input_reference"

Must be input_reference.

string

The exact name of an immutable Session Reference, such as A or hotel_lobby.

capability-gated object

A runtime image input. Use it only when input_image is listed in capabilities.event_content_types.

Show properties

"input_image"

Must be input_image.

string

An HTTPS URL for an image directly fetchable by Vivix.

optional string

Image MIME type, such as image/jpeg or image/png.

capability-gated object

A runtime audio input. Use it only when input_audio is listed in capabilities.event_content_types.

Show properties

"input_audio"

Must be input_audio.

string

An HTTPS URL for an audio file directly fetchable by Vivix.

optional string

Audio MIME type, such as audio/wav or audio/mpeg.

optional string

A caller-supplied transcript that helps interpret speech in the audio.

"steer"

Must be steer. Vivix preserves committed media, prepares a coherent continuation, and redirects unpublished future media at a safe boundary. The value must also appear in capabilities.event_handling.

No queue or rollback. There is no enqueue or after-current mode because an open-ended Event has no reliable completion boundary. Steer does not retract media that is already committed, published, or buffered, and it does not promise a frame-accurate cut.

event.create

{
  "event_id": "evt_world_020",
  "type": "event.create",
  "event": {
    "content": [
      { "type": "input_reference", "name": "A" },
      { "type": "input_reference", "name": "B" },
      {
        "type": "input_text",
        "text": "A notices that B keeps one hand hidden below the counter and begins to test his story. B first pretends not to understand, then accidentally reveals too much. Let the exchange develop naturally. Preserve both characters’ identities, voices, positions, and prior experience."
      }
    ],
    "handling": "steer"
  }
}

event.cancel

Cancels an accepted world Event before it becomes effective. Send this event only when capabilities.event_cancel is true. The server confirms success with event.cancelled.

Cancellation is not undo. After event.applied, the Event has already entered media history and cannot be cancelled. Send a newer Event to redirect what happens next.

string

Client-generated message id used for correlation and idempotent retries.

"event.cancel"

Must be event.cancel.

string

The domain Event id returned by event.accepted. If it has already been applied when this request is processed, the server returns event_not_cancelable.

event.cancel

{
  "event_id": "evt_cancel_world_020",
  "type": "event.cancel",
  "world_event_id": "world_event_020"
}

Session Events

session.hold

Requests that the world stop advancing at a safe media boundary while preserving the Session and its continuity. The server reports the effective result with media.state.updated where state is held and request_event_id matches this client message. A hold may allow already committed media to finish. It retains the last available visual output and does not erase prior Event influence.

string

Client-generated message id used for correlation and idempotent retries.

"session.hold"

Must be session.hold.

session.hold

{
  "event_id": "evt_session_hold_001",
  "type": "session.hold"
}

session.resume

Requests that a held Session continue from its existing continuity. The server reports the effective result with media.state.updated where state is running and request_event_id matches this client message. Creating a new world Event while held also requests an implicit resume.

string

Client-generated message id used for correlation and idempotent retries.

"session.resume"

Must be session.resume.

session.resume

{
  "event_id": "evt_session_resume_001",
  "type": "session.resume"
}

Request errors

A request rejected before admission produces an error server event with the triggering request_event_id. An Event that was accepted but cannot later be applied produces event.failed instead.

Code	Meaning
`invalid_request`	The JSON shape, required fields, or field values are invalid.
`unsupported_event_content`	At least one content block is not supported by this Session.
`unsupported_event_handling`	The requested handling value is not advertised by this Session.
`reference_not_found`	An input_reference name does not exist in this Session.
`world_event_not_found`	The cancellation target does not exist in this Session.
`event_not_cancelable`	Cancellation is unsupported or the world Event has already been applied.
`session_not_ready` / `session_closed`	The Session cannot accept the requested control message in its current lifecycle state.
`idempotency_conflict`	The same client event_id was reused with a different payload.

Overview

A1: Streaming Avatar

W1: Streaming World

Blazing Fast Video Generation

Common event envelope

World Events

event.create

event.cancel

Session Events

session.hold

session.resume

Request errors

​Common event envelope

​World Events

​event.create

​event.cancel

​Session Events

​session.hold

​session.resume

​Request errors

Common event envelope

World Events

event.create

event.cancel

Session Events

session.hold

session.resume

Request errors