Introduction
Wan 3.0 Pro Prime Reference to video locks a face, a garment, a set, a movement or a voice with image, video and audio references and renders the shot at 1080p, 2K or 4K for 2 to 30 seconds on the Prime render. At least one of reference_image_urls (1 to 10 ordered images), reference_video_urls, reference_audio_urls (up to 5 clips each), reference_file_url (one document) or reference_link_url (one web page) is required. Name each reference in the prompt, or the model averages them into a subject that matches none of them.
Choose a Wan 3.0 Pro Prime mode by starting material
| What you have at the start | Mode |
|---|---|
| a written scene or script | Wan 3.0 Pro Prime Text to video |
| an approved opening image | Wan 3.0 Pro Prime Image to video |
| separate visual, motion, or sound references | Wan 3.0 Pro Prime Reference to video |
Key features & highlights
Two characters in one shot
The two-character example sends two plates and labels them: "The first image is the woman, the second is the man — keep both faces and both haircuts." They stand on either side of a workbench in a dim garage under one hanging bulb, 6 seconds at 1080p with seed 220913 and room tone only. It is the pattern for keeping a couple consistent across an episode.
A set plate with no people
References do not have to be people. The set-continuity example sends one plate of a boxing gym — ropes, lockers, a single hanging light — and asks for an empty frame with dust drifting through the beam and the bulb swinging slowly, locked camera, 5 seconds at 4k with audio off. Every shot in a sequence can then share the same room.
Movement referenced instead of written
Image, video and audio references can go in together, so movement can come from a clip rather than a paragraph. Reference videos are MP4 or MOV, at least 16 fps, 1 to 15 seconds each and 15 seconds in total; their seconds are billed with the output, and reference video plus output stays within 30 seconds.
Request parameters
| Parameter | Required | Description |
|---|---|---|
prompt | No | Optional, but this is where the references are separated from one another — which plate is which character, what the video and the audio are for — and the action is stated. at least 1 characters · at most 20000 characters |
reference_image_urls | No | 1 to 10 images for identity, wardrobe and set plates. Name each one in the prompt — character, garment, set — or they are averaged together. at least 1 items · at most 10 items |
reference_video_urls | No | Up to 5 clips, each 1 to 15 seconds and 15 seconds in total. Use them for movement and camera style rather than for a face. at least 1 items · at most 5 items |
reference_audio_urls | No | Up to 5 clips, each 1 to 15 seconds and 15 seconds in total — a voice, a line reading or room tone the shot has to match. Reference audio is not billed. at least 1 items · at most 5 items |
reference_file_url | No | One document the model reads before it directs the shot: a character sheet, a script, a shot list or a product brief. |
reference_link_url | No | One public web page the model reads for reference, such as an article, a product page or a character profile. It must open without a login. |
resolution | No | 1080p, 2k or 4k, default 1080p. |
aspect_ratio | No | 16:9, 4:3, 1:1, 3:4, 9:16 or adaptive. Defaults to adaptive, which lets the model choose; name a ratio when the delivery format is fixed. |
duration_seconds | No | Any whole number from 2 to 30, default 5, or -1 for smart duration, which reserves the maximum and settles on the length actually delivered. |
generate_audio | No | On by default. Sound is generated with the picture and arrives inside the same file. Default: |
enable_prompt_expansion | No | On by default on this family. It fills out thin briefs and rewrites detailed ones, so turn it off once your prompt is a precise shot description. Default: |
seed | No | 0 to 2147483647. Fix it while you tune resolution or duration, otherwise every rerun changes two things at once. |
Pricing
Reference videos add to the billed seconds; reference images and audio do not. Because we cannot measure your clips before the job runs, we hold funds for the 15-second maximum up front and release the unused portion the moment the job settles — you are only ever charged for the seconds actually used.
| Specification | Price |
|---|---|
| $0.234 / second |
| $0.252 / second |
| $0.279 / second |
Use cases
A costume across several stages
The dancer example carries one performer and one layered chiffon costume into a third stage, with the follow spot now behind her so the fabric goes translucent as she turns through it. The references carry the dancer and the garment, so the prompt describes only the new lighting set-up, and translucent fabric under backlight leaves almost nothing to hide behind at a large delivery size.
Master files that get recut
Render a reference-locked hero shot at 4K in 16:9, then crop a 9:16 cutdown and a square banner out of the same master. Reference plates plus a fixed seed keep the cast identical across every derivative in the set.
Prompt guide & pro tips
Label by position
reference_image_urls is an ordered list, so refer to "the first image" and "the second image" and supply them in that order. Say for each one whether it is a character, a garment or a set; use video for movement and camera style and audio for a voice, a line reading or room tone. Reference images and audio are not billed.
Hold everything except the change
For a sequence, keep the plates, the seed and the prompt skeleton identical and change only the action or lighting line. Turn enable_prompt_expansion off — it defaults to true on this family — so the labels you wrote are not rewritten.
Check reference lengths before you submit
Video and audio reference limits are enforced during generation rather than when the task is accepted, so a clip over the limit is caught later instead of at submission. Measure clips first, keep reference video plus duration_seconds at 30 seconds or less, and explore at 1080p before rendering at 4K.
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": "alibaba/wan-3.0-pro-prime/reference-to-video",
"input": {
"aspect_ratio": "adaptive",
"duration_seconds": 5,
"reference_image_urls": [
"https://example.com/reference.png"
],
"resolution": "1080p"
}
}'
# 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.
