Wan 3.0 Reference-to-Video API

alibaba/wan-3.0/reference-to-video

Wan 3.0 (Reference-to-Video) transforms text prompts alongside multimodal references including images, video clips, audio, documents, or web links into dynamic video, supporting up to 20 combined assets and 2 to 30 second continuous generation. It preserves subject identity, artistic style, and narrative continuity across scenes while synthesizing synchronized native audiovisual footage.

Input

Prompt

631/20000

Total references3/21 · remaining 18

Reference images

3/10 · remaining 7

Add image

Reference videos

0/5 · remaining 5

Add video

Reference audios

0/5 · remaining 5

Resolution

Duration

Aspect ratio

Audio

Safety checker

Seed

Reference document URL

Reference webpage URL

Output

Ready

Continue with

Wan 3.0 Text-to-Video Wan 3.0 Image-to-Video Minimax Hailuo 01

Examples

Use Reference Image 1 only for the proud pigeon with the aviator scarf. Use Reference Image 2 only for the oversized croissant. Use Reference Image 3 only for the subway grab handle. In one continuous five-second shot, the Image 1 pigeon holds the Image 2 croissant in its beak and stands on the Image 3 subway handle, swaying with the train. Camera: waist-height handheld sway matching the subway motion. No cuts. Synchronized audio: subway rumble, a proud coo, a faint pastry flake crunch. No readable text, letters, numbers, captions, labels, logos, brands, watermarks, advertisements, posters, UI screens, or product packaging.

Use Reference Image 1 only for the long-legged Victorian teapot character. Use Reference Image 2 only for the mossy library aisle. In one continuous five-second shot, the Image 1 teapot tiptoes down the Image 2 aisle, pausing to inspect a shelf, lid tilting like a polite nod. Camera: tracking follow from behind and slightly beside, staying at teapot-eye height. No cuts. Synchronized audio: porcelain foot taps, a floorboard creak, a hushed library room tone. No readable text, letters, numbers, captions, labels, logos, brands, watermarks, advertisements, posters, UI screens, or product packaging.

Parse Reference Document 1 as a one-page playful science comic about why toast usually lands butter-side down. Produce one continuous five-second explainer animation: the toast slides off a table, rotates in the air, and lands butter-side down while a tiny curious cat watches. Keep the homemade paper-comic look. No product brands, no advertisements, no logos. Camera: simple locked comic-panel push that follows the fall. No cuts. Synchronized audio: plate scrape, brief whoosh, buttered toast slap, a tiny cat chirp.

REST API Reference

Quick Start

Submit a reference-to-video request with multimodal assets and retrieve high-definition video outputs.

Step 1: Set up authentication

Generate an API Key in the dashboard and attach it as Authorization: Bearer <API_KEY> on all HTTP requests.

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

Step 2: Submit a reference-to-video task

Send a POST request to /api/generate/submit specifying alibaba/wan-3.0/reference-to-video and your multimodal reference assets. Audio may be the only reference type; a prompt is still required.

Submit Request

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "alibaba/wan-3.0/reference-to-video",
  "input": {
    "prompt": "Use Reference Image 1 only for the proud pigeon with the aviator scarf. Use Reference Image 2 only for the oversized croissant. Use Reference Image 3 only for the subway grab handle. In one continuous five-second shot, the Image 1 pigeon holds the Image 2 croissant in its beak and stands on the Image 3 subway handle, swaying with the train. Camera: waist-height handheld sway matching the subway motion. No cuts. Synchronized audio: subway rumble, a proud coo, a faint pastry flake crunch. No readable text, letters, numbers, captions, labels, logos, brands, watermarks, advertisements, posters, UI screens, or product packaging.",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "adaptive",
    "audio": true,
    "enable_safety_checker": true,
    "reference_image_urls": [
      "https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0/reference-to-video/v1/01/input-01.jpg",
      "https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0/reference-to-video/v1/01/input-02.jpg",
      "https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0/reference-to-video/v1/01/input-03.jpg"
    ]
  }
}
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-wan30-r2v-774129",
    "status": "running",
    "created_time": "2026-09-16T08:40: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-3.0/reference-to-video",
  "input": {
    "prompt": "Use Reference Image 1 only for the proud pigeon with the aviator scarf. Use Reference Image 2 only for the oversized croissant. Use Reference Image 3 only for the subway grab handle. In one continuous five-second shot, the Image 1 pigeon holds the Image 2 croissant in its beak and stands on the Image 3 subway handle, swaying with the train. Camera: waist-height handheld sway matching the subway motion. No cuts. Synchronized audio: subway rumble, a proud coo, a faint pastry flake crunch. No readable text, letters, numbers, captions, labels, logos, brands, watermarks, advertisements, posters, UI screens, or product packaging.",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "adaptive",
    "audio": true,
    "enable_safety_checker": true,
    "reference_image_urls": [
      "https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0/reference-to-video/v1/01/input-01.jpg",
      "https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0/reference-to-video/v1/01/input-02.jpg",
      "https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0/reference-to-video/v1/01/input-03.jpg"
    ]
  }
}
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 parameters inside the input object when submitting to /api/generate/submit:

