Wan 3.0 Prime Image-to-Video API

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

Wan 3.0 Prime (Image-to-Video) transforms a start-frame image and text prompt into a continuous video up to 30 seconds, with optional end-frame guidance, native audio-visual sync, and output up to 1080p. It carries the source subject, composition, and style into motion while adding action, camera movement, and sound.

Input

Prompt

514/20000

Start frame

Add start

A start frame is required; the end frame is never promoted automatically.

End frame

Add end

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 Reference-to-Video Gemini Omni 1.1 Flash Image-to-Video MiniMax H3 Image-to-Video

Examples

Begin from the first frame. One continuous 4-second 16:9 shot: the eyed toast slides straight toward the lens on a thin butter trail, eyes widening, until it nearly fills the frame. Locked low table-level camera. Native audio: bread scrape on laminate, a tiny squeak, quiet kitchen room tone. No logos, no readable text, no products, no packaging, no prices, no CTA, no advertising, no watermark, no brand marks.

Begin from the first frame. One continuous 4-second 3:4 shot: the diving-helmet cat slowly turns its head toward the goldfish in the open briefcase. Preserve the same cat, helmet, briefcase, fish, and desk. Locked camera. Native audio: helmet metal tick, water slosh in the pouch, soft room tone. 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.

Submit request

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "alibaba/wan-3.0-prime/image-to-video",
  "input": {
    "prompt": "Begin on the first frame and finish on the last. One continuous 5-second shot: the garden gnome leans, tips, and launches from the pond rim, arcing through the air until it matches the mid-air crash into the koi pond. Preserve the same gnome, pond, koi, plants, and late-afternoon light. Slight handheld follow, no cuts. Native audio: stone scrape, wind whoosh, water slap, startled koi splash. 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": "adaptive",
    "audio": true,
    "enable_safety_checker": true,
    "image_urls": [
      "https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0-prime/image-to-video/v1/01/input-start-frame.webp",
      "https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0-prime/image-to-video/v1/01/input-end-frame.webp"
    ]
  }
}
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/image-to-video",
  "input": {
    "prompt": "Begin on the first frame and finish on the last. One continuous 5-second shot: the garden gnome leans, tips, and launches from the pond rim, arcing through the air until it matches the mid-air crash into the koi pond. Preserve the same gnome, pond, koi, plants, and late-afternoon light. Slight handheld follow, no cuts. Native audio: stone scrape, wind whoosh, water slap, startled koi splash. 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": "adaptive",
    "audio": true,
    "enable_safety_checker": true,
    "image_urls": [
      "https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0-prime/image-to-video/v1/01/input-start-frame.webp",
      "https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0-prime/image-to-video/v1/01/input-end-frame.webp"
    ]
  }
}
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
image_urls	string[]	Yes	—	One or two public image URLs in Start, optional End order.
prompt	string	No	—	Optional; 1–20,000 characters after trimming when provided.
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	Task progress from 0 to 100, when included in the response.
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	Image + optional text	image_urls requires 1–2 frames; prompt is optional for motion direction.
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 Image-to-Video API documentation

Wan 3.0 Prime Image-to-Video

Wan 3.0 Prime Image-to-Video generates continuous clips with optional synchronized sound from a start-frame image and an optional text prompt. It preserves the opening subject, composition, and lighting while adding subject motion, camera movement, scene progression, and sound; an optional second image can guide the closing state.

Why Choose This?

Image-to-VideoAnimate an approved still into a continuous clip by providing one or two public image URLs.
Preserve source featuresCarry the start frame's subject identity, composition, lighting, and style into the generated motion.
Optional end-frame guidanceAdd a second image in image_urls when the final pose, product state, or composition needs a visible destination.
Native audio syncKeep audio enabled to generate synchronized ambience, action sounds, dialogue, or music with the animated still.
Prompt-led motion controlDescribe subject action, camera path, lighting change, and atmosphere after the opening frame.
Delivery specsOutput 480p, 720p, or 1080p video from 2–30 seconds with adaptive or fixed aspect ratios.

Parameters

Parameter	Requirement	Description
image_urls	Required	String array with one or two public, directly downloadable URLs. The first image is Start; the optional second image is End. Preserve this order.
prompt	Optional	String. Directs action, camera movement, visual change, and sound intent after the start frame; 1–20,000 characters after trimming when provided.
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

