Wan 2.6 Reference to Video API

alibaba/wan-2.6/reference-to-video

Wan 2.6 Reference to Video transforms 1–10 reference video clips and text prompts into 5–10 second 1080p cinematic videos, featuring multi-source motion synthesis, multi-shot transitions, and adaptive camera choreography. It faithfully preserves the motion cadence and visual style of source clips while steering new scene storylines guided by your prompt.

Input

Prompt

550/5000

Video Urls

1/10

Add Video

Required: 1–10 videos. MP4, MOV, or MKV, up to 10 MiB per file.

Resolution

Duration

Multi Shots

OutputReady

Examples

Use the exact dog from the reference video. Place the same chocolate-and-tan dachshund with teal collar on an open sandy beach in bright afternoon daylight. It trots a few steps along firm sand while the camera tracks sideways at dog-eye level. Keep its long torso, short legs, floppy ears and tan eyebrows consistent, with believable paw contact and small fresh footprints. Soft distant surf and paw sounds, no people, other dogs, music, text or cuts.

REST API Spec

Quick Start

Submit an endpoint request and poll for status. Replace example URLs with your accessible files.

Step 1: Configure API authentication

Obtain an API key from the dashboard and include Authorization: Bearer <API_KEY> in every request header.

Submission Endpoint: POSThttps://api.vidgo.ai/api/generate/submit
Auth Header: Authorization: Bearer VIDGO_API_KEY

Step 2: Submit a generation task

POST /api/generate/submit. Pass model and optional callback_url at the root level, with generation parameters inside input.

Request Payload

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "alibaba/wan-2.6/reference-to-video",
  "input": {
    "prompt": "Use the exact yellow robot from the reference video as the sole character. Place it on a stone path inside a daylight fern greenhouse. Preserve the mustard rectangular torso, single turquoise eye, short arms with two-finger grippers and broad grey feet. In one full-body three-quarter shot, it bends slightly forward to inspect a large fern frond without touching it, then tilts its rectangular upper body a little to one side. Gentle servo sounds and greenhouse ambience. A completely new leafy glasshouse background. No speech, music, text or cuts.",
    "duration": 5,
    "resolution": "720p",
    "multi_shots": false,
    "video_urls": [
      "https://cdn.vidgo.ai/apis/models/alibaba/wan-2.6/reference-to-video/v1/02/input.mp4"
    ]
  }
}
JSON
)

RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data "$REQUEST_BODY")

CODE=$(printf '%s' "$RESPONSE" | jq -r '.code // empty')
if [ "$CODE" != "0" ] && [ "$CODE" != "200" ]; then
  printf 'API error: %s
' "$RESPONSE" >&2
  exit 1
fi
printf '%s
' "$RESPONSE"

Step 3: Poll for task completion

Poll status with task_id; continue while not_started or running, and stop on finished or failed. Read video URLs from data.files[].file_url on success, or data.error_message on failure.

Status Endpoint

GET https://api.vidgo.ai/api/generate/status/{task_id}

Poll status using task_id; continue while not_started or running, stop when finished or failed. On success, read data.files[].file_url; on failure, read data.error_message.

not_startedrunningfinishedfailed

Submission Response

{
  "code": 200,
  "data": {
    "task_id": "7MP4RU1LZGJT3NOK",
    "status": "running",
    "created_time": "2026-09-21T17:33:00"
  }
}

Completed Response Data

{
  "code": 200,
  "data": {
    "task_id": "task-unified-...",
    "status": "finished",
    "files": [
      {
        "file_url": "https://storage.vidgo.ai/generated/video.mp4",
        "file_type": "video"
      }
    ],
    "created_time": "2026-08-22T10:00:00Z",
    "progress": 100,
    "error_message": null
  }
}

Complete end-to-end script example

Expand to view a production-ready script with retry logic, error handling, and timeout safeguards.

Complete end-to-end script example

set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "alibaba/wan-2.6/reference-to-video",
  "input": {
    "prompt": "Use the exact yellow robot from the reference video as the sole character. Place it on a stone path inside a daylight fern greenhouse. Preserve the mustard rectangular torso, single turquoise eye, short arms with two-finger grippers and broad grey feet. In one full-body three-quarter shot, it bends slightly forward to inspect a large fern frond without touching it, then tilts its rectangular upper body a little to one side. Gentle servo sounds and greenhouse ambience. A completely new leafy glasshouse background. No speech, music, text or cuts.",
    "duration": 5,
    "resolution": "720p",
    "multi_shots": false,
    "video_urls": [
      "https://cdn.vidgo.ai/apis/models/alibaba/wan-2.6/reference-to-video/v1/02/input.mp4"
    ]
  }
}
JSON
)

SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data "$REQUEST_BODY")

TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
BUSINESS_CODE=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
  printf 'Submit failed:
%s
' "$SUBMIT_RESPONSE" >&2
  exit 1
