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.
- Select a model: Go to the Model Gallery to select a model and confirm the region it belongs to.
- Select a URL: Select the Endpoint URL for the corresponding region.
- Configure API Key: Select a region and Obtain an API key, then Configure API key as an environment variable.
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{WorkspaceId} with your actual workspace ID.
- After the task is created, use the returned
task_idto query the result. Thetask_idis 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 parametersRequest headers (Headers)Content-Typestring (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.Request body (Request Body)modelstring (Required)Model name. Valid values:
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.
Properties type string (Required)Media asset type. Valid values:
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:
Input video (type=reference_video) Reference video URL.Video limits:
Input audio (type=reference_audio) Reference audio URL.Audio limits:
Input file (type=file) File URL.File limits:
Input web link (type=link) URL of a public web page. Only supports parsing publicly accessible web pages that do not require login (such as news, blogs, public accounts, etc.).Supported input formats:
object (Optional)Video processing parameters.
Properties resolution string (Optional)Resolution tier of the generated video. Default value: 1080P. Valid values:
string (Optional)Aspect ratio of the generated video. Valid values:
integer (Optional)Duration of the generated video, in seconds. Default value: 5.
boolean (Optional)Whether the output video contains audio.
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.
boolean (Optional)Whether to add a watermark.
|
Pass in a file through the file type, and the model automatically understands the file content to generate a video. |
Response parametersoutputobjectTask output information.
Properties task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.
Enumeration values
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. |
Save the task_id to query the task status and result. |
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 asUNKNOWN.
Request parametersRequest headers (Headers)Authorizationstring (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.URL path parameters (Path parameters)task_idstring (Required)The ID of the task. |
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. |
Response parametersoutputobjectTask output information.
Properties task_id string (Required)The ID of the task.task_status stringTask status.
Enumeration values
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.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.stringUnique request identifier for tracing and troubleshooting. |
Video URLs are valid for only 24 hours and then automatically purged. Save generated videos promptly. |