Field	Type	Required	Default	Description
prompt	string	Yes	-	Text prompt describing scene progression and binding reference asset roles; supports 1 to 20,000 characters.
reference_image_urls	array[string]	No	[]	Array of reference image URLs (up to 10, max 30MB each in JPEG, PNG, or WebP).
reference_video_urls	array[string]	No	[]	Up to 5 public HTTP(S) reference video URLs to guide motion, camera behavior, or pacing.
reference_audio_urls	array[string]	No	[]	Array of reference audio URLs (up to 5, max 50MB each in MP3 or WAV). May be the only reference type.
reference_file_urls	array[string]	No	[]	Up to 1 public HTTP(S) document URL; cannot be combined with reference_link_urls.
reference_link_urls	array[string]	No	[]	Up to 1 public webpage URL; mutually exclusive with reference_file_urls.
duration	integer	No	5	Output video duration in whole seconds between 2 and 30.
resolution	string	No	720p	Resolution tier: 480p, 720p, or 1080p.
aspect_ratio	string	No	adaptive	Framing ratio: adaptive (follows reference framing), 16:9, 4:3, 1:1, 3:4, or 9:16.
audio	boolean	No	true	Whether to generate a synchronized native audio track; billed at the same rate as silent output.
seed	integer	No	-	Seed value (0–2,147,483,647) for reproducible generation.
enable_safety_checker	boolean	No	true	Enables content compliance and safety checking.

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
Task queued successfully; system is downloading and extracting multimodal assets.
running
The model is executing cross-asset feature alignment and spatial-temporal diffusion denoising.
finished
Video generation completed and stored; download URL available in data.files[0].file_url.
failed
Task stopped due to asset download failure, mutual exclusivity conflict, or safety rejection.

Polling & Error Handling

Polling frequencyMultimodal ingestion requires preprocessing; start polling after 3 seconds, repeating every 3 to 5 seconds.
Mutual exclusivity validationSubmitting both reference_file_urls and reference_link_urls produces a 400 validation error immediately.
Webhook callbacksProvide a top-level callback_url in your submission payload to receive completion notifications automatically.

Specifications

Specification	Value	Description
Model identifier	alibaba/wan-3.0/reference-to-video	API route identifier passed in the request body model field.
Input mode	Multimodal references (up to 20 assets)	Images ≤10, videos ≤5, audio ≤5, documents or links ≤1 (mutually exclusive), plus a text prompt.
Output format	30 fps / MP4 (H.264)	High-compatibility MP4 container with native AAC audio.
Duration	2–30 seconds	Configurable in whole seconds from 2 to 30 seconds per task.
Resolution	480p / 720p / 1080p	Three native resolution tiers; 720p is the default.

View complete Wan 3.0 Reference-to-Video API documentation

Wan 3.0 Reference-to-Video

Wan 3.0 Reference-to-Video generates continuous high-definition video with native synchronized audio by blending text prompts with multimodal reference assets. Maintain strict facial identity, costume styling, dynamic motion patterns, or document narrative structures across 2 to 30-second generations at up to 1080p resolution.

Why Choose This?

