Sessions

Session endpoints allocate, inspect, reconnect, and close one continuous Streaming World experience. Runtime guidance is sent as open-ended Events over the control channel.

Resource model

A Session is the only top-level REST resource. The other types below are session-scoped inputs or connection records, not separate REST collections.

Type	Address	What an API developer uses it for
`Session`	`session_id`	Allocate a persistent generation runtime, discover its effective capabilities, reconnect clients, inspect operational status, and release resources.
`Reference`	`name` inside one Session	Give related text, images, and audio a reusable name. An Event can select that name instead of sending the same grounding material again.
`Event`	`world_event_id` assigned on the control channel	Describe, in natural language and supported multimodal content, how the unpublished future should develop. Events are not created through a REST endpoint.
Connection descriptor	`control` or `media`	Authorize a client to connect to Vivix control messages or continuous media. Each descriptor is opaque and short-lived.

References are reusable anchors. A Reference has no fixed semantic category. For example, a Reference named A can combine a portrait, an audio sample, and a short description. Events can then use A as a stable conditioning anchor.

REST workflow

Create a Session with POST /v1/streaming-world/sessions and save its session_id.
Read the returned capabilities before enabling runtime controls or sending Event content.
Pass the opaque control and media descriptors to the Vivix client.
Use GET /v1/streaming-world/sessions/{session_id} to recover the current operational snapshot after reconnecting.
Issue fresh descriptors with POST /v1/streaming-world/sessions/{session_id}/client-secrets when client credentials expire.
Close the Session with POST /v1/streaming-world/sessions/{session_id}/close.

Response envelope. All REST responses use {code, message, data}. code = 0 means success; a non-zero code means failure. The fields below refer to values inside data.

Create Session

Creates a Streaming World Session and returns its effective configuration, capability contract, and initial client connection descriptors. POST /v1/streaming-world/sessions

Body Parameters

string

required

Model to run. Use vivix-w1-stream.

string

Client-generated key that prevents duplicate Session allocation. Reuse the same key and identical body after a timeout, HTTP 429, or 5xx response.

object

required

Persistent creative context that establishes the experience before generation starts.

Show properties

array

required

Ordered content blocks. The initial v1 profile accepts one or more input_text blocks.

object

A visual starting point for continuous generation.

Show properties

string

required

HTTPS URL that Vivix can fetch without custom request headers.

string

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

array

Named multimodal anchors available throughout the Session.

Show properties

string

required

Caller-defined name, unique within the Session. Prefer a short stable value that can be selected naturally, such as A, lobby, or red_car.

array

required

One or more supported input_text, input_image, or input_audio blocks interpreted together.

object

Requested continuous output settings.

Show properties

string enum

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

string enum

480p or 720p. Defaults to 720p when supported by the selected model.

boolean

Requests caption events on the control channel. Defaults to false.

object

Optional realtime input accepted from an authorized client.

Show properties

boolean

Requests live audio input. Confirm support through capabilities.live_audio.supported.

boolean

Requests transcription before a completed utterance is interpreted as an Event.

string

A BCP 47 language tag or auto for automatic detection.

object

Controls when generation begins and how long it may continue without new guidance.

Show properties

string enum

manual keeps output held until a client resumes it or creates an Event. automatic begins when the Session is ready. Defaults to manual.

integer

Maximum time generation may continue without a new Event before entering held mode. The model can apply a lower limit.

integer

Requested maximum Session lifetime. The effective expiry can be lower and is returned by the server.

object

Application-defined string keys and values. Metadata is returned with the Session and is not interpreted as generation input.

Content Blocks

Content arrays are ordered. Check capabilities.event_content_types and capabilities.reference_content_types before using a block type at runtime or in a Reference.

object

Natural-language context or guidance.

Show properties

string

Must be input_text.

string

Non-empty UTF-8 text.

object

An image included in a Reference.

Show properties

string

Must be input_image.

string

HTTPS URL that Vivix can fetch without custom request headers.

optional string

Image MIME type.

object

An audio sample included in a Reference.

Show properties

string

Must be input_audio.

string

HTTPS URL that Vivix can fetch without custom request headers.

optional string

Audio MIME type.

optional string

Text associated with the sample when it is known to the application.

