Wan 3.0 Prime Reference-to-Video API

alibaba/wan-3.0-prime/reference-to-video

Wan 3.0 Prime (Reference-to-Video) transforms a text prompt plus image, video, audio, file, or link references into a continuous video up to 30 seconds, with Omni-Reference multimodal control, native audio-visual sync, and output up to 1080p. It carries identity, props, motion cues, and space into a new scene while following the roles you assign in the prompt.

Input

Prompt

500/20000

Total references0/20 · remaining 20

Reference images

0/10 · remaining 10

Add image

Reference videos

0/5 · remaining 5

Add video

Reference audios

0/5 · remaining 5

Reference document URL

Reference webpage URL

Add at least one reference image, video, audio, document URL, or webpage URL.

Resolution

Duration

Aspect ratio

Audio

Safety checker

Seed

Output

Idle

Your generated video will appear here

Configure the required inputs, resolution, and duration, then run the task.

Continue with

Wan 3.0 Prime Text-to-Video Wan 3.0 Prime Image-to-Video Gemini Omni 1.1 Flash Reference-to-Video MiniMax H3 Reference-to-Video

Examples

Use the two reference images only for this long-legged porcelain teapot: spout, lid, floral glaze, and stork-like legs. New 4-second 1:1 scene: the teapot stomps across a wooden dining table, each footfall making cups rattle. Locked three-quarter camera. Native audio: ceramic foot stomps, cup chatter, table creak. Image references only. No logos, no readable text, no products, no packaging, no prices, no CTA, no advertising, no watermark, no brand marks.

Use the two close-up references for this barrel cactus with tiny black sunglasses, spines, and pot. New 4-second 4:3 scene: the cactus nods and sways in a tiny dance on a sunny windowsill. Locked close-up. Native audio: faint spine rustle, window breeze, a soft rhythmic tap. No logos, no readable text, no products, no packaging, no prices, no CTA, no advertising, no watermark, no brand marks.

REST API

Quick Start

Authenticate, submit a valid input object, then use task_id to retrieve the video.

Connect to the Vidgo API

Create an API key, keep it only on your server, and send Authorization: Bearer VIDGO_API_KEY.

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

Submit one generation task

Run the smallest valid payload for this workflow. A successful submission immediately returns task_id without waiting for the video. Audio may be the only reference type; a prompt is still required.

Submit request

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "alibaba/wan-3.0-prime/reference-to-video",
  "input": {
    "prompt": "Use image 1 for the fox's face, fur, and oversized white lab coat. Use video 1 only for the walking gait and tail sway. Use audio 1 for the laboratory room-tone: HVAC hum and distant glass. New 5-second 16:9 scene: the same fox walks along a lab bench, pauses, and sniffs a bubbling beaker. Medium tracking shot, eye level. Native audio: the supplied lab room-tone plus paw steps. No logos, no readable text, no products, no packaging, no prices, no CTA, no advertising, no watermark, no brand marks.",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "audio": true,
    "enable_safety_checker": true,
    "reference_image_urls": [
      "https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0-prime/reference-to-video/v1/01/input-01.webp",
      "https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0-prime/reference-to-video/v1/01/input-02.webp"
    ],
    "reference_video_urls": [
      "https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0-prime/reference-to-video/v1/01/input-motion.mp4"
    ],
    "reference_audio_urls": [
      "https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0-prime/reference-to-video/v1/01/input-audio.mp3"
    ]
  }
}
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"

Wait for the result

Query with task_id, continue for not_started/running, and stop for finished/failed. On success, read data.files[].file_url.

Track status

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

Poll about every 2 seconds, then back off gradually. Continue only for not_started or running and stop on finished or failed. You can instead add callback_url to the same top-level request contract.

not_startedrunningfinishedfailed

Submit response

{
  "code": 200,
  "data": {
    "task_id": "task-unified-...",
    "status": "running",
    "created_time": "2026-08-22T10:00:00Z"
  }
}

Finished 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 runnable example

Expand for a complete script with HTTP and business-code checks, task_id validation, polling, terminal-state handling, and a timeout boundary.

