Wan 2.7 Reference to Video API

alibaba/wan-2.7/reference-to-video

Wan 2.7 Reference to Video transforms up to 9 reference images or reference videos into 2–10 second cinematic clips, supporting 9-grid storyboards, multi-shot pacing, and prompt-guided camera direction. It maintains consistent character identity and environmental style across complex narrative transitions without visual drift.

Input

Prompt (Required)531/5,000

Reference Image Urls

Drag and drop files, paste from clipboard, or provide a URL.

2/9 files added

Reference Video Urls

Drag and drop files, paste from clipboard, or provide a URL.

Resolution

Duration

Aspect Ratio

Seed

Multi Shots

Enable Safety Checker

Output

Ready

Continue using

Wan 2.7 Text to Video Wan 2.7 Image to Video Wan 3.0 Reference to Video

Examples

Use Reference Image 1 for the same explorer, face, helmet and ochre clothing. Use Reference Image 2 for the same brass lantern. Two shots in a limestone cave: first three seconds, a medium-wide shot of her holding the lantern and taking one careful step; last two seconds, cut to a waist-up view as she raises the lantern to illuminate mineral textures. Preserve her identity, outfit and lantern across the cut. Restrained natural movement. No text, lettering, captions, logos, watermarks, brands, advertising or product packaging.

Use the reference video for the dancer identity, rust skirt, cream blouse and graceful turning movement. Show the same dancer making one gentle quarter turn on a stone terrace overlooking calm blue hills at dawn. Full-body fixed camera view, both feet remain grounded, preserve clothing and natural anatomy. Continuous shot. No text, lettering, captions, logos, watermarks, brands, advertising or product packaging.

Use Reference Image 1 for the exact small green clay dragon with cream horns and amber eyes. Use Reference Image 2 for the miniature greenhouse setting. The dragon sits on the terracotta floor, then slowly lifts its head to inspect a broad leaf overhead. Preserve handmade clay texture and proportions. A gentle camera push, tactile stop-motion aesthetic, single shot. No text, lettering, captions, logos, watermarks, brands, advertising or product packaging.

REST API Reference

Quick Start

Submit a task and query its status.

Step 1: Set up authentication

Create an API key in the dashboard and attach Authorization: Bearer <API_KEY> when submitting a task.

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

Step 2: Submit a task

POST /api/generate/submit · alibaba/wan-2.7/reference-to-video

Submit Request

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "alibaba/wan-2.7/reference-to-video",
  "input": {
    "resolution": "720p",
    "duration": 5,
    "prompt": "Describe the scene or edit",
    "aspect_ratio": "16:9",
    "reference_image_urls": [
      "https://example.com/reference.png"
    ]
  }
}
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 completion

Poll with task_id while status is not_started or running, and stop at finished or failed. On success, read data.files[].file_url; on failure, read data.error_message.

Status Endpoint

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

Poll with task_id while status is not_started or running, and stop at finished or failed. On success, read data.files[].file_url; on failure, read data.error_message.

not_startedrunningfinishedfailed

Submit Response

{
  "code": 200,
  "data": {
    "task_id": "task-example",
    "status": "running",
    "created_time": "2026-09-21T08:00:00Z"
  }
}

Completed Response

{
  "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 executable script

Expand to review an end-to-end script with automatic polling, error handling, and timeout safeguards.

Complete executable script

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

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "alibaba/wan-2.7/reference-to-video",
  "input": {
    "resolution": "720p",
    "duration": 5,
    "prompt": "Describe the scene or edit",
    "aspect_ratio": "16:9",
    "reference_image_urls": [
      "https://example.com/reference.png"
    ]
  }
}
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 generation parameters inside the input object when submitting to /api/generate/submit:

Field	Type	Required	Default	Description
prompt	string	Yes	—	Prompt, trimmed; maximum 5,000 Unicode characters. Optional for image-to-video.
reference_image_urls	array	No	—	Up to nine ordered reference images; HTTP(S), Data URI or Base64. Provide reference images or videos.
reference_video_urls	array	No	—	Public HTTP(S) reference video URLs. Provide reference images or videos.
aspect_ratio	string	No	16:9	16:9, 9:16, 1:1, 4:3 or 3:4. Default: 16:9.
resolution	string	No	720p	720p or 1080p. Default: 720p.
duration	integer	No	5	2–10 whole seconds; default 5.
multi_shots	boolean	No	—	Optional multi-shot control. Omitted by default.
seed	integer	No	—	Optional integer from 0 to 2147483647.
enable_safety_checker	boolean	No	—	Optional safety checker setting; omitted by default.

Response Fields (Status Query)

Details returned by GET /api/generate/status/{task_id}:

Field	Type	Description
code	integer	HTTP/business response status code (200 indicates success).
data.task_id	string	Globally unique task identifier.
data.status	string	Task lifecycle state: not_started, running, finished, or failed.
data.files	array	Array of output assets containing file_url and file_type upon completion.
data.error_message	string \| null	Error diagnostic details if the task status is failed.

Task Lifecycle

Clients should poll status until reaching either the finished or failed terminal state:

not_started
Queued
running
Generating
finished
Ready
failed
Failed

Polling & Error Handling

Polling frequencyStart polling with a 2 to 3-second interval, gradually increasing to 5 seconds for extended takes.
Network resiliencyTransient 5xx responses or timeouts do not signify task failure; retry status requests after a short backoff.
Webhook callbacksProvide a top-level callback_url in your submission payload to receive completion notifications automatically.

Specifications

Specification	Value	Description
Model	alibaba/wan-2.7/reference-to-video
Resolution	720p / 1080p	Default: 720p
Duration	2–10 whole seconds; default 5.

View Wan 2.7 Reference to Video API docs

Wan 2.7 Reference to Video

Wan 2.7 Reference to Video is designed for complex narrative filmmaking and visual continuity tasks. By ingesting up to 9 reference images (including 9-grid storyboard frames) or reference videos alongside descriptive text prompts, the model locks character faces, costumes, and props across multiple scene changes. It supports 2 to 10-second durations, 5 native aspect ratios, and multi-shot generation to power seamless storytelling.

Why Choose Wan 2.7 Reference to Video?

Ingest up to 9 reference imagesProvide multiple angles, lighting setups, or character poses to guide consistent subject rendering across new scenes.
Support 9-grid storyboard workflowsTranslate panel sequences and visual boards into animated cinematic shots with coherent narrative pacing.
Maintain cross-scene character identityAdvanced feature matching prevents identity drift across multi-angle camera shots, costume variations, and action sequences.
Accept reference video assetsPass reference video clips in reference_video_urls to establish realistic motion rhythms and scene dynamics directly.
Switch across five native aspect ratiosDeliver clips in 16:9, 9:16, 1:1, 4:3, or 3:4 formats tailored for theatrical pre-visualization or social feeds.

Parameters

Parameter	Requirement	Description
prompt	Yes	Prompt, trimmed; maximum 5,000 Unicode characters. Optional for image-to-video. Default`—`
reference_image_urls	No	Up to nine ordered reference images; HTTP(S), Data URI or Base64. Provide reference images or videos. Default`—`
reference_video_urls	No	Public HTTP(S) reference video URLs. Provide reference images or videos. Default`—`
aspect_ratio	No	16:9, 9:16, 1:1, 4:3 or 3:4. Default: 16:9. Default`16:9`
resolution	No	720p or 1080p. Default: 720p. Default`720p`
duration	No	2–10 whole seconds; default 5. Default`5`
multi_shots	No	Optional multi-shot control. Omitted by default. Default`—`
seed	No	Optional integer from 0 to 2147483647. Default`—`
enable_safety_checker	No	Optional safety checker setting; omitted by default. Default`—`

How to Use Wan 2.7 Reference to Video