Returns

string

Stable identifier for the Session.

string enum

One of provisioning, active, or failed at create time.

object

Opaque descriptor for the Session control connection.

Show properties

string

Vivix control connection URL.

string

Short-lived control credential.

timestamp

Expiration time for this descriptor.

object

Opaque descriptor used by the Vivix client to connect continuous media.

Show properties

string

Vivix media connection URL.

string

Short-lived media credential.

timestamp

Expiration time for this descriptor.

object

Effective output settings, including aspect_ratio, resolution, fps, and captions.

object

Effective feature contract for this allocated Session.

object

Latest operational snapshot, including media status, media time, and applied or pending world Event ids.

timestamp

Session creation time.

timestamp

Time after which the Session can no longer be used.

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",
  "idempotency_key": "hotel-demo-001",
  "initial_prompt": {
    "content": [
      {
        "type": "input_text",
        "text": "A rain-soaked old hotel at night. A is a young detective and B is the hotel owner. Preserve their appearances, voices, positions, relationships, and prior experience as events unfold."
      }
    ]
  },
  "opening_frame": {
    "url": "https://cdn.example.com/hotel/lobby.jpg",
    "mime_type": "image/jpeg"
  },
  "references": [
    {
      "name": "A",
      "content": [
        { "type": "input_image", "url": "https://cdn.example.com/a.jpg" },
        { "type": "input_audio", "url": "https://cdn.example.com/a.wav" },
        { "type": "input_text", "text": "Calm, observant, and concise." }
      ]
    },
    {
      "name": "B",
      "content": [
        { "type": "input_image", "url": "https://cdn.example.com/b.jpg" },
        { "type": "input_audio", "url": "https://cdn.example.com/b.wav" },
        { "type": "input_text", "text": "Friendly on the surface, but tense under pressure." }
      ]
    }
  ],
  "output": {
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "captions": true
  },
  "live_input": {
    "audio": {
      "enabled": true,
      "transcription": true,
      "language": "auto"
    }
  },
  "continuation": {
    "start_mode": "manual",
    "max_idle_ms": 30000
  },
  "max_session_duration_seconds": 3600,
  "metadata": {
    "experience_id": "hotel-demo"
  }
}'

Response

{
  "code": 0,
  "message": "success",
  "data": {
    "session_id": "sws_01K4JH8X9M",
    "status": "active",
    "model": "vivix-w1-stream",
    "control": {
      "url": "wss://api.vivix.ai/v1/streaming-world/control?session_id=sws_01K4JH8X9M",
      "client_secret": "ctl_...",
      "expires_at": "2026-07-24T10:05:00Z"
    },
    "media": {
      "url": "https://media.vivix.ai/connect/sws_01K4JH8X9M",
      "client_secret": "med_...",
      "expires_at": "2026-07-24T10:05:00Z"
    },
    "output": {
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "fps": 24,
      "captions": true
    },
    "live_input": {
      "audio": {
        "enabled": true,
        "transcription": true,
        "language": "auto"
      }
    },
    "continuation": {
      "start_mode": "manual",
      "max_idle_ms": 30000
    },
    "references": [
      { "name": "A" },
      { "name": "B" }
    ],
    "runtime": {
      "media_status": "held",
      "media_time_ms": 0,
      "applied_world_event_id": null,
      "pending_world_event_id": null
    },
    "capabilities": {
      "event_content_types": ["input_text", "input_reference"],
      "reference_content_types": ["input_text", "input_image", "input_audio"],
      "event_handling": ["steer"],
      "live_audio": {
        "supported": true,
        "interpretation": "transcription"
      },
      "runtime_references": false,
      "event_cancel": false,
      "continuation": {
        "hold": true,
        "resume": true,
        "automatic": true
      },
      "reconnect": {
        "snapshot": true,
        "event_replay": false
      },
      "limits": {
        "max_event_bytes": 65536,
        "max_references": 8,
        "max_reference_images": 8
      }
    },
    "metadata": {
      "experience_id": "hotel-demo"
    },
    "created_at": "2026-07-24T10:00:00Z",
    "expires_at": "2026-07-24T11:00:00Z"
  }
}

Capability negotiation