Upload the start frameProvide a clear public image URL that already holds the subject, composition, lighting, and style you want at frame one.
Add an end frame (optional)When the closing pose or product state needs a visual destination, add a second compatible image URL.
Describe the motionWrite what happens after the still: subject action, camera path, lighting change, and sound intent.
Set durationChoose an integer from 2 through 30 seconds; the default is 5 for first drafts.
Choose resolutionSelect 480p for motion 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 delivery framing.
Configure audioKeep audio enabled for synchronized sound; turn it off for a silent clip.
Generate the videoClick Run, then preview picture and sound together in the output area when the task finishes.

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

Product stills into motionTurn an approved product photo into a showcase clip with rotation, material movement, or a light change for launch teasers.
Poster and key visual animationAnimate a locked campaign still into a short motion asset for social, display, or presentation use.
Open-and-close transitionsConnect compatible first and last frames into a transition study for a reveal or composition change.
Character keyframe performanceUse a portrait or character still, then prompt expression, gesture, and camera response into a performance clip.
Concept art into shotsBring a concept painting into a short exploratory shot to evaluate motion and framing before production.

Pro Tips

Treat the start image as the opening sentence; use the prompt for what happens next instead of restating visible details.
Replace 'make the portrait move' with a visible progression: she looks toward the window, exhales, then turns back as the camera slowly pushes in.
When using a second image, keep identity, lighting logic, and art direction compatible across both stills.
Structure the prompt as subject action, scene and lighting, camera and shot, dialogue and sound, then timeline.
Validate motion at 480p / 5 seconds, then render 1080p and longer durations once the action plan holds.

Notes

image_urls requires 1–2 public http(s) URLs; the first is Start and the optional second is End.
Generation is asynchronous; retain task_id and stop tracking when the task reaches finished or failed.

Wan 3.0 Prime Reference-to-VideoCombine images, video, audio, documents, or webpages to keep identity across a new scene.

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 Image To Video API — Frequently asked questions

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

Wan 3.0 Prime Image-to-Video is an Alibaba Tongyi Lab model for generating high-definition video from images. It animates static starting frames into continuous takes up to 30 seconds at up to 1080p resolution with native audio, supporting an optional ending frame for precise end-state control. Built on Wan 3.0 Prime's upgraded spatiotemporal alignment architecture, it preserves source facial likeness, intricate apparel textures, and lighting environments while delivering enhanced physical motion dynamics. You can call it programmatically or try it from the playground above.

What motion improvements does Wan 3.0 Prime Image-to-Video provide over Wan 3.0?

Wan 3.0 Prime substantially improves character facial stability, joint articulation, and complex physical dynamics (such as hair sway, flowing water, and fabric motion) under significant camera movements, greatly reducing distortion when animating from static images.

How do I guide video transitions with an end frame in Wan 3.0 Prime Image-to-Video?

Provide two image URLs in the image_urls array, where the first acts as the start frame and the second defines the closing frame. The model calculates spatiotemporal interpolation between both compositions, generating smooth intermediate dynamics and camera shifts across your chosen duration.

Does Wan 3.0 Prime Image-to-Video synthesize synchronized sound for photos?

Yes. With joint audiovisual diffusion, the model automatically analyzes visual context and prompt descriptions to synthesize matching ambient acoustics, motion foley, and impact sounds without requiring external audio inputs.

How can I ensure subject identity consistency in Wan 3.0 Prime Image-to-Video?

Upload a clear, well-lit starting image with distinct facial or product features, and describe specific motion directions in the prompt while avoiding contradictory character changes. The model anchors identity features directly from the initial still.

Does Wan 3.0 Prime Image-to-Video support 9:16 vertical video?

Yes. When aspect_ratio is set to adaptive, the output matches the aspect ratio of the first input image. You can also explicitly specify 9:16 to adapt horizontal source stills into vertical video compositions optimized for mobile feeds.

Can Wan 3.0 Prime Image-to-Video generate motion without a text prompt?

Yes. If no prompt is provided, the model automatically infers plausible physical dynamics and camera drift based on the image's scene content. Adding prompt text allows you to direct explicit trajectories, character actions, and sound design.