fi
if [ -z "$TASK_ID" ]; then
  printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
  exit 1
fi

START_TIME=$(date +%s)
POLL_DELAY=2
while true; do
  if [ $(( $(date +%s) - START_TIME )) -ge 600 ]; then
    printf 'Timed out after 600 seconds
' >&2
    exit 1
  fi
  STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
    --url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
    --header "Authorization: Bearer $VIDGO_API_KEY")
  STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')
  BUSINESS_CODE=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.code // empty')
  if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
    printf 'Status request failed:
%s
' "$STATUS_RESPONSE" >&2
    exit 1
  fi

  case "$STATUS" in
    finished)
      printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
      break
      ;;
    failed)
      printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
      exit 1
      ;;
    not_started|running)
      sleep "$POLL_DELAY"
      if [ "$POLL_DELAY" -lt 10 ]; then POLL_DELAY=$((POLL_DELAY + 1)); fi
      ;;
    *)
      printf 'Unexpected task status: %s
' "$STATUS" >&2
      exit 1
      ;;
  esac
done

Request Parameters (input object)

Supported reference-to-video parameters inside the input object when submitting a POST request to /api/generate/submit:

Field	Type	Required	Default	Description
prompt	string	Yes	—	String. Trimmed before validation; 1–5,000 Unicode characters.
video_urls	array<string>	Yes	—	Array of 1–10 HTTP(S) video URLs. MP4, MOV, or MKV, up to 10 MiB per file. PoYo validates remote files; no input-video duration limit is imposed.
duration	integer	No	5	Integer. Output duration: 5, 10 seconds.
resolution	string	No	720p	Output resolution: 720p or 1080p.
multi_shots	boolean	No	—	Optional boolean. Omit to leave the upstream setting unspecified. The playground starts with false. No additional charge.

Response Fields (query result)

Task details returned when polling GET /api/generate/status/{task_id}:

Field	Type	Description
code	integer	Business response code, 200 on success.
data.task_id	string	Globally unique asynchronous task identifier.
data.status	string	Execution status: not_started, running, finished, or failed.
data.files	array	Generated video files upon completion, each with file_url and file_type.
data.error_message	string \| null	Error description if task fails.

Task Lifecycle

Clients should inspect the status field and stop polling when reaching finished or failed:

not_started
Task received and queued for execution.
running
Generation is in progress.
finished
Generation complete; retrieve video URL from data.files.
failed
Generation failed; inspect data.error_message; deducted credits are refunded per standard policy.

Polling & Error Handling

Recommended Polling IntervalStart polling every 2–3 seconds, increasing to 5 seconds as the task continues, to avoid excessive requests.
Network Fluctuations & RetriesIf status polling encounters 5xx or timeouts, the task is still running; retry querying after a brief pause.
Asynchronous Webhook CallbackProvide callback_url at the root of the request payload to receive the completed task result automatically via POST.

Specifications

Specification	Value	Description
Model ID	alibaba/wan-2.6/reference-to-video	Send this value in the root-level model field.
Duration	5, 10s	Default is 5 seconds.
Resolution	720p / 1080p	Default is 720p.

View the Wan 2.6 Reference to Video API docs

Wan 2.6 Reference to Video

Wan 2.6 Reference to Video is developed by Alibaba Tongyi Lab to generate high-quality video guided by existing video footage. By accepting 1–10 reference clips along with a text prompt, it produces 5 or 10-second takes in up to 1080p resolution, helping creators replicate complex motion cadences, choreography, and cinematic camera moves with optional multi_shots sequencing.

Why Choose This?

1–10 multi-clip video referencesAccepts up to 10 video clips to extract motion features, spatial framing, and lighting from diverse angles.
Faithful motion cadence transferAccurately extracts character poses, movement velocity, and camera tracks to apply them fluidly to new visual concepts.
Adaptive multi-shot transitionsSynthesize dynamic multi-angle sequences by enabling multi_shots without adding any extra billing cost.
Up to 1080p clean output resolutionSupports 720p and 1080p tiers to eliminate resampling artifacts and deliver smooth, high-definition final frames.
Asynchronous pipeline integrationSupports MP4, MOV, and MKV containers, plugging easily into automated media pipelines via standard REST endpoints.

Parameters

Parameter	Requirement	Description
prompt	Required	String. Trimmed before validation; 1–5,000 Unicode characters.
video_urls	Required	Array of 1–10 HTTP(S) video URLs. MP4, MOV, or MKV, up to 10 MiB per file. PoYo validates remote files; no input-video duration limit is imposed.
duration	Optional	Integer. Output duration: 5, 10 seconds. Default`510`
resolution	Optional	Output resolution: 720p or 1080p. Default`720p1080p`
multi_shots	Optional	Optional boolean. Omit to leave the upstream setting unspecified. The playground starts with false. No additional charge. `truefalse`

How to Use