Capabilities are resolved after Vivix validates and allocates the Session. Treat the returned object as the authoritative feature contract rather than assuming that every model or deployment accepts the same inputs.

Field	Meaning	Client requirement
`event_content_types`	Content blocks accepted by runtime Events.	Do not submit a block type that is absent.
`reference_content_types`	Content blocks accepted inside create-time References.	Validate every Reference before creating the Session.
`event_handling`	Handling modes accepted by Event creation.	Use `steer` unless the returned list explicitly enables another mode.
`live_audio`	Whether live audio is supported and how it is interpreted.	Enable microphone controls only when supported.
`runtime_references`	Whether a Reference can be added after Session creation.	When `false`, include every required Reference in the create request.
`event_cancel`	Whether an accepted but unapplied Event can be cancelled by id.	Hide cancellation controls when false.
`continuation`	Available hold, resume, and automatic continuation controls.	Only expose controls whose values are true.
`reconnect`	Snapshot and disconnected-event recovery guarantees.	In v1, `snapshot` is true and `event_replay` is false. Recover from the latest snapshot rather than waiting for missed messages.
`limits`	Effective Event and Reference limits for the Session.	Validate locally and still handle server rejection.

Unsupported content is rejected. Vivix validates an Event or Reference as one input. It does not silently ignore unsupported blocks and apply the remainder.

Get Session

Retrieves lifecycle status, effective configuration, capabilities, and the latest operational snapshot. Use it after reconnecting or while waiting for closure. GET /v1/streaming-world/sessions/{session_id}

Path Parameters

string

required

Identifier of the Session to retrieve.

Returns

Returns the effective Session object. For security, Get Session never returns either client_secret. Use Create Client Secret when a client needs new credentials.

string enum

One of provisioning, active, closing, closed, or failed.

string enum

One of connecting, running, held, stalled, disconnected, or failed.

integer

Latest server-side media time in milliseconds.

optional string

Most recent world Event known to be influencing published media.

optional string

Newest accepted world Event that has not yet taken effect.

integer

Latest control-event sequence included in this snapshot.

Request

curl https://api.vivix.ai/v1/streaming-world/sessions/sws_01K4JH8X9M \
  -H "Authorization: Bearer $VIVIX_API_KEY"

Response

{
  "code": 0,
  "message": "success",
  "data": {
    "session_id": "sws_01K4JH8X9M",
    "status": "active",
    "model": "vivix-w1-stream",
    "control": {
      "url": "wss://api.vivix.ai/v1/streaming-world/control?session_id=sws_01K4JH8X9M",
      "expires_at": "2026-07-24T10:15:00Z"
    },
    "media": {
      "url": "https://media.vivix.ai/connect/sws_01K4JH8X9M",
      "expires_at": "2026-07-24T10:15:00Z"
    },
    "runtime": {
      "media_status": "running",
      "media_time_ms": 84320,
      "applied_world_event_id": "world_event_018",
      "pending_world_event_id": "world_event_019"
    },
    "last_sequence": 142,
    "usage": {
      "generated_video_ms": 84200,
      "generated_audio_ms": 60100
    },
    "capabilities": {
      "event_content_types": ["input_text", "input_reference"],
      "reference_content_types": ["input_text", "input_image", "input_audio"],
      "event_handling": ["steer"],
      "event_cancel": false,
      "reconnect": {
        "snapshot": true,
        "event_replay": false
      }
    },
    "created_at": "2026-07-24T10:00:00Z",
    "expires_at": "2026-07-24T11:00:00Z"
  }
}

Create Client Secret

Issues fresh, short-lived control and media descriptors for an active Session. Call this endpoint from a trusted server and return only the descriptors to the authorized client. POST /v1/streaming-world/sessions/{session_id}/client-secrets

Path Parameters

string

required

Identifier of the active Session.

Body Parameters

string

Client-generated key that makes credential issuance safe to retry.

Returns

string

Identifier of the Session.

object

Fresh opaque descriptor containing url, client_secret, and expires_at.

object

Fresh opaque descriptor containing url, client_secret, and expires_at.

Keep API keys on your server. Client secrets are intentionally short-lived and scoped to one Session. Never expose the workspace API key in a browser or mobile application.

