Skip to main content
Wan

Wan3.0 - Video Generation API Reference

Wan3.0 is an All-in-One reference-based video generation model that supports Text-to-Video , Image-to-Video (first frame/first-last frame), and Reference-based Video Generation . It can generate videos up to 30 seconds long at 30fps. Currently in preview .

Prerequisites

To ensure a successful API call, make sure that the model, Endpoint URL and API Key all belong to the same region. Cross-region calls will fail.
The sample code in this topic applies to the Singapore region.

HTTP call

Since video generation tasks take a relatively long time (typically 1-5 minutes), the API uses asynchronous calls. The entire process consists of two core steps: "Create a task -> Poll for results", as described below:

Step 1: Create a task and obtain the task ID

  • Singapore
  • Beijing
  • US (Virginia)
  • Japan (Tokyo)
  • Germany (Frankfurt)
  • China (Hong Kong)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
Replace {WorkspaceId} with your actual workspace ID.
  • After the task is created, use the returned task_id to query the result. The task_id is valid for 24 hours. Do not create duplicate tasks. Instead, use polling to retrieve the result.
  • For guidance for beginners, see Call APIs with Postman or cURL.

Request parameters

Request headers (Headers)
Content-Type string (Required)The content type of the request. Must be application/json.Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.X-DashScope-Async string (Required)Enables asynchronous processing. HTTP requests support only asynchronous calls. Must be enable.
If this request header is missing, the error "current user api does not support synchronous calls" is returned.
Request body (Request Body)
model string (Required)Model name. Valid values:
  • wan3.0-video-prime: High-speed version with capabilities aligned to the standard version, with significantly improved end-to-end speed.
  • wan3.0-video: Standard version.
input object (Required)Basic input information. Either prompt or media must be provided.

Properties

prompt string (Conditionally required)Text prompt used to describe the desired video content. Either this or media must be provided.Supports both Chinese and English. Each Chinese character or letter counts as one character, with a maximum of 20,000 characters. Content exceeding this limit will be automatically truncated.In reference mode, you can use "Image 1", "Video 1", etc. in the prompt to refer to media assets in the corresponding order within the media array.media array (Conditionally required)Media asset array that supports images, videos, audio, files, and web pages as input. Either this or prompt must be provided.
  • Each element in the array is a media object containing the type and url fields.
  • In reference-based video generation mode, the array order defines the reference order of assets in the prompt. Images and videos are counted separately, meaning Image 1 and Video 1 can coexist.
    • The 1st reference_video in the array corresponds to Video 1, the 2nd corresponds to Video 2, and so on.
    • The 1st reference_image in the array corresponds to Image 1, the 2nd corresponds to Image 2, and so on.
    • The 1st reference_audio in the array corresponds to Audio 1, the 2nd corresponds to Audio 2, and so on.

Properties

type string (Required)Media asset type. Valid values:
  • first_frame: First frame image. Maximum 1 image, strictly used as the first frame of the video.
  • last_frame: Last frame image. Maximum 1 image, strictly used as the last frame of the video.
  • reference_image: Reference image. Maximum 10 images.
  • reference_video: Reference video. Maximum 5 clips, with a total duration of no more than 15 seconds.
  • reference_audio: Reference audio. Maximum 5 clips, with a total duration of no more than 15 seconds.
  • file: File. Maximum 1 file, cannot be used together with link.
  • link: Web link. Maximum 1 link, cannot be used together with file.
The reference_xx/file/link types and first_frame/last_frame types are mutually exclusive and cannot be used together in the same request.
url string (Required)Media asset URL or Base64 encoded data.

Input image (type=first_frame / last_frame / reference_image)

Image URL or Base64 encoded data.Image limits:
  • Format: JPEG, JPG, PNG (transparent channel not supported), BMP, WEBP.
  • Resolution: [240, 8000] pixels per side.
  • Aspect ratio: no more than 8:1.
  • File size: no more than 20MB.
Supported input formats:
  1. Public URL:
  2. Base64 encoded image string:
    • Data format: data:{MIME_type};base64,{base64_data}.
    • Example: data:image/png;base64,GDU7MtCZzEbTbmRZ...... (the encoded string is too long, only a fragment is shown)
    • For details, see Input Image.

Input video (type=reference_video)

Reference video URL.Video limits:
  • Format: mp4, mov.
  • Duration: [1, 15] seconds per clip, with a total duration of no more than 15 seconds.
  • Resolution: [240, 4096] pixels per side.
  • Aspect ratio: no more than 8:1.
  • File size per clip: no more than 100MB.
Supported input formats:
  1. Public URL:

Input audio (type=reference_audio)

Reference audio URL.Audio limits:
  • Format: wav, mp3.
  • Duration: [1, 15] seconds per clip, with a total duration of no more than 15 seconds.
  • File size: no more than 15MB.
Supported input formats:
  1. Public URL:

Input file (type=file)

File URL.File limits:
  • Format: docx, doc, xlsx, xls, pptx, ppt, pdf, txt, key, pages, numbers, md.
  • File size: no more than 100MB.
  • Page limit: no more than 50 pages (validated for pdf, docx, doc, pptx, ppt, key, pages formats).
Supported input formats:
  1. Public URL:

Input web link (type=link)

parameters object (Optional)Video processing parameters.

Properties

resolution string (Optional)Resolution tier of the generated video. Default value: 1080P. Valid values:
  • 1080P
  • 720P
  • 480P
