Skip to main content
PixVerse R2 Director takes two kinds of text. A world description goes into create_world once. It sets the place, the people, the light, and the mood for every clip. A clip prompt goes into enqueue for each clip. It says what happens next. Both can be up to 2,000 characters. The model uses your prompts as written. When you set enhance_prompt to true, the model first adds more detail to the world description, and then creates the world.

Describe the world once

Write the world as a place you could walk into. Name the location, the people in it, the light, and the mood. Do not say what happens in the world description.
A cook flips noodles, then serves a customer, then closes the stall and walks home.
A rainy neon market at night. A street cook in her fifties works at a noodle stall under a red awning. Wet asphalt reflects the signs. Steam and warm lantern light.
Put the actions that happen in the scene into clip prompts instead. The world is the stage, and each clip is a scene on it. If you give reference images, the description can be short, or you can leave it out. If you give no images, the model builds the world from the description alone.

Choose a style

style sets the style of every clip in the world: Dramatic (the default), Ambient, or POV. POV is a first-person view. A world has one style, and you cannot change it. To try a different style, create a second world.

Cast the world with reference images

create_world takes up to six images of the people, places, and things in the world. The order of the images matters:
  • The first image is the opening image of the world. The first clip of every run opens from it.
  • Each image gets an index. The indexes start at 0 and follow the upload order. From the second clip of a run on, enqueue names images by that index in reference_indexes, first_frame_ref, and last_frame_ref.
Match the shape of the images to your aspect_ratio: wide images for 16:9, tall images for 9:16. Use PNG, JPEG, or WEBP images. Each image can be at most 20 MiB and 40 megapixels.

Write each clip as an action

A clip prompt says what happens in 5 to 10 seconds: the action, and how the view moves. Write the events in the order they play. Put one or two actions in each clip.
The cook flips the noodles, serves two customers, cleans the stall, turns off the lights, and walks away into the rain.
The cook lifts the wok and flips the noodles. Steam rises. Slow push-in toward her hands.
Avoid the word “camera”. The model uses the prompt as written, so “the camera pushes in” can put a camera in the picture. Describe how the view moves instead.
The camera pushes in toward her hands. The camera pans left across the stall.
Slow push-in toward her hands. The view drifts left across the stall.
Set seconds to fit the action. A quick action, like a glance, fits in 5 seconds. A slower one, like a walk down a street, needs up to 10.

Continue, cut, or move between images

By default, the next clip continues from the last frame of the previous clip, and it draws on every reference image. From the second clip of a run on, the reference options choose which images a clip draws on, and which image it opens or ends on: The first clip of a run always opens from the opening image, and it takes none of these options. The model refuses three mistakes with invalid_reference:
  • A nonempty reference_indexes together with a frame reference.
  • An index named twice.
  • An index past the number of images in the world.
Some generation workers cannot build a last_frame_ref. When the worker that builds your clip cannot, the clip fails with unsupported_reference. Queue the clip again without last_frame_ref, or as a cut with first_frame_ref alone.

Plan a run

A run is a series of clips that continue one another. It starts with the first enqueue on a world. Any one of these ends it:
  • You call end_run.
  • The run has nothing to build for idle_seconds.
  • The run reaches max_seconds (1,800 seconds).
  • The session ends.
The next enqueue starts a new run. Its first clip opens from the opening image again. It does not continue from the last frame of the run before. To stay in one run, keep generating clips while a scene plays. Up to 4 clips can be queued or generating at once. Up to 8 clips can be ready or building together. Built clips stay ready after their run ends, so you can still play them.

Common fixes