Complete runnable example

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

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "alibaba/wan-3.0-prime/reference-to-video",
  "input": {
    "prompt": "Use image 1 for the fox's face, fur, and oversized white lab coat. Use video 1 only for the walking gait and tail sway. Use audio 1 for the laboratory room-tone: HVAC hum and distant glass. New 5-second 16:9 scene: the same fox walks along a lab bench, pauses, and sniffs a bubbling beaker. Medium tracking shot, eye level. Native audio: the supplied lab room-tone plus paw steps. No logos, no readable text, no products, no packaging, no prices, no CTA, no advertising, no watermark, no brand marks.",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "audio": true,
    "enable_safety_checker": true,
    "reference_image_urls": [
      "https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0-prime/reference-to-video/v1/01/input-01.webp",
      "https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0-prime/reference-to-video/v1/01/input-02.webp"
    ],
    "reference_video_urls": [
      "https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0-prime/reference-to-video/v1/01/input-motion.mp4"
    ],
    "reference_audio_urls": [
      "https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0-prime/reference-to-video/v1/01/input-audio.mp3"
    ]
  }
}
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

Input parameters

These are the fields accepted inside input. The request example shows the required top-level model field.

Field	Type	Required	Default	Description
prompt	string	Yes	—	1–20,000 characters after trimming.
reference_image_urls	string[]	Conditional	—	1–10 public image URLs when images are part of the reference set.
reference_video_urls	string[]	Conditional	—	1–5 public video URLs when videos are part of the reference set.
reference_audio_urls	string[]	Conditional	—	1–5 public audio URLs when audio is part of the reference set. May be the only reference type.
reference_file_urls	string[]	Conditional	—	Exactly one public file URL; mutually exclusive with reference_link_urls.
reference_link_urls	string[]	Conditional	—	Exactly one public link URL; mutually exclusive with reference_file_urls.
duration	integer	No	5	An integer from 2 through 30, inclusive.
resolution	string	No	720p	480p, 720p, or 1080p.
aspect_ratio	string	No	adaptive	adaptive, 16:9, 4:3, 1:1, 3:4, or 9:16.
audio	boolean	No	true	Whether to request an audio track; does not change the credit rate.
seed	integer	No	—	Optional integer from 0 through 2147483647.
enable_safety_checker	boolean	No	true	Whether to enable the safety checker.

Response Fields

Submission returns task identity immediately. Status responses add progress, every output file, or a failure message.

Field	Type	Description
code	integer	Application result code; successful responses use 0 or 200.
message	string	Human-readable message or error detail when present.
data.task_id	string	Task ID used in the status endpoint path.
data.status	string	not_started, running, finished, or failed.
data.created_time	string	Task creation time in date-time format.
data.progress	integer	Generation progress from 0 to 100, when available.
data.files[]	array	All output files from a successful task, in response order.
data.files[].file_url	string	Public URL for a generated video.
data.files[].file_type	string	File type, such as video.
data.error_message	string \| null	Failure detail when status is failed.

Task Lifecycle

Treat not_started and running as non-terminal states. finished and failed are terminal alternatives; stop polling when either is returned.

not_started
The task was accepted and is waiting to begin.
running
Generation is in progress. Continue polling the same task_id.
finished
Generation succeeded. Read every video URL from data.files[].file_url.
failed
Generation stopped with an error. Read data.error_message and stop polling.

Polling and Errors

AuthenticationA 401 response means the Bearer API key is missing or invalid. Correct it before retrying.
ValidationA 400 response identifies an invalid field, unsupported media key, or insufficient credit balance. Correct the request before resubmitting.
Network and timeoutA transport failure is different from a failed task. Retry status checks with a bounded timeout before deciding that the task failed.
Polling intervalStart around every 2 seconds and increase the interval gradually for a long-running task.
Terminal statesContinue only for not_started or running. Stop immediately on finished or failed.
Callback optionProvide callback_url at the request top level to receive the final flat task object; polling remains available if delivery fails.

Endpoint limits

