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

> ## Agent Instructions
> To build and serve your own model, start at /deploy/development/quickstart and /deploy/development/overview. Deploying is the default path: reactor init scaffolds a workspace, reactor auth login authenticates, and reactor model deploy registers the model, publishes the release with the weights/ folder, and activates it on Reactor's GPUs, in one command from that workspace. Docker must be running, because the publish step builds the image locally. Bump model.version in reactor.yaml before redeploying a change, because a release that already has an image is reactivated as it is. Deployment access is granted per account, so contact team@reactor.inc if a deploy is refused. Every key in reactor.yaml is documented at /deploy/platform/reactor-yaml. Model code imports reactor_runtime; Python client code imports reactor_sdk. The runtime overview explains the model interface. Running the model on your own machine with reactor run is optional and needs a GPU you attach with --gpus; /deploy/development/local-testing covers that loop and pairs a complete brightness model with a Python client test in a separate brightness-test workspace.
> Reactor hosts multiple models, each with its own connect slug (modelName) and command/event schema. The video model catalog — slug, typed SDK package, and links to its schema — is at /model-api-reference/overview. Robotics policy documentation starts at /robotics/overview; The launch policies are Cosmos Nano DROID (/robotics/cosmos/nano-policy-droid/), DreamZero DROID (/robotics/dreamzero/droid/), and FLUX Action DROID (/robotics/flux-action/droid/), organized by model family and embodiment. Some models expose one slug per experience (e.g. HappyOyster); always take the slug from the model's own pages, never guess it.
> Fastest path to a working app: `npx create-reactor-app my-app --model=<slug>` scaffolds a complete app with secure auth wired up. Typed TypeScript SDKs are published as @reactor-models/<model>; Python uses the base reactor-sdk package.
> Auth: exchange an API key (rk_...) for a JWT via POST https://api.reactor.inc/tokens from your server. Never put the API key in client-side code.
> Append .md to any docs URL for clean Markdown. Search these docs via the MCP server at https://docs.reactor.inc/mcp.

# PixVerse R2 Director schema

> Tracks, session lifecycle, commands, refusals, and messages for PixVerse R2 Director.

This page is the protocol reference for PixVerse R2 Director. It covers the tracks, the session
lifecycle, the commands, the refusals, and the messages. The model streams video on `main_video`.
It has no audio track. When the session reaches `ready`, send commands with
`reactor.sendCommand()`.

## Tracks

| Track | Direction | Type |
| - | - | - |
| `main_video` | Output | Video, 24 fps. 1280 × 720 for a `16:9` world, or 720 × 1280 for `9:16`. |

There are no input tracks. The model gets all its input from commands and uploads.

The track sends nothing before the session's first `play`. After that, it always carries a picture:
the playing clip, or the last frame sent.

## Session lifecycle

A session holds one **world** and at most one open **run** at a time:

* The world is the place where the model makes clips. `create_world` makes one from a description,
  reference images, or both. `attach_world` makes a saved one current.
* A run is a sequence of clips that continue one another. The first `enqueue` on a world starts a
  run. The run ends with `end_run`, after `idle_seconds` with nothing to build, at `max_seconds`
  (1,800 seconds), or when the session ends. The next `enqueue` starts a new run on the same world.
  The first clip of the new run does not continue the picture of the last run.

Two queues hold the clips:

* The **generation queue** holds clips that are `queued` or `generating`. They build in order, and
  each one continues from the last frame of the one before.
* The **playout queue** holds built clips that are `ready` and wait for `play`.

`play` sends the oldest ready clip, or a named one, on `main_video`. `stop` stops it. `set_autoplay`
plays ready clips on their own, oldest first. Built clips stay `ready` after their run ends, so you
can play them at any time.

`session_state.phase` says where the session is:

| Phase | Meaning |
| - | - |
| `idle` | No world. |
| `creating_world` | The model creates the world. This takes 4 to 12 seconds. Clips queued now wait for it. |
| `world_ready` | A world is current, and no clip is `generating`. |
| `starting` | The run waits for generation capacity, then submits the first clip. `wait_position` gives the place in line. |
| `generating` | The run is open, and clips build. |
| `ending` | The run closes. This usually takes under a second. |
| `ended` | The run ended as asked, after `idle_seconds`, or at `max_seconds`. |
| `failed` | The run ended on an error. `last_error` says why. |

