DocsICP FilingConsole
官方文档
首页

Wan3.0 - Video Generation API Reference

更新时间：
复制 MD 格式
产品详情
我的收藏

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. 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.

Note

The sample code in this topic applies to the Beijing 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

Beijing

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Singapore

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Note

  • 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

File Reference to Video

Pass in a file through the file type, and the model automatically understands the file content to generate a video.

curl --location 'https://{WorkspaceId}.cn-beijing.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
    }
}'

Reference-based Video Generation

Pass in reference images, videos, audio, files, or web links through input.media, and the model automatically understands the intent to generate a video.

curl --location 'https://{WorkspaceId}.cn-beijing.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": "Video 1 holds Image 3 and plays a soothing country folk song on the chair in Image 4, saying: '\''The sunshine is so nice today.'\'' Image 1 holds Image 2, passes by Video 1, places Image 2 on the table next to Video 1, and says: '\''That sounds beautiful, can you sing it again?'\''",
        "media": [
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg"
            },
            {
                "type": "reference_video",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
            }
        ]
    },
    "parameters": {
        "resolution": "480P",
        "ratio": "adaptive",
        "duration": 5
    }
}'

Text-to-Video

Generate a video using only prompt, without passing in any media files.

curl --location 'https://{WorkspaceId}.cn-beijing.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 kitten running on a rooftop under the moonlight, neon lights of the city flickering in the distance, cinematic quality, smooth camera movement."
    },
    "parameters": {
        "resolution": "480P",
        "ratio": "adaptive",
        "duration": 5
    }
}'

First Frame to Video

Strictly specify the first frame image of the video using first_frame.

curl --location 'https://{WorkspaceId}.cn-beijing.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": "An urban fantasy art scene. A dynamic graffiti art character. A spray-painted teenager coming to life from a concrete wall. He raps at an extremely fast pace while striking a classic, energetic rapper pose. The scene is set under a railway bridge at night with an urban vibe. Lighting comes from a solitary streetlamp, creating a cinematic atmosphere full of high energy and stunning detail. The audio of the video consists entirely of rap, with no other dialogue or noise.",
        "media": [
            {
                "type": "first_frame",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/wpimhv/rap.png"
            }
        ]
    },
    "parameters": {
        "resolution": "480P",
        "ratio": "adaptive",
        "duration": 5
    }
}'

First-Last Frame to Video

Pass in both first_frame and last_frame to strictly specify the first and last frame images of the video.

curl --location 'https://{WorkspaceId}.cn-beijing.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 young girl gradually transitions from a smile to laughter, the camera slowly pushing in, background lighting shifting from cool to warm tones.",
        "media": [
            {
                "type": "first_frame",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/wpimhv/rap.png"
            },
            {
                "type": "last_frame",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg"
            }
        ]
    },
    "parameters": {
        "resolution": "480P",
        "ratio": "adaptive",
        "duration": 5
    }
}'
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.

Important

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. Fixed value: wan3.0-video.

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.

Important

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:

    • Supports HTTP or HTTPS protocol.

    • Example: https://xxx/xxx.png.

  2. Temporary URL:

  3. 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:

    • Supports HTTP or HTTPS protocol.

    • Example: https://xxx/xxx.mp4.

  2. Temporary 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:

    • Supports HTTP or HTTPS protocol.

    • Example: https://xxx/xxx.mp3.

  2. Temporary 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:

    • Supports HTTP or HTTPS protocol.

    • Example: https://xxx/xxx.pdf.

  2. Temporary URL:

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].

watermark boolean (Optional)

Whether to add a watermark.

  • false: Default value, no watermark is added.

  • true: A watermark is added.

Response parameters

Successful 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"
}

Error response

Task creation failed. See Error codes.

{
    "code": "InvalidApiKey",
    "message": "No API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

output object

Task output information.

Properties

task_id string

The task ID. Valid for queries for 24 hours.

task_status string

The status of the task.

Enumeration values

  • PENDING

  • RUNNING

  • SUCCEEDED

  • FAILED

  • CANCELED

  • UNKNOWN: The task does not exist or its status is unknown.

request_id string

Unique request identifier for tracing and troubleshooting.

code string

Error code. Returned only for failed requests. See Error codes.

message string

Detailed error message. Returned only for failed requests. See Error codes.

Step 2: Query results by task ID

Beijing

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

Singapore

GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

Note

  • 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_id validity: 24 hours. After this period, queries return the task status as UNKNOWN.

  • RPS limit: The default RPS for the query API is 20. For higher-frequency queries or event notifications, we recommend that you configure an asynchronous task callback.

  • More operations: For batch queries, task cancellation, and other operations, see Manage asynchronous tasks.

Request parameters

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}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
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.

Response parameters

Task succeeded

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"
    }
}

Task failed

When a task fails, task_status is FAILED with an error code and message. See Error codes.

{
    "request_id": "e5e57877-c0fc-47ed-8fad-xxxxxx",
    "output": {
        "task_id": "eff1443c-ccab-4676-aad3-xxxxxx",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "The two modes are mutually exclusive. Do not pass reference_xx and first_frame/last_frame at the same time."
    }
}

Task query expired

The task_id is valid for 24 hours. After this period, queries return the following error.

{
    "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
    "output": {
        "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
        "task_status": "UNKNOWN"
    }
}

output object

Task output information.

Properties

task_id string (Required)

The ID of the task.

task_status string

Task status.

Enumeration values

  • PENDING

  • RUNNING

  • SUCCEEDED

  • FAILED

  • CANCELED

  • UNKNOWN: The task does not exist or its status is unknown.

submit_time string

The time when the task was submitted. format is YYYY-MM-DD HH:mm:ss.SSS.

scheduled_time string

The time when the task was executed. format is YYYY-MM-DD HH:mm:ss.SSS.

end_time string

The time when the task was completed. format is YYYY-MM-DD HH:mm:ss.SSS.

orig_prompt string

The original input prompt.

video_url string

URL of the generated video. Returned when the task succeeds.

code string

Error code. Returned only for failed requests. See Error codes.

message string

Detailed error message. Returned only for failed requests. See Error codes.

usage object

Output statistics. Only counts successful results.

Properties

video_count integer

Number of generated videos. Fixed at 1.

duration float

Duration of the generated video, in seconds.

input_video_duration float

Duration of the input video, in seconds. Returns 0.0 when no video is provided as input.

output_video_duration float

Duration of the output video, in seconds.

fps integer

Frame rate of the generated video.

SR integer

Resolution of the generated video. Example: 720.

ratio string

Aspect ratio of the generated video. Example: 16:9.

request_id string

Unique request identifier for tracing and troubleshooting.
Previous：WanNext：Wan2.7 - image-to-video