Introduction
Wan 2.6 Reference to video casts people, animals or objects from one to three short clips into a new scene you describe. The clips supply who or what appears; location, action, camera and light all come from the prompt. The result runs any whole number of seconds from 2 to 10, at 720p or 1080p, in one of five aspect ratios, as one continuous take or a multi-shot edit. The call is alibaba/wan-2.6/reference-to-video and it is asynchronous: create the task, then poll or take the callback.
Up to two still images can join the clips, or replace them, in the same request; together with the clips that is five references at most. Stills are numbered after the clips, so with two clips the first image is character3, and they are not billed.
Choose a Wan 2.6 mode by starting material
| What you have at the start | Mode |
|---|---|
| a written scene or script | Wan 2.6 Text to video |
| an approved opening image | Wan 2.6 Image to video |
| separate visual, motion, or sound references | Wan 2.6 Reference to video |
Key features & highlights
Subjects travel, the setting is written
The reference clips decide who or what appears, and the prompt decides where they are, what they do and how the camera and light treat them. That is the difference from image-to-video, where the opening frame also fixes the set, the light and the proportions. Here, a presenter filmed once can be placed on a rooftop at dusk, in a different shape, without a second shoot.
Up to three clips in one scene
Send one clip when a single subject has to stay recognisable, or up to three when a scene needs several at once. Refer to the clips in the prompt by the order you sent them and say what each contributes, so the model knows which one is the presenter and which one is the dog. Busy clips with several people make it harder to know who should be cast.
Shape and size are parameters, not inherited
aspect_ratio is chosen per request: 16:9, 9:16, 1:1, 4:3 or 3:4, all available at both resolutions. 720p returns 1280×720, 720×1280, 960×960, 1088×832 or 832×1088; 1080p returns 1920×1080, 1080×1920, 1440×1440, 1632×1248 or 1248×1632. Nothing is taken from the reference footage, so a vertical delivery does not require vertical source clips, and one set of references can be delivered in several shapes.
Request parameters
| Parameter | Required | Description |
|---|---|---|
prompt | Yes | The new scene: say what each reference clip contributes, then setting, action, camera and light. Keep it under 1,500 characters. at least 1 characters · at most 1500 characters |
negative_prompt | No | What must not appear: extra people, captions, props from the reference clip you do not want carried over. at most 1500 characters |
reference_video_urls | No | Up to three clips of the characters or objects to cast. at least 1 items · at most 3 items |
reference_image_urls | No | Up to two still images of characters or objects to cast, alongside the clips or instead of them; with the clips a request takes at most five references. at least 1 items · at most 2 items |
aspect_ratio | No | 16:9, 9:16, 1:1, 4:3 or 3:4, default 16:9, available at both resolutions, and each combination has fixed pixel dimensions listed in the specs. |
resolution | No | 720p or 1080p, default 720p. It sets the per-second rate and how long the task takes, and both resolutions accept all five aspect ratios. |
duration_seconds | No | Any whole number from 2 to 10, default 5. |
shot_type | No | single keeps one continuous take; multi lets the model cut between shots within the same scene. |
seed | No | 0 to 2147483647. Hold it while swapping one reference clip at a time so the random draw stays constant and the thing you changed is the only thing moving. |
Pricing
Reference clips add to the billed seconds. Because we cannot measure your clips before the job runs, we hold funds for the 5-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.065 / second |
| $0.0975 / second |
Use cases
Recast a presenter into a new location
One clip of the person, then a prompt for the room, the light and the camera move. The presenter's look comes from the reference while the set is written, so a single shoot can supply footage for locations that were never available on the day.
Put a product into seasonal staging
Send the packshot turn you already have and describe a new surface, a new season, a new light. The object keeps its shape and finish while the scene around it is rebuilt, so one product clip can serve several campaign settings without restaging the shot.
Bring two subjects together
A clip of a presenter and a clip of the animal or object that has to share the frame, then a prompt saying what each of them does. It resolves scenes that would otherwise need both subjects on set on the same day.
Reuse footage you cannot reshoot
An archive clip of a presenter who is no longer available, or a product sample that has gone back to the client, still carries the subject. Send it as the reference and write the new setting: the old footage supplies the subject, the prompt supplies the scene.
Prompt guide & pro tips
Pick clips the model can read
Short footage where the subject is large in frame, well lit and seen from more than one angle transfers best. A subject that stays small or backlit tends to come back only approximately. Trim before you upload rather than after: the seconds you send are billable, and the few seconds where the subject is clearest usually transfer better than a long take that wanders.
Write the scene, not the reference
Name what each clip contributes first, such as the woman from clip 1 and the dog from clip 2, then describe setting, action, camera and light the way you would for text-to-video, within 1,500 characters. Re-describing what the footage already shows spends that budget and sometimes competes with the clips. Use negative_prompt for what keeps turning up and should not: extra people, on-screen captions, or a prop from the reference clip that keeps following the subject into the new scene.
Budget the seconds before you submit
Billable seconds are the output duration plus the combined length of the reference clips, each rounded up to whole seconds, with the reference side counted up to five seconds in total. A 5-second render with one 3-second reference is billed as 8 seconds at the rate of the chosen resolution; the same render with three clips adding up to nine seconds is billed as 10, because only five reference seconds count. The live estimate before submitting shows the amount, and if a clip's length cannot be read in advance the estimate assumes five seconds and the final charge uses the measured length.
Adapt the included example
Start from the published example using aspect_ratio: 16:9, duration_seconds: 5, resolution: 720p and one clip in reference_video_urls. Replace the subject and the staging while keeping that input contract intact.
Keep character1, the amber glass bottle, exactly - its shape, colour and the marble block it stands on. Move it to a sunlit kitchen windowsill in the morning, lemons and a linen cloth beside it. The camera circles it slowly the way the reference clip does. Soft birdsong outside.
One product clip as the reference, re-staged in a new room while the camera repeats its slow circle.
Check the likeness before iterating
Play the whole clip rather than the first second: likeness tends to drift towards the end of the longer durations, so check the last second before committing to that length. On 2 to 3 seconds there is rarely room for a cut, so multi mostly pays off from about 6 seconds upward. Hold the seed and swap one reference clip at a time while comparing; it keeps the random draw constant so the thing you changed is the only thing moving, without promising a frame-identical rerun. Generated clips are deleted after 14 days, so copy anything you want to keep.
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-2.6/reference-to-video",
"input": {
"aspect_ratio": "16:9",
"duration_seconds": 5,
"prompt": "A slow aerial shot drifting over a misty pine forest at sunrise",
"resolution": "720p",
"shot_type": "single",
"reference_video_urls": [
"https://example.com/reference.mp4"
]
}
}'
# 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.