Specification	Value	Details
Input mode	Prompt + references	Requires prompt and at least one reference field among images, videos, audio, file, or link.
Output	Video task	The endpoint returns an asynchronous task ID.
Resolution	480p / 720p / 1080p	resolution defaults to 720p when omitted.
Duration	2–30 seconds	Every integer value in the inclusive range is valid; default is 5.
Aspect ratio	Adaptive + 5 fixed	adaptive, 16:9, 4:3, 1:1, 3:4, or 9:16.
Billing basis	Output seconds	480p uses 13.6 credits/s; 720p uses 28 credits/s; 1080p uses 56 credits/s.

View Wan 3.0 Prime Reference-to-Video API documentation

Wan 3.0 Prime Reference-to-Video

Wan 3.0 Prime Reference-to-Video generates continuous clips with optional synchronized sound from a required prompt and mixed references. It brings subject appearance, motion rhythm, camera language, and sonic cues from those assets into a new scene when each reference is given a clear role.

Why Choose This?

Reference-to-VideoCombine a prompt with image, video, audio, file, or link references to generate a new continuous scene.
Subject continuityCarry a recurring character, product, voice, or room into a prompt-driven clip instead of rebuilding identity from text alone.
Multimodal reference rolesUse up to 10 images, 5 videos, and 5 audio clips, or one file / one link, and assign each asset a clear creative job.
Native audio syncKeep audio enabled to generate synchronized dialogue, ambience, effects, or music with the picture.
Layered prompt directionMap each reference to identity, motion, camera, or sound, then describe the new scene timeline.
Delivery specsOutput 480p, 720p, or 1080p video from 2–30 seconds with adaptive or fixed aspect ratios.

Parameters

Parameter	Requirement	Description
prompt	Required	String. Defines how each reference contributes to the new scene; 1–20,000 characters after trimming.
reference_image_urls	Conditional	String array of 1–10 public image URLs. Uses images to guide identity, appearance, composition, environment, or style.
reference_video_urls	Conditional	String array of 1–5 public video URLs. Uses videos to guide action, camera movement, blocking, pace, or shot rhythm.
reference_audio_urls	Conditional	String array of 1–5 public audio URLs. Uses audio to guide ambience, rhythm, voice character, or sound direction.
reference_file_urls	Conditional	String array with exactly one public file URL when a packaged reference file is the source. Mutually exclusive with reference_link_urls.
reference_link_urls	Conditional	String array with exactly one public link URL when a linked reference pack is the source. Mutually exclusive with reference_file_urls.
duration	Optional	Integer. Sets output length from 2 through 30 seconds, inclusive; default is 5.
resolution	Optional	String. Sets output resolution; default is 720p. `480p720p1080p`
aspect_ratio	Optional	String. Controls output framing; default is adaptive. `adaptive16:94:31:13:49:16`
audio	Optional	Boolean. Requests a generated audio track; default is true. The audio toggle does not change the credit rate. `truefalse`
seed	Optional	Integer. Optional reproducibility seed from 0 through 2147483647.
enable_safety_checker	Optional	Boolean. Enables the safety checker; default is true. `truefalse`

How to Use

Decide each asset's roleLabel whether a reference controls character identity, product look, environment, motion, camera path, voice, or rhythm.
Add the reference anchorsProvide at least one of reference_image_urls, reference_video_urls, reference_audio_urls, reference_file_urls, or reference_link_urls within the allowed counts.
Map relationships in the promptWrite the mapping plainly: first image for the presenter, first video for walking pace, first audio for room tone.
Set durationChoose an integer from 2 through 30 seconds; the default is 5 for first drafts.
Choose resolutionSelect 480p for role checks, or 720p / 1080p for review and delivery.
Choose aspect ratioPick adaptive, 16:9, 4:3, 1:1, 3:4, or 9:16 to match the channel framing.
Configure audioKeep audio enabled for synchronized sound; turn it off for a silent clip.
Generate the videoClick Run, then preview which reference roles carried into the clip in the output area.

Pricing

Price depends only on output duration and resolution; the audio toggle does not change the rate.