Request

curl -X POST https://api.vivix.ai/v1/streaming-world/sessions/sws_01K4JH8X9M/client-secrets \
  -H "Authorization: Bearer $VIVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "idempotency_key": "refresh-hotel-demo-002"
}'

Response

{
  "code": 0,
  "message": "success",
  "data": {
    "session_id": "sws_01K4JH8X9M",
    "control": {
      "url": "wss://api.vivix.ai/v1/streaming-world/control?session_id=sws_01K4JH8X9M",
      "client_secret": "ctl_...",
      "expires_at": "2026-07-24T10:15:00Z"
    },
    "media": {
      "url": "https://media.vivix.ai/connect/sws_01K4JH8X9M",
      "client_secret": "med_...",
      "expires_at": "2026-07-24T10:15:00Z"
    }
  }
}

Close Session

Stops accepting new Events and begins asynchronous cleanup. Media already published to a client is not withdrawn. Repeating the request with the same idempotency key is safe. POST /v1/streaming-world/sessions/{session_id}/close

Path Parameters

string

required

Identifier of the Session to close.

Body Parameters

string

Client-generated key that makes the close request safe to retry.

Returns

string

Identifier of the closing Session.

string enum

closing while cleanup is in progress or closed if cleanup has already completed.

Request

curl -X POST https://api.vivix.ai/v1/streaming-world/sessions/sws_01K4JH8X9M/close \
  -H "Authorization: Bearer $VIVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "idempotency_key": "close-hotel-demo-001"
}'

Response

{
  "code": 0,
  "message": "success",
  "data": {
    "session_id": "sws_01K4JH8X9M",
    "status": "closing"
  }
}

Session status

Status	Meaning	Client guidance
`provisioning`	Vivix is preparing the runtime and connection descriptors.	Wait for active status before connecting.
`active`	The Session accepts connections and Events.	Connect or continue using the Session.
`closing`	No new Events are accepted and cleanup is in progress.	Poll Get Session only when closure confirmation is required.
`closed`	Cleanup is complete.	Discard credentials and create another Session to continue.
`failed`	The Session cannot continue.	Inspect the error and create another Session when retryable.

Session error cases

Condition	API error code	Retry guidance
A required field is missing, a Reference name is duplicated, or a URL is invalid.	`30004 invalid argument`	Correct the request before retrying.
The selected model does not support the requested output or live input configuration.	`30004 invalid argument`	Remove the unsupported option or select a compatible model.
An idempotency key is reused with a different request body.	`30004 idempotency conflict`	Use the original body or generate a new key.
The Session does not exist, is closed, or has expired.	`20005 not found`	Create another Session.
The API key is missing or invalid.	`10001 missing api key` or `10003 invalid api key`	Correct server authentication before retrying.
Workspace billing is inactive or the balance is insufficient.	`10004 workspace billing is not active` or `10005 insufficient workspace balance`	Resolve the workspace billing issue before retrying.
The request exceeded the API key rate limit.	`10008 API rate limit exceeded`	Honor `Retry-After` and reuse the same idempotency key for the same request.

Error responses use the same {code, message, data} envelope. A non-zero code indicates failure, and message contains an English description.

Overview

A1: Streaming Avatar

W1: Streaming World

Blazing Fast Video Generation

Resource model

REST workflow

Create Session

Body Parameters

Content Blocks

Returns

Capability negotiation

Get Session

Path Parameters

Returns

Create Client Secret

Path Parameters

Body Parameters

Returns

Close Session

Path Parameters

Body Parameters

Returns

Session status

Session error cases

​Resource model

​REST workflow

​Create Session

​Body Parameters

​Content Blocks

​Returns

​Capability negotiation

​Get Session

​Path Parameters

​Returns

​Create Client Secret

​Path Parameters

​Body Parameters

​Returns

​Close Session

​Path Parameters

​Body Parameters

​Returns

​Session status

​Session error cases

Resource model

REST workflow

Create Session

Body Parameters

Content Blocks

Returns

Capability negotiation

Get Session

Path Parameters

Returns

Create Client Secret

Path Parameters

Body Parameters

Returns

Close Session

Path Parameters

Body Parameters

Returns

Session status

Session error cases