Skip to main content
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 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:
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.
See Authentication 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.
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.
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:

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:
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:
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.
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:
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.
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:
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:

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.
The schema lists every code.