getToken(), which asks your server for a session token. The Authentication section shows the server side.streetPhotoandportraitPhoto, which areFileobjects from a file picker.- A page with one
<video>element.
Installation and setup
Install the base JavaScript SDK: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 yourrk_ 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.
1. Connect and show the tracks
Connect toreactor/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.
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 callenqueue. 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:
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 sendsclip_started. After the model sends the whole clip, it sends clip_finished. Between clips, the
picture holds on the last frame.
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 afteridle_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.
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, sendattach_world with the
saved world_id. You do not upload the images again. The phase moves to world_ready at once:
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 theerror
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.