Assemble your reference assetsPrepare up to 9 reference images (characters, environments, or 9-grid frames) or reference videos as public URLs.
Write prompt with narrative referencesOutline the scene action, camera movements, and subject interactions, linking descriptive elements to your references.
Configure duration and submitSelect duration (2–10 seconds), resolution, and aspect ratio, then execute the task via API or Playground to fetch the final MP4.

Pricing

Credits = output seconds × resolution rate. Failed tasks are refunded automatically.

Usage	Rate	Details
720p	12 credits/s ($0.06/s)	All four workflows use the same rate.
1080p	18 credits/s ($0.09/s)	All four workflows use the same rate.

Best Use Cases

9-grid storyboard sequence animationAnimate full 9-panel comic strips and narrative storyboard drawings into flowing cinematic video sequences.
Multi-character drama continuityMaintain facial identities and distinct costumes across complex multi-actor dialogue and confrontation scenes.
Product commercial stylingProvide reference photos of real-world merchandise to place products into dynamic live-action marketing clips.
Reference video style & motion transferSupply choreography or camera movement references via video URLs to inspire new animated sequences.

Pro Tips for Wan 2.7 Reference to Video

Upload multi-angle shots of the main character：Supplying front, three-quarter, and profile reference images establishes comprehensive spatial memory for 360-degree camera turns.
Organize 9-grid storyboards chronologically：When feeding a 9-grid storyboard, describe the narrative sequence from opening beat to climax in the prompt to match visual flow.
Combine multi_shots with distinct scene directions：Enable multi_shots: true when scripting dialogue or shot-reverse-shot setups to let the model generate natural camera cuts.
Keep reference lighting consistent：While the model adapts characters to new environments, providing references with uniform lighting enhances edge cleanliness.

Notes

Reference asset requirements：Provide at least one reference input via reference_image_urls (up to 9 images) or reference_video_urls.
Duration range：Reference to Video supports whole second durations from 2 to 10 seconds. Values outside this range will fail validation.
Automatic credit refund：If a task fails during generation or media processing, all deducted credits are refunded immediately to your account.

Wan 2.7 Reference to Video API frequently asked questions

What is the Wan 2.7 Reference to Video API?

Wan 2.7 Reference to Video is an Alibaba Tongyi Lab model for reference-driven video creation. It generates 2 to 10-second high-definition videos at 720p or 1080p by incorporating up to 9 reference images or reference videos with text prompts, supporting 9-grid storyboards, multi-shot pacing, and character consistency. Powered by a Diffusion Transformer backbone and Wan-VAE 3D temporal compression, it locks subject identity and environmental style across dynamic camera transitions without visual drift. You can call it programmatically or try it from the playground above.

How many reference images can Wan 2.7 Reference to Video accept?

Wan 2.7 Reference to Video accepts up to 9 reference images via the reference_image_urls array. You can submit images showcasing characters from multiple perspectives, specific props, or sequential storyboard panels.

How does Wan 2.7 Reference to Video use 9-grid storyboards?

You can provide a 9-grid storyboard image as reference. The model extracts individual panel arrangements and narrative progressions, transforming static panel layouts into dynamic, continuous video takes guided by your text prompt.

Can Wan 2.7 Reference to Video take reference videos as input?

Yes, the reference_video_urls parameter accepts public video URLs. The model analyzes motion rhythms, camera gestures, and stylistic transitions from the reference videos to inform the generated animation.

What is the maximum duration for Wan 2.7 Reference to Video?

Wan 2.7 Reference to Video supports whole second durations from 2 seconds up to 10 seconds. The default duration is 5 seconds, allowing creators to balance multi-character staging with generation speed.

How does Wan 2.7 Reference to Video bind characters in the prompt?

You can reference specific attributes or ordinal indices in your prompt corresponding to the uploaded reference images. The attention layers correlate prompt descriptors directly with the visual embeddings of the respective reference inputs.

How does multi_shots work in Wan 2.7 Reference to Video?

Setting multi_shots to true enables multi-shot storytelling within a single generation. It instructs the model to create cinematic transitions or angle variations across the timeline while keeping the referenced subjects consistent.