Wan Video API

This page specifies the Alibaba Wan video models wan3.0-video and wan3.0-video-prime. They share the POST /v1/videos create and GET /v1/videos/{id} polling flow with the other video models; authentication, media upload, polling states, downloads and error handling are covered in the Complete Video API Standard. This page lists only the fields and rules specific to Wan. Wan can also be submitted with POST /v1/responses; see "Calling via the Responses API" below.

Updated 2026-10-12. The former wan3.0-video-480p, wan3.0-video-720p and wan3.0-video-1080p are merged into wan3.0-video; choose the resolution with resolution. First frames, last frames and reference media are best sent in the top-level media array (first_frame, last_frame, reference_image, ...). metadata.firstFrame, metadata.lastFrame, metadata.referenceImages, metadata.referenceVideos and metadata.referenceAudios (and snake_case forms such as metadata.first_frame) as well as a top-level firstFrame / first_frame or lastFrame / last_frame are also accepted and converted to media; they cannot be combined with media. Material fields that cannot be read return a 400 error. Wan supports polling only; do not send callback_url.

Models

The two models have the same capabilities: resolution, duration, ratio, first/last-frame and multi-reference rules are identical, the request parameters are interchangeable, and switching only means changing model. The difference is generation speed: wan3.0-video-prime is the high-speed version with noticeably faster end-to-end generation, suited to cases where you need the finished video as soon as possible; wan3.0-video is the standard version and is the right choice when turnaround time is not critical.

Common rules

• Resolution: top-level resolution is 480p, 720p or 1080p (case-insensitive); defaults to 1080P. A pixel size such as 1280x720 or 1920x1080 sets both resolution and ratio; size can also carry a ratio (for example "size": "9:16"), and a value that differs from ratio/aspect_ratio returns 400.
• Duration: whole seconds in duration (or seconds); -1 lets the model choose the duration.
• Aspect ratio: use ratio (or the equivalent aspect_ratio); if both are sent and differ, the request returns 400. adaptive follows the input media.
• Prompt: may be omitted when a first frame or references are supplied, but describing motion and camera is recommended; a request with neither returns 400.
• Optional fields:
  • negative_prompt;
  • prompt_extend: rewrite the prompt automatically, boolean, default true;
  • watermark: boolean;
  • seed: integer from -1 to 2147483647.

{
  "model": "wan3.0-video",
  "prompt": "A silver sports car in a rainy city at night, low tracking shot, neon reflections, cinematic",
  "duration": 10,
  "resolution": "1080p",
  "ratio": "16:9"
}

First frame and first/last frames

Put the first and last frames in the media array: first_frame is the first frame and last_frame the last frame (a last frame requires a first frame). Reference images also go in media (reference_image); see the next section.

{
  "model": "wan3.0-video-prime",
  "prompt": "Transition smoothly from an empty square at dawn to the same view at night with the lights on",
  "duration": 8,
  "resolution": "720p",
  "media": [
    { "type": "first_frame", "url": "https://cdn.example.com/start.jpg" },
    { "type": "last_frame", "url": "https://cdn.example.com/end.jpg" }
  ]
}

Multi-reference: the media array

Put reference images, videos and audio in a top-level media array of { "type": "...", "url": "..." } items:

• Keyframes cannot be combined with reference images, videos or audio.
• When media is present, only media is read; if images, image or similar fields contain media that media does not include, the request returns 400. Put keyframes in media too.
• Media URLs must be anonymously readable; see Media URL requirements. Upload local files first through Local media upload. Wan does not accept multipart/form-data file uploads.

{
  "model": "wan3.0-video",
  "prompt": "The person from the image dances to the reference audio, moving like the reference video",
  "duration": 10,
  "resolution": "720p",
  "ratio": "9:16",
  "media": [
    { "type": "reference_image", "url": "https://cdn.example.com/dancer.jpg" },
    { "type": "reference_video", "url": "https://cdn.example.com/dance-motion.mp4" },
    { "type": "reference_audio", "url": "https://cdn.example.com/music.mp3" }
  ]
}

Calling via the Responses API

Both models can also be submitted with POST /v1/responses, which suits clients or workflows that can only call the Responses API. It creates the same video task as /v1/videos, with identical parameter rules and billing.

• Prompt goes in input: either a string or a message array. input_text parts in the messages become the prompt and input_image parts become image materials, following the same rule as the top-level images (1st image = first frame, 2nd image = last frame).
• Other parameters (resolution, duration, ratio, media, negative_prompt, ...) stay at the top level of the request, written as described above.
• There are three ways to get the result:

{
  "model": "wan3.0-video-prime",
  "input": "A silver sports car in a rainy city at night, low tracking shot, neon reflections, cinematic",
  "duration": 5,
  "resolution": "720p",
  "ratio": "16:9",
  "background": true
}

When the video is ready, its URL is in output[0].content[0].text as <video controls src="video URL"></video>; take the src value to download it:

{
  "id": "resp_BVQwZLWyXB2dEU99F7nrER7XNJdVh8RS",
  "object": "response",
  "model": "wan3.0-video-prime",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        { "type": "output_text", "text": "<video controls src=\"https://...\"></video>" }
      ]
    }
  ],
  "metadata": {
    "task_id": "task_BVQwZLWyXB2dEU99F7nrER7XNJdVh8RS",
    "task_status": "completed"
  }
}

metadata.task_id is the matching video task ID; you can also query the same task with GET /v1/videos/{task_id}.

Billing

wan3.0-video and wan3.0-video-prime are official versions; task result URLs are official. Billing follows the official rule:

Billed duration = input video duration + output video duration

• Input video duration: the actual seconds of reference video you send; 0 when there is no reference video.
• Output video duration: the seconds of video successfully generated.
• The per-second unit price is the output-resolution tier (480P / 720P / 1080P). Input and output video use the same tier.
• Reference images, reference audio, files and web pages are not added to billed duration.
• With a reference video, or with duration -1, 30 seconds are reserved at submission; after completion the charge is settled to the input-plus-output seconds reported by the model platform and the unused reservation is refunded.

Use the current model-square unit prices. Do not estimate a reference-video task from output seconds alone.