Several clients can connect to one session. Each client gets `session_state` when it connects. All
clients see the same snapshot and the same tracks, and each one can send `play` or `stop`. A reply
goes only to the client that sent the command. The other messages go to every client.

## Commands

| Command | Typed method | Description | Reply |
| - | - | - | - |
| `create_world` | `createWorld()` | Create a world from a description, reference images, or both. | none (`session_state` follows) |
| `attach_world` | `attachWorld()` | Make a saved world current. | none (`session_state` follows) |
| `enqueue` | `enqueue()` | Queue one clip of the current world. | `clip_queued` |
| `play` | `play()` | Play the oldest ready clip, or a named one. | none (`clip_started` follows) |
| `stop` | `stop()` | Stop the playing clip. | none (`clip_stopped` follows) |
| `set_autoplay` | `setAutoplay()` | Play ready clips on their own, oldest first. | `autoplay_accepted` |
| `pop` | `pop()` | Remove a `queued` or `ready` clip. | `clip_popped` |
| `end_run` | `endRun()` | End the open run. Built clips stay ready. | `session_state` |
| `get_state` | `getState()` | Read the session state. | `session_state` |

The typed SDK, `@reactor-models/pixverse-r2-director`, has one method for each command on
`PixverseR2DirectorModel` and on the `usePixverseR2Director()` hook. `createWorld`, `attachWorld`,
`play`, and `stop` resolve `undefined`. The other methods resolve their reply message. If the model
refuses the command, they resolve `undefined`. Parameter fields and message fields keep their
snake\_case names. For each uploaded image, pass the `FileRef` that `uploadFile` returns.

### `create_world`

Create the world where the model makes clips, and make it current. Valid in `idle`, `world_ready`,
`ended`, and `failed`. The phase moves to `creating_world`. After 4 to 12 seconds, it moves to
`world_ready`, with `world_id` and `reference_images` set. Clips that you queue in the meantime wait
for the world.

If the model cannot create the world, the previous world stays current. The model sets `last_error`
and fails the clips that waited for the world.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `prompt` | string | `""` | The world: the place, the people in it, the light, and the mood. Up to 2,000 characters. If you give `reference_images`, this is optional. |
| `style` | `"Dramatic"`, `"Ambient"`, `"POV"` | `"Dramatic"` | The style of every clip. `POV` is first person. |
| `aspect_ratio` | `"16:9"` or `"9:16"` | `"16:9"` | The shape of every clip: 1280 × 720 or 720 × 1280. |
| `enhance_prompt` | boolean | `false` | Expand the world description with more detail before the model creates the world. The model always uses clip prompts as written. |
| `reference_images` | upload reference array or null | `null` | Up to 6 images of the people, places, and things in the world. PNG, JPEG, or WEBP, at most 20 MiB and 40 megapixels each. The order of the images is their index, from 0. The first image is the opening image of the world. Give the images the shape that `aspect_ratio` sets. |