Omni-asset multimodal inputsCombine up to 20 multimodal assets in a single request, including images (up to 10), videos (up to 5), audio files (up to 5), and a document or webpage.
Cross-scene character consistencyAnchor protagonist facial features, wardrobe details, and unique aesthetic rendering styles steadily across distinct shots and story beats.
Document and webpage synthesisIngest structured presentations (PPT, PDF, DOCX) or public URLs to automatically distill key information into dynamic narrative video.
Native audiovisual co-generationSynthesize synchronized dialogue timing, acoustic room ambience, and foley sound effects natively alongside visual diffusion frames at 30 fps.
Extended 30-second 1080p outputDeliver broadcast-ready takes with flexible durations from 2 to 30 seconds at 480p, 720p, or 1080p resolution.

Parameters

Parameter	Requirement	Description
prompt	Required	String. Describes scene actions, camera motion, and assigns roles to provided reference assets; supports 1 to 20,000 characters.
reference_image_urls	Optional	Array of strings. Up to 10 image URLs for character appearance, scene environment, or props; max 30MB per image in JPEG, PNG, or WebP.
reference_video_urls	Optional	Up to 5 public HTTP(S) reference video URLs to guide motion, camera behavior, or pacing.
reference_audio_urls	Optional	Array of strings. Up to 5 audio URLs for vocal timbre, rhythm, or ambient sound; max 50MB per file in MP3 or WAV format.
reference_file_urls	Optional	Up to 1 public HTTP(S) document URL; cannot be combined with reference_link_urls.
reference_link_urls	Optional	Array of strings. Maximum 1 publicly accessible webpage URL; mutually exclusive with reference_file_urls.
duration	Optional	Integer. Output duration in whole seconds between 2 and 30; playground defaults to 5 seconds. Default`5`
resolution	Optional	String. Native output resolution tier; choices include 480p, 720p (default), or 1080p. Default`720p480p1080p`
aspect_ratio	Optional	String. Framing ratio; supports adaptive (follows reference framing), 16:9, 4:3, 1:1, 3:4, and 9:16. Default`adaptive16:94:31:13:49:16`
audio	Optional	Boolean. Determines whether to synthesize a synchronized audio track alongside the video; defaults to true at no extra cost. Default`truefalse`
seed	Optional	Integer. Random seed between 0 and 2,147,483,647 for reproducible trajectories and dynamics.
enable_safety_checker	Optional	Boolean. Enables automated safety filtering on prompts and generated outputs; defaults to true. Default`truefalse`

How to Use

Gather and attach reference assetsUpload character turnarounds (up to 10 images), action motion clips (up to 5 videos), timbre audio clips, or attach a pitch presentation / public webpage URL.
Assign asset roles in your promptReference assets explicitly in natural language (e.g., Using the hero in reference image 1 wearing the armor in reference image 2, perform a slow walk inside the futuristic hangar from reference image 3).
Choreograph motion and camera pathsDescribe scene progression sequentially with explicit camera instructions (e.g., The camera tracks steadily at waist level before ascending into an aerial view).
Configure duration and resolutionSelect an output duration between 2 and 30 seconds, choose 720p or 1080p resolution, and set aspect ratio to adaptive or 16:9.
Verify asset exclusivity constraintsEnsure audio is enabled if sound is desired, and verify that document files and webpage URLs are not submitted in the same request.
Submit and evaluate consistent videoSubmit your task, track asynchronous progress in the preview console, and inspect character consistency upon playback before downloading.

Pricing

Wan 3.0 Reference-to-Video charges by generated output second based strictly on the selected resolution tier; multimodal asset ingestion and audio synthesis carry no additional fee (1 credit = $0.005).

Usage	Rate	Details
480p	10 credits / output sec ($0.05 / sec)	Standard definition tier. 5-second default is 50 credits ($0.25); 30-second maximum is 300 credits ($1.50).
720p (Default)	20 credits / output sec ($0.10 / sec)	High definition tier. 5-second default is 100 credits ($0.50); 30-second maximum is 600 credits ($3.00).
1080p	40 credits / output sec ($0.20 / sec)	Full high definition flagship tier. 5-second default is 200 credits ($1.00); 30-second maximum is 1,200 credits ($6.00).

Best Use Cases