Usage	Rate	Details
480p	13.6 credits/output sec ($0.068/sec)	2 seconds costs 27.2 credits ($0.136), 5 seconds costs 68 credits ($0.340), and 30 seconds costs 408 credits ($2.04).
720p	28 credits/output sec ($0.14/sec)	2 seconds costs 56 credits ($0.280), 5 seconds costs 140 credits ($0.70), and 30 seconds costs 840 credits ($4.20).
1080p	56 credits/output sec ($0.28/sec)	2 seconds costs 112 credits ($0.560), 5 seconds costs 280 credits ($1.40), and 30 seconds costs 1,680 credits ($8.40).

Best Use Cases

Brand-kit filmsCombine product stills, location photos, short motion refs, and a logo lockup into one on-brand clip driven by a new prompt.
Character or product continuityCarry a character sheet, wardrobe, or product hero into a new performance or demo scene.
Deck or report explainersUse one reference file or public webpage pack to turn structured content into a narrated explainer clip.
Motion and voice-matched cutsPair a subject image with a movement video and a voice or rhythm track for campaign spots that follow those references.
Multi-asset storyboard assemblyAssemble approved visual, motion, and audio references into a single previsualization take for creative review.

Pro Tips

Write the role beside each asset in the prompt: character, wardrobe, product, room, motion, camera, voice, or tempo.
Replace 'use all references' with a relationship: keep the subject from the first image, follow the blocking in the first video, and use the first audio only for tempo.
Stay inside the allowed caps: up to 10 images, 5 videos, 5 audio clips, and exactly one file or one link when using document or webpage input.
Structure the prompt as duration and aspect intent, subject and reference assets, scene and lighting, camera and shot, dialogue and sound, then timeline.
Validate reference roles at 480p / 5 seconds, then render 1080p and longer durations once identity and timing hold.

Notes

Provide at least one reference array; reference_file_urls and reference_link_urls are mutually exclusive.
Generation is asynchronous; retain task_id and stop tracking when the task reaches finished or failed.

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

Wan 3.0Use the standard Wan 3.0 family for the same three workflows at a lower per-second rate.

Gemini Omni 1.1 FlashCompare prompt-driven native audio video generation from Google DeepMind.

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

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

Wan 3.0 Prime Reference To Video API — Frequently asked questions

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

Wan 3.0 Prime Reference-to-Video is an Alibaba Tongyi Lab model for generating high-definition video from multimodal references. It combines natural-language prompts with multiple 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 Wan 3.0 Prime's upgraded multimodal fusion architecture, it maintains strict character facial identity, movement rhythm, and visual style across shots in brand-new narrative environments. You can call it programmatically or try it from the playground above.

What multi-asset fusion upgrades does Wan 3.0 Prime Reference-to-Video offer over Wan 3.0?

Wan 3.0 Prime features enhanced multi-modal asset feature alignment and cross-modal reasoning. When ingesting multiple references (such as character portraits, prop photos, and motion reference clips simultaneously), it maps identity, motion dynamics, and acoustic cues with significantly higher fidelity and visual cohesion.

Can Wan 3.0 Prime Reference-to-Video ingest PPT or PDF documents?

Yes. By providing a document URL in reference_file_urls (supporting PPT, PPTX, PDF, DOCX, TXT, MD), the model analyzes slide graphics, layout hierarchy, and textual knowledge to produce structured, narrated video presentations.

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

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

How do I assign roles to multiple references in Wan 3.0 Prime Reference-to-Video?

Use clear role-assignment tagging in your prompt, such as "Use Reference Image 1 for the character's face, Reference Image 2 for the costume, and Reference Video 1 for the walking pace." Explicit mapping guides the model to bind each asset to the correct entity.

How does Wan 3.0 Prime Reference-to-Video synthesize native audio?

When reference_audio_urls are provided, the model incorporates reference vocal tone, cadence, or ambient music into the scene. If no audio assets are supplied, it generates matching environmental soundscapes and Foley effects derived from prompt and visual cues.

What are the reference image specifications for Wan 3.0 Prime Reference-to-Video?

You can include up to 10 reference images (JPEG, PNG, WebP up to 30MB each). Supplying multi-angle views—such as front portraits, profile perspectives, and wardrobe details—gives the model comprehensive geometric data to maintain character consistency across dynamic takes.