Introduction
Wan 3.0 Prime Reference to video builds a 2 to 30 second shot on the Prime render from up to ten image, five video and five audio references, with the same fields as Wan 3.0 Reference to video. At least one reference array, a reference file or a web link must be present and the prompt is optional; when you write one, it should say what each reference controls. Resolution is 480p, 720p or 1080p, default 720p, and aspect_ratio defaults to 16:9.
Choose a Wan 3.0 Prime mode by starting material
| What you have at the start | Mode |
|---|---|
| a written scene or script | Wan 3.0 Prime Text to video |
| an approved opening image | Wan 3.0 Prime Image to video |
| separate visual, motion, or sound references | Wan 3.0 Prime Reference to video |
Key features & highlights
One identity plate, a whole scene from text
A single plate can carry the person while the prompt invents everything else. The dune example uses one identity image shot flat on a plain studio background; the moonlit dune field, the wind and a scarf several metres long streaming above her are all written. The scarf still has to be attached to the same arm at the end of the take, which makes it a good thing to check.
Camera behaviour borrowed from a clip
Reference video is for movement and camera style rather than faces. The motion-style example takes a slow handheld orbit from a reference clip and applies it to the woman from a reference image, standing in an empty studio, for 6 seconds at 720p. Reference clips must be MP4 or MOV, at least 16 fps, 1 to 15 seconds each and 15 seconds in total.
Voice continuity from audio references
Up to five WAV or MP3 audio references, 15 seconds in total, can hold a voice across takes. A presenter who looks continuous but sounds different between shots is still discontinuous, so when a person speaks in more than one shot, send the same audio reference every time. Reference audio and reference images are not billed.
Request parameters
| Parameter | Required | Description |
|---|---|---|
prompt | No | Optional. When you write one, name what each reference controls, then the shot: subject, one action, one camera move, light and sound. at least 1 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. |
aspect_ratio | No | 16:9, 9:16, 1:1, 4:3, 3:4 or adaptive, which lets the model choose. Defaults to 16:9. |
enable_thinking | No | Has the model think through the brief and any reference material before generating. It helps with dense documents, web pages and complex reference images, and makes the run slower. Default: |
resolution | No | 480p, 720p or 1080p. Defaults to 720p. |
duration_seconds | No | Any whole number from 2 to 30, or -1 for smart duration. Defaults to 5. |
generate_audio | No | On by default. The clip comes back with sound already locked to the picture. Default: |
enable_prompt_expansion | No | Off by default. When on, the prompt is rewritten before generation, which helps thin briefs and fights you on detailed ones. |
seed | No | 0 to 2147483647. Hold it steady to compare one changed field at a time; drop it for variety. |
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.0612 / second |
| $0.126 / second |
| $0.252 / second |
Use cases
A recurring presenter
Keep the same image plates for face and set, and the same audio reference for the voice, in every request of a series. The presenter example keeps "the same presenter, the same studio" and describes only the move — a push that ends on a specific framing — because identity is already carried by the references.
Style-matched inserts
When a new shot has to move the way an existing one does, supply that clip as a motion reference and an image for the subject. State in the prompt which is which, as the motion-style example does: "Take the camera behaviour from the reference clip — a slow handheld orbit — and apply it to the woman in the reference image."
Prompt guide & pro tips
Budget reference video against output length
Reference video seconds are billed with the output, and reference video plus duration_seconds cannot pass 30 seconds. A 6-second style clip therefore leaves room for up to 24 seconds of output. Reference limits are enforced during generation rather than on submission, so trim clips before you send them.
Keep the face on an image, not a video
A reference video sets motion style well but is a poor way to pin a face. Put identity on an image plate, name it in the prompt, and use video only for how the camera or the body moves.
Hold the reference set steady between takes
Change one reference or one line of the prompt per attempt and hold seed, so a difference can be traced to its cause. Settle the look at 5 seconds and 720p before extending, and check face, costume and voice against their references at the start and end of every render.
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-prime/reference-to-video",
"input": {
"aspect_ratio": "16:9",
"duration_seconds": 5,
"prompt": "A slow aerial shot drifting over a misty pine forest at sunrise",
"reference_image_urls": [
"https://example.com/reference.png"
],
"resolution": "720p"
}
}'
# 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.
