> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vivix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# World Configuration

Streaming World

Configure the starting conditions of a continuous world once, then guide what happens next with open-ended Events while the session is running.

A create request establishes the world’s premise, optional visual starting point, reusable character or environment references, output preferences, and continuation behavior. It should describe the experience you want the model to sustain—not a frame-by-frame plan for how to produce it.

For runtime guidance, interruption, and lifecycle semantics, continue to [Streaming Control](/streaming-world/control).

<h2 id="world-configuration-session">
  One resource, several configuration blocks
</h2>

A Session is the only top-level REST resource. Your application creates it, reconnects to it when necessary, and closes it when the experience ends. Everything else on this page is embedded configuration for that Session.

| Configuration | What it lets your application do |
| - | - |
| `initial_prompt` | Establish the premise, participants, atmosphere, and continuity expectations. |
| `opening_frame` | Give generation a specific visual point from which to begin. |
| `references` | Name reusable multimodal anchors that later Events can invoke consistently. |
| `output`, `continuation`, and `live_input` | Shape how the experience is delivered, advances, and accepts realtime user input. |

<Note>
  **Configuration is not an entity model.** References and runtime Events belong to a Session, but they are not independently addressable REST resources. Streaming World does not expose character, object, location, scene, or world-state CRUD.
</Note>

<h2 id="world-configuration-starting-world">
  Define the starting world
</h2>

`initial_prompt` is the durable creative context for the session. Describe the world as a whole: who or what matters, where the experience begins, the tone it should maintain, and the continuity that later Events should preserve.

```json Initial prompt theme={null}
{
  "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. Keep their appearances, voices, locations, and prior experience continuous as events unfold."
      }
    ]
  }
}
```

`opening_frame` is optional. Use it when the first image matters—for example, when an experience must open in a particular lobby, composition, or art direction. It establishes a visual starting point; it is not an authoritative snapshot of queryable world state.

<Note>
  **Describe intent, not production steps.** Keep dialogue, behavior, reactions, movement, and presentation together in natural language. Do not pre-split an interaction into lines, actions, shots, or timing fields.
</Note>

<h2 id="world-configuration-references">
  Ground the world with named references
</h2>

A Reference gives a short, stable name to related text, images, or audio. Use one when later Events need to return to the same character, place, object, voice, or visual style without resending its source material.

<Columns cols={2}>
  <Card title={"Image"}>
    Ground appearance, silhouette, wardrobe, environment, object design, or visual style.
  </Card>

  <Card title={"Audio"}>
    Ground a voice, ambience, sound identity, delivery quality, or other audible traits.
  </Card>

  <Card title={"Text"}>
    Add role, temperament, relationships, constraints, or context that media alone cannot express.
  </Card>
</Columns>

The modalities in one Reference are interpreted together. A character reference can therefore combine a portrait, a voice sample, and a short description under one name such as `A`. Runtime Events can then select that anchor and describe the next development in ordinary language.

<Warning>
  **A Reference is an anchor, not an actor object.** Its name helps condition generation; it does not create mutable properties, inventory, coordinates, or a source of truth that your application can read or update.
</Warning>

<h2 id="world-configuration-experience">
  Choose how the experience runs
</h2>

| Block | Guide-level decision |
| - | - |
| `output` | Request an aspect ratio, resolution, and optional caption events that fit the surface where the continuous media will appear. |
| `continuation` | Choose whether generation begins automatically or waits for your application, and bound how long the world may advance without new guidance. |
| `live_input` | Request realtime user input, such as microphone audio, when the experience should react directly to a participant. |

These fields express application intent. The create response contains the effective settings for the allocated Session, so clients should render and enable controls from the returned values rather than assuming every model or region behaves identically.

<h2 id="world-configuration-capabilities">
  Treat capabilities as the session contract
</h2>

Streaming models can differ in the inputs and controls they support. After creating a Session, read its returned capabilities before enabling UI or sending runtime content.

* Only send Event and reference content types that the Session reports as supported.
* Enable live audio, cancellation, hold, resume, or other controls only when advertised.
* Apply the returned Event and reference limits in the client, while still handling server rejection.
* After reconnecting, refresh the effective Session contract instead of relying on stale assumptions.

<Note>
  **Capabilities are authoritative.** A field appearing in the general API schema does not mean that every Session supports it. Unsupported content is rejected rather than silently ignored.
</Note>

<h2 id="world-configuration-create-example">
  Create a configured Session
</h2>

The following request creates a manually started hotel experience with two grounded characters. It is intentionally compact; [Streaming World Sessions](/streaming-world/api-references/sessions) contains the complete request, response, validation, and error schemas.

```bash Create Session theme={null}
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, relationships, and prior experience."
      }]
    },
    "opening_frame": {
      "url": "https://cdn.example.com/hotel/lobby.jpg"
    },
    "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_text", "text": "Friendly on the surface, but tense under pressure." }
        ]
      }
    ],
    "output": {
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "captions": true
    },
    "continuation": {
      "start_mode": "manual",
      "max_idle_ms": 30000
    }
  }'
```

Keep the returned Session id, pass the opaque client connection descriptors to the Vivix client, and use the returned capabilities as the effective feature contract. Then move to [Streaming Control](/streaming-world/control) to start and steer the world.

<Columns cols={2}>
  <Card title={"Continue with Streaming Control"} href={"/streaming-world/control"}>
    Start the world, steer it with Events, and react to its realtime lifecycle.
  </Card>
</Columns>