Upload reference clipsProvide 1–10 MP4, MOV, or MKV video files up to 10 MiB each; pass URLs in the video_urls array via API.
Describe desired sceneIn the prompt, define new subjects, lighting environments, and how reference motion should be applied.
Set output durationChoose either 5 or 10 seconds based on your target scene duration, with 5 seconds as default.
Pick target resolutionSelect 720p for fast preview or 1080p for final broadcast quality, with 720p as default.
Optionally toggle multi-shotEnable multi_shots to introduce multi-angle cuts guided by your reference footage at no extra charge.
Verify credits and submitReview estimated credits and click Run, or send an authenticated POST request to /api/generate/submit.
Poll task and retrieve videoQuery task progress with task_id and download your finished MP4 file once status reaches finished.

Pricing

Billed per generated video by output resolution and duration. Multiple shots do not add a surcharge. 1 credit = $0.005.

Usage	Rate	Details
720p · 5 seconds	80 credits / $0.40	Per video
720p · 10 seconds	160 credits / $0.80	Per video
1080p · 5 seconds	120 credits / $0.60	Per video
1080p · 10 seconds	240 credits / $1.20	Per video

Best Use Cases

Choreography and martial arts replicationUse dance rehearsals or stunt footage to transfer realistic kinetic choreography to virtual characters.
Cinematic camera movement mimicryBorrow complex dolly zooms, orbital pans, or drone tracking shots from reference footage for new scenes.
Action sports and dynamic physics simulationFeed parkour, skiing, or skateboarding clips to recreate realistic momentum in sci-fi environments.
Visual style and lighting ambiance transferAdopt color schemes, illumination shifts, and volumetric mood from sample reels into new productions.
Product mechanical showcasesReplicate mechanical disassemblies or device interactions to render precision commercial animations.

Pro Tips

Select high-clarity motion footage: Clear silhouettes with minimal motion blur allow the model to track movement dynamics with maximum fidelity.
Align text prompts with reference actions: Clearly describe how new subjects perform the referenced motions to keep kinematics natural.
Combine complementary references: When submitting multiple clips, specify their roles in your prompt (e.g. 'motion from clip 1, camera angle from clip 2').
Use 10-second duration for complete cycles: Complex physical cycles like acrobatics or athletic stunts resolve best within the 10-second window.
Pair high-energy motion with multi_shots: For fast-paced scenes, enabling multi_shots introduces dramatic cutaways that amplify visual impact.

Notes

Reference clip limits and sizes: The video_urls array must contain 1–10 accessible HTTP(S) links in MP4, MOV, or MKV format, up to 10 MiB per file.
Supported duration and resolution tiers: Outputs 5 or 10 seconds (distinct from text/image endpoints) at 720p or 1080p, billed accordingly.
No surcharge for multi-shot mode: The multi_shots boolean option allows multi-angle transitions without additional credit deductions.
Asynchronous task polling: Submission returns task_id; poll the status endpoint or supply callback_url for webhook notifications.

Wan 2.6 Reference to Video API Frequently Asked Questions

What is the Wan 2.6 Reference to Video API?

Wan 2.6 Reference to Video is an Alibaba model for video-guided video generation. It synthesizes 1–10 reference video clips and text prompts into 5–10 second, up to 1080p high-definition dynamic videos with support for camera control and multi-shot transitions. Built on a Diffusion Transformer spatio-temporal architecture, it faithfully extracts motion cadence, kinetic rhythm, and lighting style from source clips while generating new subjects and scene interactions specified in your prompt. You can call it programmatically or try it from the playground above.

How many reference clips does Wan 2.6 Reference to Video support?

The endpoint accepts 1 to 10 reference video files. Pass accessible HTTP(S) links in the video_urls array; supported formats include MP4, MOV, and MKV with a file size limit of 10 MiB per video.

How does Wan 2.6 Reference to Video transfer motion from reference clips?

The model utilizes spatio-temporal cross-attention to isolate kinetic rhythm and camera tracks from input footage. By pairing this with your prompt descriptions, it smoothly applies the extracted movements to your newly generated subjects.

What durations does Wan 2.6 Reference to Video output?

It outputs 5 or 10 seconds of video, with 5 seconds as default. To ensure tight spatio-temporal alignment with reference footage, generation focuses on these high-fidelity 5-second and 10-second tiers.

Does multi-shot mode in Wan 2.6 Reference to Video cost more?

No, it adds no cost. Enabling multi_shots allows the model to arrange cinematic multi-angle cuts guided by the reference movement and prompt, billed strictly by standard duration and resolution rates.

How does Wan 2.6 Reference to Video perform at 1080p?

Selecting 1080p produces crisp details and fluid motion gradients, preventing resampling artifacts from source footage and delivering clean, broadcast-ready visuals.

Should I use Wan 2.6 Reference to Video if I only have a static photo?

If you only have a single photo, choose the Wan 2.6 Image to Video endpoint instead. Wan 2.6 Reference to Video is specifically designed for multi-frame video guidance.