ratio string (Optional)Aspect ratio of the generated video. Valid values:
  • adaptive (Default value): Adaptive aspect ratio that automatically recommends a suitable aspect ratio based on the input media proportions and intent.
  • 16:9
  • 4:3
  • 1:1
  • 3:4
  • 9:16
duration integer (Optional)Duration of the generated video, in seconds. Default value: 5.
  • Without video input: an integer in the range [2, 30].
  • With video input: the total input video duration + output video duration must not exceed 30 seconds.
  • When set to -1: Smart duration mode, where the model automatically recommends a suitable duration based on the input prompt, content, and rich media.
audio boolean (Optional)Whether the output video contains audio.
  • true: Default value, the output video contains audio.
  • false: The output video does not contain an audio track.
Enabling or disabling audio does not affect pricing.seed integer (Optional)Random seed. Used to reproduce generation results. Value range: [0, 2147483647].prompt_extend boolean (Optional)Whether to enable intelligent prompt rewriting. When enabled, a large language model rewrites the input prompt. This significantly improves generation quality for shorter prompts, but increases latency.
  • true: Default value, intelligent rewriting is enabled.
  • false: Intelligent rewriting is disabled.
watermark boolean (Optional)Whether to add a watermark.
  • false: Default value, no watermark is added.
  • true: A watermark is added.
  • File Reference to Video
  • Reference-based Video Generation
  • Text-to-Video
  • First Frame to Video
  • First-Last Frame to Video
  • Video Editing
  • Video Extension
Pass in a file through the file type, and the model automatically understands the file content to generate a video.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan3.0-video",
    "input": {
        "prompt": "A high-end smart glasses product advertisement with a minimalist, futuristic, and fashionable style. The color palette features black, silver-gray, and ice-blue tones with subtle white light accents and parameter UI graphics. Opening in pure black background, a pair of smart glasses slowly emerges from darkness with refined highlights on the temple edges. The camera captures ultra-close details of lenses, nose pads, hinges, temples, and material textures, showcasing metal and high-performance composite materials. The product then rotates slowly in mid-air with minimalist motion graphics displaying core parameters. Then the camera pulls back as all parts precisely reassemble into the complete product, transitioning to a young model wearing demonstration in minimalist spaces and urban lighting environments.",
        "media": [
            {
                "type": "file",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260806/ebapmr/glass.pptx"
            }
        ]
    },
    "parameters": {
        "resolution": "480P",
        "ratio": "adaptive",
        "duration": 10,
        "prompt_extend": true
    }
}'

Response parameters

output objectTask output information.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: The task does not exist or its status is unknown.
request_id stringUnique request identifier for tracing and troubleshooting.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.
  • Successful response
  • Error response
Save the task_id to query the task status and result.
{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Step 2: Query results by task ID

  • Singapore
  • Beijing
  • US (Virginia)
  • Japan (Tokyo)
  • Germany (Frankfurt)
  • China (Hong Kong)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
  • Polling recommendation: Video generation takes several minutes. Use a polling mechanism with a reasonable interval, such as 15 seconds.
  • Task state transition: PENDING → RUNNING → SUCCEEDED or FAILED.
  • Result link: After a task succeeds, a video URL valid for 24 hours is returned. Download and save the video to permanent storage, such as OSS.
  • task_idvalidity: 24 hours. After this period, queries return the task status as UNKNOWN.

Request parameters

Request headers (Headers)
Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.
URL path parameters (Path parameters)
task_id string (Required)The ID of the task.
  • Query task results
Replace {task_id} with the task_id value returned by the previous API call. The task_id is valid for queries for 24 hours, Replace {WorkspaceId} with your actual workspace ID.
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Response parameters

output objectTask output information.

Properties

task_id string (Required)The ID of the task.task_status stringTask status.

Enumeration values

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: The task does not exist or its status is unknown.
submit_time stringThe time when the task was submitted. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringThe time when the task was executed. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.end_time stringThe time when the task was completed. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.orig_prompt stringThe original input prompt.video_url stringURL of the generated video. Returned when the task succeeds.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.
usage objectOutput statistics. Only counts successful results.

Properties

video_count integerNumber of generated videos. Fixed at 1.duration floatDuration of the generated video, in seconds.input_video_duration floatDuration of the input video, in seconds. Returns 0.0 when no video is provided as input.output_video_duration floatDuration of the output video, in seconds.fps integerFrame rate of the generated video. Default value: 30.SR integerResolution of the generated video. Example: 720.ratio stringAspect ratio of the generated video. Example: 16:9.
request_id stringUnique request identifier for tracing and troubleshooting.
  • Task succeeded
  • Task failed
  • Task query expired
Video URLs are valid for only 24 hours and then automatically purged. Save generated videos promptly.
{
    "request_id": "78c9b768-0285-996c-b682-xxxxxx",
    "output": {
        "task_id": "17ed7e50-00cf-4509-aea1-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-08-06 10:01:35.452",
        "scheduled_time": "2026-08-06 10:01:35.507",
        "end_time": "2026-08-06 10:13:33.838",
        "orig_prompt": "A golden retriever running on a sunny beach, waves crashing in the background, cinematic lighting",
        "video_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx/video.mp4"
    },
    "usage": {
        "video_count": 1,
        "duration": 5.0,
        "input_video_duration": 0.0,
        "output_video_duration": 5.0,
        "fps": 30,
        "SR": 720,
        "ratio": "16:9"
    }
}
Text Generation
Image Generation
  • FAQ
Audio
Realtime API
Text Embedding
Model Production