Introduction
PixVerse V6 Reference to video casts a clip from pictures you send, up to 7 elements in one request. PixVerse calls this mode Fusion. Each element has a name, one picture and a role: subject for a person, animal, object or product, or background for a place or setting. Write @name in the prompt where each element should appear. Clips run 1 to 15 seconds at 360p to 1080p, in eight aspect ratios. PixVerse reviews prompts and images before generating; requests it declines fail and are not charged.
Choose a PixVerse V6 mode by starting material
| What you have at the start | Mode |
|---|---|
| a written scene | PixVerse V6 Text to video |
| a first frame, and optionally a last frame | PixVerse V6 Image to video |
| photos of people, objects or places to cast from | PixVerse V6 Reference to video (you are here) |
| a clip you want to continue | PixVerse V6 Video extend |
| a prompt or one image, and you want higher picture quality | PixVerse V6 Max |
| one photo and a ready-made themed template, no prompt to write | PixVerse V6 Effects |
Key features & highlights
Name your elements
Give each element a name of 1 to 30 characters and call it with @name in the prompt. In our test maya (a photo of a red-haired woman in a mustard jacket) and trailer (a photo of a chrome travel trailer) became a dusk shot of her walking toward the camera with a steaming enamel mug in front of the trailer, string lights on. Her face, hair and jacket matched the reference and so did the trailer.
Put a space after the name
In our test "@trailer," with a comma right after the name was rejected because the name did not match, while "@trailer and" worked. Failed requests are not charged. Write @name followed by a space.
Subjects and backgrounds
Set role to subject (default) for people, animals, objects and products, or to background for a place. One request can mix up to 7 of them.
Small artifacts happen
In our sample one frame showed a second figure briefly in the doorway. Check the clip before you ship it.
Request parameters
| Parameter | Required | Description |
|---|---|---|
prompt | Yes | Required, 3 to 5,000 characters. Write @name where each element should appear, with a space after it: "@trailer," was rejected in our test and "@trailer and" worked. at least 3 characters ยท at most 5000 characters |
elements | Yes | Required, 1 to 7 items. at least 1 items ยท at most 7 items |
aspect_ratio | No | 16:9 (default), 4:3, 1:1, 3:4, 9:16, 2:3, 3:2 or 21:9. It does not change the price. |
resolution | No | 360p, 540p, 720p (default) or 1080p. Higher resolutions cost more per second. |
duration_seconds | No | Whole seconds, 1 to 15 (default 5). The price is per second. |
generate_audio | No | Off by default. On generates sound with the picture: ambience, effects, music and dialogue written in quotes. Default: |
seed | No | Optional whole number from 0 to 2147483647. Useful to compare one change at a time; it does not guarantee identical frames. |
Pricing
Billed per second of output. The resolution and the audio switch change the price per second; aspect ratio and seed do not. Failed or declined requests are not charged.
| Resolution | Generate audio: No | Generate audio: Yes |
|---|---|---|
| $0.0222 / second | $0.0311 / second |
| $0.0311 / second | $0.04 / second |
| $0.04 / second | $0.0533 / second |
| $0.08 / second | $0.1022 / second |
Use cases
Put a person in a place they were never photographed
A portrait as one element and a photo of a location as a background, with the action written in the prompt.
Keep a vehicle or product consistent
Give a car, a trailer or a product its own element so it matches its photo in every clip you make.
Cast a short scene
Name two or three elements, say how they meet, and add a camera move.
Prompt guide & pro tips
Open with the action, name the elements as you go
Our prompt reads: "At blue hour in the high desert, @maya steps out of the door of @trailer and stretches, then walks toward the camera..." Each @name sits where that element appears in the story.
One clear picture per element
Each element takes one picture of one subject or place. Names should be short and distinct, such as maya and trailer, and every @name needs a space after it: in our test @trailer, with the comma attached was rejected as an unknown name (failed requests are not charged), while @trailer and worked. Mark a setting such as a room, a street or a landscape with role: background, and people, animals, vehicles and products with the default subject, so the model treats the place as the scene rather than as something to put into it.
Compare with a seed
seed keeps runs comparable while you change one thing at a time. It does not guarantee identical frames.
API quick start
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "pixverse/v6/reference-to-video",
"input": {
"prompt": "A slow aerial shot drifting over a misty pine forest at sunrise",
"elements": [
{
"name": "example",
"image_url": "https://example.com/reference.png"
}
],
"resolution": "720p",
"aspect_ratio": "16:9",
"generate_audio": false,
"duration_seconds": 5
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
See the API reference for authentication, the complete schema, polling, and error handling.
