> ## 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 tutorial

> Connect, create a world from images, queue clips that continue and cut, play them, reuse the world, and handle refusals.

This tutorial uses the base JavaScript SDK, so you can see each model command. It creates a world
from two reference images. Then it queues clips that continue from one to the next and cut between
the images. It plays the clips and reuses the world in a later session. The snippets build on each
other in one browser module.

Your app supplies three things that this page does not show:

* `getToken()`, which asks your server for a session token. The [Authentication](#authentication)
  section shows the server side.
* `streetPhoto` and `portraitPhoto`, which are `File` objects from a file picker.
* A page with one `<video>` element.

## Installation and setup

Install the base JavaScript SDK:

```shell theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
npm install @reactor-team/js-sdk
```

To start from a complete example app instead, run
`npx create-reactor-app my-director-app --model=pixverse-r2-director`.

## How PixVerse R2 Director works

A session holds one world and one run at a time. `create_world` or `attach_world` sets the world.
`enqueue` queues a clip of it. The first `enqueue` starts a run. The clips of one run continue one
another. A built clip waits as `ready` until `play` sends it on `main_video`, or until autoplay
plays it.

A command reply only tells you that the model accepted the request. To know when a clip is built or
plays, wait for the messages that follow, such as `clip_generated` and `clip_started`. The
`session_state` snapshot always agrees with them, so mirror it to draw your UI.

## Authentication

Create the session token on your server so that your `rk_` API key never reaches the browser. This
route exchanges the key for a short-lived token that can only start `reactor/pixverse-r2-director`
sessions. The Python SDK exchanges the key for you, so it needs no route.

```typescript app/api/token/route.ts theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
import { NextResponse } from "next/server";

export async function POST() {
  const response = await fetch("https://api.reactor.inc/tokens", {
    method: "POST",
    headers: {
      "Reactor-API-Key": process.env.REACTOR_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      authorization_details: [
        { type: "session", resources: { models: { match: ["reactor/pixverse-r2-director"] } } },
      ],
    }),
  });
  if (!response.ok) {
    return NextResponse.json({ error: await response.text() }, { status: response.status });
  }
  const { jwt, expires_at } = await response.json();
  return NextResponse.json({ jwt, expires_at }, { headers: { "Cache-Control": "no-store" } });
}
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
import asyncio
import os
from reactor_sdk import Reactor

async def main():
    reactor = Reactor(model_name="reactor/pixverse-r2-director", api_key=os.environ["REACTOR_API_KEY"])
    await reactor.connect()  # The SDK exchanges the key for a token.

asyncio.run(main())
```

See [Authentication](https://docs.reactor.inc/authentication.md) for token lifetimes and for how to keep a token fresh for a
whole session.

## 1. Connect and show the tracks

Connect to `reactor/pixverse-r2-director`. Attach `main_video` to the video element. The model has
no audio track. The track sends nothing until the first `play`, so the video element stays blank
for now.

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

const reactor = new Reactor({ modelName: "reactor/pixverse-r2-director" });
const video = document.querySelector("video")!;

reactor.on("trackReceived", (name, _track, stream) => {
  if (name === "main_video") {
    video.srcObject = stream;
    void video.play().catch(console.error);
  }
});

let lastRefusal: ReactorError | undefined;
reactor.on("error", (error) => {
  if (error.operation === "sendCommand") lastRefusal = error;
});

type SessionState = {
  phase: string;
  world_id: string | null;
  ready_clips: number;
  autoplay: boolean;
  end_reason: string | null;
  last_error: { code: string; reason: string; retryable: boolean } | null;
};
let state: SessionState | undefined;
reactor.on("message", (message) => {
  if (message.type === "session_state") state = message.data as SessionState;
});

await reactor.connect(await getToken());
```

If the browser blocks autoplay, connect from a user action such as a button click. Wait for
the `ready` status before you send commands. When you connect, the model sends a `session_state`
with phase `idle`.

## 2. Create a world from reference images

Upload the images. Then create the world. The upload order gives the image index: the street is
image 0, and the portrait is image 1. Image 0 is the opening image of the world, so the first clip
of every run opens from it.

```typescript 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],
});
```

`create_world` declares no reply, so the call resolves `undefined` whether the model accepted it or
refused it. A refusal, such as `invalid_image`, arrives on the `error` event. On success, the phase
moves to `creating_world`. Then it moves to `world_ready`, with `world_id` set.

You do not need to wait for `world_ready` before you queue clips. Clips that you queue now wait for
the world. When `world_id` arrives, save it, because step 6 reuses it:

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
function waitForPhase(phase: string): Promise<SessionState> {
  return new Promise((resolve) => {
    const onMessage = (message: { type: string; data: unknown }) => {
      if (message.type !== "session_state") return;
      const next = message.data as SessionState;
      if (next.phase !== phase) return;
      reactor.off("message", onMessage);
      resolve(next);
    };
    reactor.on("message", onMessage);
  });
}

const worldReady = waitForPhase("world_ready");
```

## 3. Queue clips that continue and cut

Register one message listener before you call `enqueue`. The listener records the result of every
clip. If a result arrives before you start to wait, you do not lose it. The `waitForClip` helper
then waits for one clip to be ready or to fail:

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
type ClipResult = { ok: true } | { ok: false; reason: string };
const results = new Map<string, ClipResult>();
const waiters = new Map<string, (result: ClipResult) => void>();