Episodic IP character storytellingGenerate multi-shot scenes across varied environments while anchoring protagonist appearance and costume design.
Presentation and pitch deck visualizationConvert business proposals, pitch decks, or training slides into dynamic motion explainers with ambient voiceover soundscapes.
Webpage and article reformattingProvide a public article or product URL to distill written editorial content into engaging short-form social video.
Motion choreography style transferCombine existing stunt or dance video clips with new character portraits to transfer complex choreography onto new subjects.

Pro Tips

Provide multi-angle character references: Supplying front, three-quarter, and side portraits enhances subject geometric stability during dynamic character turns.
Use explicit reference binding phrases: Write phrases like 'character from reference image 1 wearing jacket from reference image 2' to prevent visual feature leakage.
Respect document and link mutual exclusivity: reference_file_urls and reference_link_urls cannot be used simultaneously; select one modality per task.
Keep documents focused, with clear charts and readable text hierarchy to guide the video narrative.
Maintain shared asset sets across shots: Reuse the exact same reference array across consecutive prompt generations to maintain consistent production design across an entire video project.

Notes

Reference asset limits: A single request supports up to 20 total assets: maximum 10 images, 5 videos, 5 audio files, and 1 document or webpage.
Mutually exclusive inputs: reference_file_urls and reference_link_urls are mutually exclusive; submitting both triggers a 400 validation error.
Whole-second duration input: The duration parameter accepts whole integers between 2 and 30 seconds.

Wan 3.0 Image-to-VideoAnimate a start image with sound and add an optional end frame to guide the closing shot.

Wan 3.0 PrimeUse the Prime tier for the same three workflows with a higher per-second rate.

MiniMax H3Compare a fixed 2K video family with text, frame, and multimodal reference workflows.

Seedance 2.5Compare a ByteDance family with text, start/end-frame, and multimodal reference workflows.

Wan 2.6Generate 1080p video through text, image, or video-guided workflows.

Wan 3.0 Reference-to-Video API — Frequently Asked Questions

What is the Wan 3.0 Reference-to-Video API?

Wan 3.0 Reference-to-Video is an Alibaba Tongyi Lab model for generating video from multimodal references. It combines natural-language prompts with images, video clips, audio tracks, structured documents, or public webpages (up to 20 reference assets) to generate continuous takes up to 30 seconds at up to 1080p with native audio. Built on cross-modal alignment and Diffusion Transformer architectures, it preserves character facial identity, movement pacing, or document knowledge across shots in brand-new narrative scenes. You can call it programmatically or try it from the playground above.

Can I upload PPT or PDF documents to Wan 3.0 Reference-to-Video?

Yes. By providing a document URL in reference_file_urls (supporting PPT, PPTX, PDF, DOCX, TXT, MD), the model analyzes slide layout, graphics, and textual hierarchy, transforming written assets into narrated video sequences with dynamic camera moves.

Can I provide both a document and a webpage link in Wan 3.0 Reference-to-Video?

No. The reference_file_urls and reference_link_urls parameters are mutually exclusive; you may supply at most one document or one webpage link per request. You can freely combine either option with reference images, videos, or audio tracks.

What is the maximum number of reference assets in Wan 3.0 Reference-to-Video?

A single request supports up to 20 total assets, including up to 10 reference images, up to 5 reference videos, up to 5 reference audio tracks, and 1 document or webpage link. This rich multi-asset ingestion allows complex storyboard setups.

How do I bind multiple subjects in Wan 3.0 Reference-to-Video prompts?

Use explicit role-assignment tagging in your prompt, such as "Use Reference Image 1 for the protagonist's face and jacket, Reference Image 2 for the handheld prop, and Reference Video 1 for the walking pace." Explicit naming ensures distinct assets bind to the intended entities.

How does Wan 3.0 Reference-to-Video process reference audio?

When reference_audio_urls are provided, the model incorporates the reference vocal timbre, cadence, or melodic rhythm, harmonizing it with the subject's on-screen movements and ambient room acoustics for cohesive audiovisual pacing.

How do I provide a document reference?

Provide one publicly accessible HTTP(S) document URL in reference_file_urls. Do not also provide reference_link_urls.