Upload each image with `uploadFile()`. Then pass the [`FileRef`](https://docs.reactor.inc/sdk-reference/types#fileref) that
it returns.

```typescript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const street = await reactor.uploadFile(streetPhoto);
const portrait = await reactor.uploadFile(portraitPhoto);

await reactor.sendCommand("create_world", {
  prompt: "A quiet old town street at dusk, with paper lanterns.",
  style: "Dramatic",
  aspect_ratio: "16:9",
  reference_images: [street, portrait], // indexes 0 and 1
});
```

```tsx React theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const { uploadFile, createWorld } = usePixverseR2Director();

const street = await uploadFile(streetPhoto);
const portrait = await uploadFile(portraitPhoto);

await createWorld({
  prompt: "A quiet old town street at dusk, with paper lanterns.",
  style: "Dramatic",
  aspect_ratio: "16:9",
  reference_images: [street, portrait],
});
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
street = await reactor.upload_file("street.jpg")
portrait = await reactor.upload_file("portrait.jpg")

await reactor.send_command("create_world", {
    "prompt": "A quiet old town street at dusk, with paper lanterns.",
    "style": "Dramatic",
    "aspect_ratio": "16:9",
    "reference_images": [street, portrait],
})
```

### `attach_world`

Make a world from an earlier session current, without creating it again. Valid in `idle`,
`world_ready`, `ended`, and `failed`. The phase moves to `world_ready` at once. `reference_images`
is null, because the model does not know how many images the world has.

When the first clip of the next run starts, the model checks the id. If the id is unknown, that run
fails with `last_error` code `world_not_found`, and the model clears `world_id`.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `world_id` | string | none | Required. A `world_id` from `session_state` in an earlier session of this model. |

```typescript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
await reactor.sendCommand("attach_world", { world_id: savedWorldId });
```

```tsx React theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const { attachWorld } = usePixverseR2Director();
await attachWorld({ world_id: savedWorldId });
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
await reactor.send_command("attach_world", {"world_id": saved_world_id})
```

### `enqueue`

Queue one clip of the current world. Valid in every phase except `idle` and `ending`. The model
replies with `clip_queued`.

When the clip is ready, the model sends `clip_generated`. If the model cannot build the clip, it
sends `clip_failed`. A built clip waits for `play`. When autoplay is on, the clip plays on its own.
`set_autoplay` turns autoplay on.

From `world_ready`, `ended`, or `failed`, `enqueue` starts a new run. During `creating_world`, the
clip waits for the world.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `prompt` | string | none | Required. What happens in this clip: the action and the movement of the view. Up to 2,000 characters. The model uses it as written. |
| `seconds` | integer | `5` | The length of the clip in whole seconds, 5 to 10. |
| `metadata` | string | `""` | Your own string, up to 2,000 characters. The model does not read it. It returns the string in every message about this clip. |
| `reference_indexes` | integer array or null | `null` | The reference images of the world that this clip uses, by index from 0. Give each index once. Null uses all of them. An empty list uses none. Do not use it with `first_frame_ref` or `last_frame_ref`. Not for the first clip of a run. |
| `first_frame_ref` | integer or null | `null` | Open this clip on the reference image at this index. The clip does not continue from the previous clip. Alone, this is a cut. With `last_frame_ref`, the clip moves from one image to another. Not for the first clip of a run. |
| `last_frame_ref` | integer or null | `null` | End this clip on the reference image at this index. The clip moves from its first frame to that image. Not for the first clip of a run. |

#### Reference images

Each reference image of a world has an index from 0, in the order that `create_world` received the
images. Image 0 is the opening image of the world. **The first clip of every run opens from image 0,
and that clip takes no reference options.** From the second clip of a run on, `enqueue` can tell the
model how a clip uses the images:

| Options | Effect |
| - | - |
| none | Continue from the last frame of the previous clip, and use every reference image. |
| `reference_indexes: [0, 2]` | Use images 0 and 2 only. |
| `reference_indexes: []` | Use no reference image. |
| `first_frame_ref: 0, last_frame_ref: 2` | Open on image 0 and move to image 2. |
| `first_frame_ref: 1` | Cut: open on image 1 instead of continuing. |

The reference options follow three rules:

* A nonempty `reference_indexes` cannot go with a frame reference.
* Each index is below the `reference_images` count of the world.
* Each index appears once.

If a request breaks a rule, `enqueue` refuses it with `invalid_reference`. For an attached world,
the model does not know the image count. So an index out of range fails that clip instead.

Not every generation worker supports `last_frame_ref`. If the worker cannot build the clip, the clip
fails with `unsupported_reference`.

```typescript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const queued = await reactor.sendCommand("enqueue", {
  prompt: "The street dissolves into her portrait.",
  seconds: 6,
  first_frame_ref: 0,
  last_frame_ref: 1,
});
const clipId = (queued?.data as { clip: { clip_id: string } } | undefined)?.clip.clip_id;
```

```tsx React theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const { enqueue } = usePixverseR2Director();
const queued = await enqueue({
  prompt: "The street dissolves into her portrait.",
  seconds: 6,
  first_frame_ref: 0,
  last_frame_ref: 1,
});
const clipId = queued?.clip.clip_id;
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
queued = await reactor.send_command("enqueue", {
    "prompt": "The street dissolves into her portrait.",
    "seconds": 6,
    "first_frame_ref": 0,
    "last_frame_ref": 1,
})
clip_id = queued["data"]["clip"]["clip_id"]
```

### `play`

Play a `ready` clip on `main_video`. The command plays the clip that `clip_id` names. If `clip_id`
is blank, it plays the oldest ready clip. Valid in any phase, even after the run of the clip ends.

When the first frame goes out, the model sends `clip_started`. After the model sends the whole clip,
it sends `clip_finished`. If `stop` cuts the clip, the model sends `clip_stopped` instead.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `clip_id` | string | `""` | Optional. The `clip_id` of a `ready` clip. Blank plays the oldest one. |

```typescript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
await reactor.sendCommand("play", { clip_id: readyClipId });
await reactor.sendCommand("play", {}); // the oldest ready clip
```

```tsx React theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const { play } = usePixverseR2Director();
await play({ clip_id: readyClipId });
await play({}); // the oldest ready clip
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
await reactor.send_command("play", {"clip_id": ready_clip_id})
await reactor.send_command("play", {})  # the oldest ready clip
```

### `stop`

Stop playing the current clip, or the clip that `play` just asked for. The picture holds on the last
frame sent. The model sends `clip_stopped`, and the status of the clip becomes `stopped`.

```typescript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
await reactor.sendCommand("stop", {});
```

```tsx React theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const { stop } = usePixverseR2Director();
await stop();
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
await reactor.send_command("stop", {})
```

### `set_autoplay`

Choose whether ready clips play on their own, oldest first, when no clip plays. Off by default.
Valid in any phase. The model replies with `autoplay_accepted` and sends `session_state`. This
command never fails.

To play without gaps, wait until a few clips are `ready`, then turn autoplay on.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `enabled` | boolean | `false` | True plays ready clips on their own. False waits for `play`. |

```typescript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
await reactor.sendCommand("set_autoplay", { enabled: true });
```

```tsx React theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const { setAutoplay } = usePixverseR2Director();
await setAutoplay({ enabled: true });
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
await reactor.send_command("set_autoplay", {"enabled": True})
```

### `pop`

Remove a clip that is `queued` or `ready`. Valid in any phase. The model replies with `clip_popped`
and sends `session_state`. The clip becomes `cancelled`. The model does not build a queued clip that
you remove. To remove the playing clip, send `stop` instead.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `clip_id` | string | none | Required. The clip to remove: its `clip_id` from `clip_queued` or `session_state`. |

```typescript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
await reactor.sendCommand("pop", { clip_id: unwantedClipId });
```

```tsx React theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const { pop } = usePixverseR2Director();
await pop({ clip_id: unwantedClipId });
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
await reactor.send_command("pop", {"clip_id": unwanted_clip_id})
```

### `end_run`

End the open run. Valid in any phase. The model replies with `session_state`. Clips that are
`queued` or `generating` become `cancelled`. Built clips stay `ready`, and you can still play them.
The next `enqueue` starts a new run on the same world.

```typescript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
await reactor.sendCommand("end_run", {});
```

```tsx React theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const { endRun } = usePixverseR2Director();
const state = await endRun();
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
await reactor.send_command("end_run", {})
```

### `get_state`

Read the session state. Valid in any phase. The model replies with `session_state`. You rarely need
it, because the model sends `session_state` on connect and on every change.

```typescript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const state = await reactor.sendCommand("get_state", {});
```

```tsx React theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const { getState } = usePixverseR2Director();
const state = await getState();
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
state = await reactor.send_command("get_state", {})
```

## Refusals

When the model refuses a command, nothing changes, and the call fails. Only the client that sent the
command gets the error. The error carries a stable `code` and a `reason` that you can show to your
user. The model never refuses `set_autoplay`, `end_run`, or `get_state`.

| Command | Codes |
| - | - |
| `create_world` | `invalid_input`, `invalid_image`, `busy` |
| `attach_world` | `invalid_input`, `busy` |
| `enqueue` | `invalid_input`, `invalid_reference`, `no_world`, `busy`, `queue_full` |
| `play` | `already_playing`, `no_ready_clip` |
| `stop` | `not_playing` |
| `pop` | `clip_not_found`, `clip_playing`, `clip_not_pending` |

* `invalid_input`: a blank prompt, a world with no description and no image, more than 6 images, or
  a malformed `world_id`.
* `invalid_image`: an image that does not decode, or that is over 20 MiB or 40 megapixels.
* `invalid_reference`: reference options that the world or the clip cannot take. See [Reference
  images](#reference-images).
* `busy`: `create_world` or `attach_world` while the model creates a world or while a run is open,
  or `enqueue` while a run closes.
* `no_world`: `enqueue` before a world is set.
* `queue_full`: `enqueue` when `max_pending_clips` clips are building, or when the ready and
  building clips together reach `max_ready_clips`.
* `already_playing`: `play` while a clip plays. Send `stop` first.
* `no_ready_clip`: `play` when no ready clip matches.
* `not_playing`: `stop` when nothing plays.
* `clip_not_found`: `pop` with an id that is not in this session.
* `clip_playing`: `pop` of the playing clip. Use `stop`.
* `clip_not_pending`: `pop` after the clip is `generating` or done, or at the moment that the model
  sends it for generation. The last case is retryable.

In JavaScript, a refused command resolves `undefined`, and the SDK emits an `error` event with
`operation: "sendCommand"` and the refusal's `code`. A command that has a reply resolves `undefined`
only when the model refuses it. `create_world`, `attach_world`, `play`, and `stop` have no reply, so
they resolve `undefined` on success too. For these four commands, only the `error` event shows a
refusal. In Python, `send_command()` raises a `ReactorError` with the code.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reactor.on("error", (error) => {
  if (error.operation === "sendCommand") showRefusal(error.code, error.message);
});

const queued = await reactor.sendCommand("enqueue", { prompt });
if (queued === undefined) return; // Refused. The error listener has the reason.
```

See [Replies and refusals](https://docs.reactor.inc/sdk-reference/using-the-sdk.md#replies-and-refusals).

### Failures

A failure that no command caused does not refuse a call. Instead, it sets `last_error` on
`session_state`. For a clip, it sets `error_code` on the clip, and the clip arrives in
`clip_failed`. `last_error` has these fields:

| Field | Type | Meaning |
| - | - | - |
| `code` | string | A stable code to branch on, from the table below. |
| `origin` | string | `upstream` (the generation service refused or failed) or `platform` (a failure in Reactor). |
| `reason` | string | A sentence to show. |
| `retryable` | boolean | Whether the same request may work if you try it again. |
| `upstream_code` | string or null | The code from the generation service, if it gave one. |
| `trace_id` | string or null | The id of the request. Give it when you report the failure. |

| Code | When |
| - | - |
| `world_not_found` | An attached `world_id` does not exist for this model. Create the world again. |
| `content_policy` | The generation service declined a prompt or an image. |
| `unsupported_reference` | The generation worker cannot build a `last_frame_ref`. The clip fails. |
| `clip_failed`, `clip_timeout` | The model could not build one clip in time. Queue it again. |
| `upstream_capacity` | No generation capacity. Retryable. |
| `upstream_unavailable`, `upstream_interrupted` | The model cannot reach the generation service, or the service ended the run. Retryable. |
| `upstream_rejected`, `upstream_protocol`, `upstream_auth` | The generation service refused the request, answered unexpectedly, or refused this deployment. |
| `platform_failed` | A failure in Reactor. |

A failed clip leaves the generation queue, and the clips after it still build.

## Messages

| Message | When it arrives | Payload |
| - | - | - |
| `session_state` | On connect, on every change, and in reply to `get_state` and `end_run`. | Session state. |
| `clip_queued` | Reply to `enqueue`. | `clip` |
| `clip_popped` | Reply to `pop`. The clip is now `cancelled`. | `clip` |
| `autoplay_accepted` | Reply to `set_autoplay`. | `enabled` |
| `clip_generated` | A clip is built and `ready`. | `clip` |
| `clip_started` | The first frame of a clip goes out on the tracks. | `clip` |
| `clip_finished` | The model sent the whole clip. The picture holds on its last frame. | `clip` |
| `clip_stopped` | `stop` stopped the playing clip. | `clip` |
| `clip_failed` | The model could not build a clip. The clips after it still build. | `clip`, `reason` |

### `clip` payload

Every clip message carries the whole clip under `clip`, in the same shape as the entries of
`session_state.clips`:

| Field | Type | Meaning |
| - | - | - |
| `clip_id` | string | The UUID that `enqueue` assigned. |
| `prompt` | string | The prompt as you sent it. |
| `metadata` | string | Your `metadata` string, unchanged. |
| `seconds` | integer | The length of the clip. |
| `status` | string | `queued`, `generating`, `ready`, `playing`, `played`, `stopped`, `failed`, or `cancelled`. |
| `error_code` | string or null | Why a `failed` clip failed, for example `content_policy`. Null otherwise. |
| `reference_indexes` | integer array or null | The reference options that you queued the clip with. Each one is null if you did not give it. |
| `first_frame_ref` | integer or null | |
| `last_frame_ref` | integer or null | |

`cancelled` means that `pop` removed the clip, or that its run ended before the model built it.

### `session_state` payload

| Field | Type | Meaning |
| - | - | - |
| `phase` | string | See [Session lifecycle](#session-lifecycle). |
| `world_id` | string or null | The id of the current world. Save it for `attach_world`. |
| `aspect_ratio` | string or null | `16:9` or `9:16`. Null for an attached world until the model builds its first clip. |
| `reference_images` | integer or null | The number of reference images in the world. Null for an attached world. |
| `clips` | array | The clips of the current or last run, oldest first, at most the last 50. A new run starts with an empty list. |
| `pending_clips` | integer | The number of clips that are `queued` or `generating` now. |
| `max_pending_clips` | integer | How many clips can be `queued` or `generating` at once (4). |
| `ready_clips` | integer | Built clips that wait to play, in the order that `play` and autoplay take them. |
| `max_ready_clips` | integer | How many clips can be ready or building at once (8). |
| `autoplay` | boolean | Whether ready clips play on their own. |
| `playing_clip_id` | string or null | The clip playing on the tracks now. |
| `wait_position` | integer or null | In phase `starting`, the place in line for generation capacity, if known. 1 is next. |
| `started_at` | number or null | The Unix time, in seconds, when the current or last run started to generate. |
| `elapsed_seconds` | number | The number of seconds that the current or last run spent in generation. Frozen when the run ends. 0 before it starts. |
| `max_seconds` | integer | How many seconds a run can last before it ends with `end_reason` `max_duration` (1,800). |
| `idle_seconds` | integer | How many seconds an open run waits with no clip `queued` or `generating` before it ends with `end_reason` `idle`. |
| `end_reason` | string or null | Why the last run ended: `ended_by_client`, `idle`, `max_duration`, `start_failed`, `upstream_interrupted`, or `platform_failed`. |
| `last_error` | object or null | Why the last run or world creation failed. See [Failures](#failures). The model clears it when a new run or world creation starts. |

`ended_by_client`, `idle`, and `max_duration` come with phase `ended`. Every other `end_reason`
comes with phase `failed` and a `last_error`.

## Step results

The model keeps every clip as one step of the session, under `/sessions/{id}/steps`. The step of a
built clip holds three files. `output.mp4` is the clip as the track plays it, in H.264.
`last_frame.png` is its last frame. `clip.json` holds the `clip_id`, `prompt`, `metadata`,
`seconds`, and reference options of the clip.

A clip that fails is a failed step. So is a clip that `pop` or the end of its run cancels. The error
of the step says why: `<code>: <reason>` for a failed clip, `cancelled: removed with pop`, or
`cancelled: its run ended (<end_reason>)`.

## Complete example

This example creates a world from a description and queues three clips. When two clips are ready, it
turns on autoplay, so the clips play back to back. The
[tutorial](https://docs.reactor.inc/model-api-reference/pixverse-r2-director/tutorial.md) adds reference images, cuts, and
world reuse.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
import { Reactor } from "@reactor-team/js-sdk";

const reactor = new Reactor({ modelName: "reactor/pixverse-r2-director" });

reactor.on("error", (error) => {
  if (error.operation === "sendCommand") console.error(error.code, error.message);
});

reactor.on("message", async (message) => {
  if (message.type === "clip_failed") {
    console.error((message.data as { reason: string }).reason);
  }
  if (message.type === "session_state") {
    const state = message.data as { ready_clips: number; autoplay: boolean };
    // Let two clips build, then play them back to back.
    if (state.ready_clips >= 2 && !state.autoplay) {
      await reactor.sendCommand("set_autoplay", { enabled: true });
    }
  }
});

reactor.on("statusChanged", async (status) => {
  if (status !== "ready") return;
  await reactor.sendCommand("create_world", {
    prompt: "A quiet old town street at dusk, with paper lanterns.",
    style: "Ambient",
    aspect_ratio: "16:9",
  });
  // These clips wait for the world, then build in order.
  await reactor.sendCommand("enqueue", { prompt: "The view slowly moves down the street." });
  await reactor.sendCommand("enqueue", { prompt: "A lantern seller lights the last lantern." });
  await reactor.sendCommand("enqueue", { prompt: "Night falls over the street.", seconds: 8 });
});

await reactor.connect(await getToken()); // Your server issues the token.
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.