reactor.on("message", (message) => {
  if (message.type !== "clip_generated" && message.type !== "clip_failed") return;
  const data = message.data as { clip: { clip_id: string }; reason?: string };
  const result: ClipResult =
    message.type === "clip_generated"
      ? { ok: true }
      : { ok: false, reason: data.reason ?? "The clip could not be built." };
  results.set(data.clip.clip_id, result);
  waiters.get(data.clip.clip_id)?.(result);
});

async function waitForClip(clipId: string): Promise<void> {
  const result =
    results.get(clipId) ??
    (await new Promise<ClipResult>((resolve) => waiters.set(clipId, resolve)));
  waiters.delete(clipId);
  if (!result.ok) throw new Error(result.reason);
}

function clipIdOf(reply: { data: unknown } | undefined): string {
  const clipId = (reply?.data as { clip: { clip_id: string } } | undefined)?.clip.clip_id;
  if (!clipId) throw new Error(lastRefusal?.message ?? "The model refused this command.");
  return clipId;
}
```

Now queue three clips. The first clip of a run opens from image 0 and takes no reference options.
The second clip continues from the last frame of the first clip. The third clip opens on image 0 and
moves to the portrait, image 1:

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const first = clipIdOf(
  await reactor.sendCommand("enqueue", {
    prompt: "The view slowly moves down the street as the lanterns light up.",
    metadata: "opening",
  }),
);
const second = clipIdOf(
  await reactor.sendCommand("enqueue", {
    prompt: "A lantern seller looks up and smiles.",
    seconds: 6,
  }),
);
const third = clipIdOf(
  await reactor.sendCommand("enqueue", {
    prompt: "The street dissolves into her portrait.",
    first_frame_ref: 0,
    last_frame_ref: 1,
  }),
);

const firstReady = waitForClip(first);
```

The `clip_queued` reply means that the clip is in the generation queue. It does not mean that the
clip is built. If the model refuses a request, the call resolves `undefined`, and the `error` event
carries the code, such as `queue_full` or `invalid_reference`. At most 4 clips can be queued or
generating at once.

Not every generation worker can build a `last_frame_ref`. If the third clip fails with
`unsupported_reference`, queue it again with `first_frame_ref: 0` alone. That clip cuts to the
street without the move.

## 4. Play the clips

Wait for the first clip. Then play it. When the first frame goes out, the model sends
`clip_started`. After the model sends the whole clip, it sends `clip_finished`. Between clips, the
picture holds on the last frame.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
await worldReady;
await firstReady;
await reactor.sendCommand("play", { clip_id: first });
```

If you play each clip as soon as it is ready, playback can have gaps.

Let the next clips build. Then turn on autoplay so that ready clips play back to back:

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

To cut the playing clip, send `stop`. To remove a clip that you no longer want, send `pop` with its
`clip_id`. This works only while the clip is `queued` or `ready`.

## 5. End the run

A run ends on its own after `idle_seconds` with nothing to build, or at `max_seconds`. To end the
run now, send `end_run`. The model cancels the clips that are still queued or generating. Built
clips stay `ready`, so autoplay still plays them.

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

The next `enqueue` starts a new run on the same world. The first clip of the new run opens from
image 0 again. It does not continue from the last clip of this run.

## 6. Reuse the world in a later session

The world stays available after the session ends. In a new session, send `attach_world` with the
saved `world_id`. You do not upload the images again. The phase moves to `world_ready` at once:

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
const savedWorldId = (await worldReady).world_id!;
// Later, in a new session of the same model:
await reactor.sendCommand("attach_world", { world_id: savedWorldId });
await reactor.sendCommand("enqueue", { prompt: "Night falls over the street." });
```

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

For an attached world, the model does not know the image count. So the model cannot refuse an index
out of range at `enqueue`. The clip fails instead.

Watch `session_state` for a run that ends on its own:

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reactor.on("message", (message) => {
  if (message.type !== "session_state") return;
  const next = message.data as SessionState;
  if (next.phase === "ended" && next.end_reason === "idle") {
    // Nothing was queued for idle_seconds. The next enqueue starts a new run.
  }
  if (next.phase === "failed" && next.last_error) {
    const { code, retryable } = next.last_error;
    // world_not_found: create the world again. A retryable code: enqueue again.
  }
});
```

## Surfacing refusals

A refused command fails its own call. Only your client gets the refusal. Read it from the `error`
event whose `operation` is `"sendCommand"`. Show it next to the control that sent the command. Do
not show it as a connection problem, because the session is still connected.

With a clip failure, the model accepted the request but could not build the clip. The model sends
`clip_failed` with a `reason`, and the status of the clip becomes `failed`. The clips after it still
build.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reactor.on("error", (error) => {
  // error.code is the model's code, such as "queue_full".
  if (error.operation === "sendCommand") showRefusal(error.code, error.message);
});

reactor.on("message", (message) => {
  if (message.type === "clip_failed") showClipFailure((message.data as { reason: string }).reason);
});
```

The [schema](https://docs.reactor.inc/model-api-reference/pixverse-r2-director/schema.md#refusals) lists every code.


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