Wan2.1 text-to-video API Reference - Alibaba Cloud Model Studio

This topic describes the input and output parameters of the Wan Text-to-video model.

Model overview

Wan Text-to-video can generate videos from text prompts. The model features powerful instruction-following capabilities, supports complex movements and realistic physics, and produces videos with rich artistic styles and cinematic visual quality.

You can experience it on the Wan official website.

Note

The features on the official website may differ from the capabilities supported by the API. For specific capabilities, refer to those listed in this topic. This topic will be updated promptly when new features are added.

Performance showcase

Sample input	Output video
Prompt: A kitten running in the moonlight

Model introduction

Name	Description
wan2.1-t2v-turbo	Faster generation with balanced performance.
wan2.1-t2v-plus	Richer details and more textured visuals.

Name	Unit price	Rate limits (shared between Alibaba Cloud account and RAM users)		Free quota
		Requests per second (RPS) for task submission	Number of concurrent tasks
wan2.1-t2v-turbo	$0.036/second	2	2	Free quota: 200 seconds each Validity period: 180 days after activation
wan2.1-t2v-plus	$0.10/second	2	2

Learn more about Billing and throttling.

Prerequisites

The text-to-video API supports calls through HTTP and DashScope SDK.

Before you make a call, you must first obtain an API key and set the API key as an environment variable.

If you need to use SDK, you must install the SDK for Python or Java.

HTTP

Text-to-video model processing takes a relatively long time. To avoid request timeouts, HTTP calls only support asynchronous retrieval of model results. You need to make two requests:

Create task: Send a request to create a task, which will return a task ID.
Query results using the ID: Use the task ID to query the results generated by the model.

Text-to-video generation takes a relatively long time (approximately 5-10 minutes). The actual time depends on the number of queued tasks and service execution conditions.

Create task

POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Request parameters	Text-to-video `curl --location 'https://dashscope-intl.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": "wan2.1-t2v-turbo", "input": { "prompt": "A kitten running in the moonlight" }, "parameters": { "size": "1280*720" } }'`
Headers
Content-Type `string` (Required) The type of the request content. This parameter must be set to `application/json`.
Authorization `string` (Required) The identity authentication for the request, which is the Model Studio API key. Example: Bearer d1xxx2a.
X-DashScope-Async `string` (Required) The asynchronous processing parameter. HTTP requests only support asynchronous mode, so this parameter must be set to `enable`.
Request body
model `string` (Required) The model name. Example value: wan2.1-t2v-turbo.
input `object` (Required) Basic input information, such as prompts. Properties prompt `string` (Required) The text prompt. Supports Chinese and English, with a maximum length of 800 characters. Each Chinese character or letter counts as one character. Content exceeding this limit will be truncated. Example value: A kitten running in the moonlight. For tips, see Text-to-video/image-to-video prompt guide.
parameters `object` (Optional) The image processing parameters. Properties size `string` (Optional) The resolution of the generated video. Default value: `1280720`. Here, 1280 represents the width and 720 represents the height. Currently, two video resolution levels are supported: 480P and 720P: wan2.1-t2v-turbo: Supports all resolutions corresponding to 480P and 720P. wan2.1-t2v-plus: Supports all resolutions corresponding to 720P. 480P: Resolutions corresponding to different video aspect ratios are: 16:9: `832480` 9:16: `480832` 1:1: `624624` 720P: Resolutions corresponding to different video aspect ratios: 16:9: `1280720`, default value. 9:16: `7201280` 1:1: `960960` 3:4: `8321088` 4:3: `1088832` Common misconception about the size parameter: The size parameter should be set directly to the specific value of the target resolution (such as `1280720`), not the aspect ratio (such as 1:1) or the resolution level (such as 480P or 720P). duration `integer` (Optional) The duration of the generated video. Default value: 5. Unit: seconds. Currently, fixed as 5. prompt_extend `bool` (Optional) Specifies whether to enable intelligent prompt rewriting. When enabled, an LLM will intelligently rewrite the input prompt. This significantly improves generation results for shorter prompts but increases processing time. true (default) false seed `integer` (Optional) The random seed, used to control the randomness of model-generated content. The value range is `[0, 2147483647]`. If not provided, the algorithm automatically generates a random seed. If you want the generated content to remain relatively stable, you can use the same seed.

Response parameters	Successful response `{ "output": { "task_status": "PENDING", "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx" }, "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx" }` Error response `{ "code":"InvalidApiKey", "message":"Invalid API-key provided.", "request_id":"fb53c4ec-1c12-4fc4-a580-xxxxxx" }`
output `object` The task output information. Properties task_id `string` The task ID. task_status `string` The task status. Valid values PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN
request_id `string` The request ID. It can be used for tracing and troubleshooting.
code `string` The error code for a failed request. This parameter is not returned when the request is successful.
message `string` The error message for a failed request. This parameter is not returned when the request is successful.

Query results by task ID

GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}

Request parameters	Query task results Replace `86ecf553-d340-4e21-xxxxxxxxx` with the actual task_id. `curl -X GET \ --header "Authorization: Bearer $DASHSCOPE_API_KEY" \ https://dashscope-intl.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx`
Headers
Authorization `string` (Required) The identity authentication for the request, which is the Model Studio API key. Example: Bearer d1xxx2a.
Path parameters
task_id `string` (Required) The task ID.

Response parameters	Task succeeded Task data (such as task status and video URL) will be automatically deleted after 24 hours. Save the generated videos promptly. `{ "request_id": "851985d0-fbba-9d8d-a17a-xxxxxx", "output": { "task_id": "208e2fd1-fcb4-4adf-9fcc-xxxxxx", "task_status": "SUCCEEDED", "submit_time": "2025-01-08 16:43:27.877", "scheduled_time": "2025-01-08 16:43:27.908", "end_time": "2025-01-08 16:46:35.304", "video_url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.comc/aa.mp4" "orig_prompt": "A kitten running in the moonlight", "actual_prompt": "" }, "usage": { "video_duration": 5, "video_ratio": "1280*720", "video_count": 1 } }` Task failed If the task fails for some reason, the task status will be set to FAILED, and the code and message fields will show the reason. `{ "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d", "output": { "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010", "task_status": "FAILED", "code": "InvalidParameter", "message": "The size is not match xxxxxx" } }`
output `object` The task output information. Properties task_id `string` The task ID. task_status `string` The task status. Valid values PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN submit_time `string` The time when the task was submitted. scheduled_time `string` The execution duration of the task. end_time `string` The time when the task was completed. video_url `string` The video URL. Use it to download the video. orig_prompt `string` The original input prompt. actual_prompt `string` The actual prompt used after prompt rewriting. This field is not returned if prompt rewriting is not enabled. code `string` The error code for a failed request. This parameter is not returned when the request is successful. message `string` The error message for a failed request. This parameter is not returned when the request is successful.
usage `object` The output statistics. It only counts successful results. Properties video_duration `integer` The duration of the generated video, in seconds. video_ratio `string` The aspect ratio of the generated video. Fixed as `standard`. video_count `integer` The number of generated videos.
request_id `string` The request ID. It can be used for tracing and troubleshooting.

Dashscope SDK

Make sure you have installed the latest version of the DashScope SDK, otherwise you may encounter errors.

DashScope SDK currently supports Python and Java.

The parameter names in the SDK are basically the same as the HTTP interface. The parameter structure depends on the SDK encapsulation of different languages. For parameter descriptions, refer to HTTP.

Because video model processing takes a long time, the underlying service uses an asynchronous approach. The SDK provides encapsulation at the upper layer and supports both synchronous and asynchronous calling methods.

Text-to-Video generation takes a relatively long time (approximately 5-10 minutes). The actual time depends on the number of queued tasks and service execution conditions.

Python

Synchronous

Sample request

from http import HTTPStatus
# dashscope sdk >= 1.22.1
from dashscope import VideoSynthesis
import dashscope

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
def sample_sync_call_t2v():
    # call sync api, will return the result
    print('please wait...')
    rsp = VideoSynthesis.call(model='wan2.1-t2v-turbo',
                              prompt='A kitten running in the moonlight',
                              size='1280*720')
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output.video_url)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))


if __name__ == '__main__':
    sample_sync_call_t2v()

Sample response

video_url is valid for 24 hours. Download the video promptly.

{
	"status_code": 200,
	"request_id": "a250655b-c899-9384-b12e-xxxxxx",
	"code": null,
	"message": "",
	"output": {
		"task_id": "04d3cdfb-8405-4e6b-bb03-xxxxxx",
		"task_status": "SUCCEEDED",
		"video_url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/aaa.mp4",
		"submit_time": "2025-02-12 11:27:12.975",
		"scheduled_time": "2025-02-12 11:29:39.988",
		"end_time": "2025-02-12 11:35:35.801",
		"orig_prompt": "A kitten running in the moonlight", 
		"actual_prompt": ""	
	},
	"usage": {
		"video_count": 1,
		"video_duration": 5,
		"video_ratio": "1280*720"
	}
}

Asynchronous

Sample request

from http import HTTPStatus
# dashscope sdk >= 1.22.1
from dashscope import VideoSynthesis
import dashscope

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
def sample_async_call_t2v():
    # call async api, will return the task information
    # you can get task status with the returned task id.
    rsp = VideoSynthesis.async_call(model='wan2.1-t2v-turbo',
                                    prompt='A kitten running in the moonlight',
                                    size='1280*720')
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print("task_id: %s" % rsp.output.task_id)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))
                           
    # get the task information include the task status.
    status = VideoSynthesis.fetch(rsp)
    if status.status_code == HTTPStatus.OK:
        print(status.output.task_status)  # check the task status
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (status.status_code, status.code, status.message))

    # wait the task complete, will call fetch interval, and check it's in finished status.
    rsp = VideoSynthesis.wait(rsp)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output.video_url)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))


if __name__ == '__main__':
    sample_async_call_t2v()

Sample response

1. Create task

{
	"status_code": 200,
	"request_id": "c86ff7ba-8377-917a-90ed-xxxxxx",
	"code": "",
	"message": "",
	"output": {
		"task_id": "721164c6-8619-4a35-a6d9-xxxxxx",
		"task_status": "PENDING",
		"video_url": ""
	},
	"usage": null
}

2. Query task results

video_url is valid for 24 hours. Download the video promptly.

{
	"status_code": 200,
	"request_id": "efa545b3-f95c-9e3a-a3b6-xxxxxx",
	"code": null,
	"message": "",
	"output": {
		"task_id": "721164c6-8619-4a35-a6d9-xxxxxx",
		"task_status": "SUCCEEDED",
		"video_url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/aaaa.mp4",
		"submit_time": "2025-02-12 11:03:30.701",
		"scheduled_time": "2025-02-12 11:06:05.378",
		"end_time": "2025-02-12 11:12:18.853",
		"orig_prompt": "A kitten running in the moonlight", 
		"actual_prompt": ""
	},
	"usage": {
		"video_count": 1,
		"video_duration": 5,
		"video_ratio": "1280*720"
	}
}

Java

Synchronous

Sample request

// Copyright (c) Alibaba, Inc. and its affiliates.

// dashscope sdk >= 2.18.2
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesis;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisParam;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;

public class Text2Video {
    /**
     * Create a video compositing task and wait for the task to complete.
     */
    static {
     Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
    }
    public static void text2Video() throws ApiException, NoApiKeyException, InputRequiredException {
        VideoSynthesis vs = new VideoSynthesis();
        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .model("wan2.1-t2v-turbo")
                        .prompt("A kitten running in the moonlight")
                        .size("1280*720")
                        .build();
        System.out.println("please wait...");
        VideoSynthesisResult result = vs.call(param);
        System.out.println(JsonUtils.toJson(result));
    }

    public static void main(String[] args) {
        try {
            text2Video();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

Sample response

video_url is valid for 24 hours. Download the video promptly.

{
	"request_id": "db27ee62-1148-9de4-aab9-xxxxxx",
	"output": {
		"task_id": "31c13f64-60e3-4822-b255-xxxxxx",
		"task_status": "SUCCEEDED",
		"video_url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/aaa.mp4"
	},
	"usage": {
		"video_count": 1,
		"video_duration": 5,
		"video_ratio": "1280*720"
	}
}

Asynchronous

Sample request

// Copyright (c) Alibaba, Inc. and its affiliates.

// dashscope sdk >= 2.18.2
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesis;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisParam;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;

public class Text2Video {
    /**
     * Create a video compositing task and wait for the task to complete.
     */
    static {
     Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
    }
    public static void text2Video() throws ApiException, NoApiKeyException, InputRequiredException {
        VideoSynthesis vs = new VideoSynthesis();
        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .model("wan2.1-t2v-turbo")
                        .prompt("A kitten running in the moonlight")
                        .size("1280*720")
                        .build();

        // Asynchronous call
        VideoSynthesisResult task = vs.asyncCall(param);
        System.out.println(JsonUtils.toJson(task));
        System.out.println("please wait...");

        // Obtain the analysis results
        // apiKey is already configured in environment variables, so it can be set to null here
        VideoSynthesisResult result = vs.wait(task, null);
        System.out.println(JsonUtils.toJson(result));
    }

    public static void main(String[] args) {
        try {
            text2Video();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

Sample response

1. Create task

{
        "request_id": "5dbf9dc5-4f4c-9605-85ea-xxxxxxxx",
	"output": {
		"task_id": "7277e20e-aa01-4709-xxxxxxxx",
		"task_status": "PENDING"
	}
}

2. Query task results

video_url is valid for 24 hours. Download the video promptly.

{
	"request_id": "1625235c-c13e-93ec-aff7-xxxxxxxx",
	"output": {
		"task_id": "464a5e46-79a6-46fd-9823-xxxxxxxx",
		"task_status": "SUCCEEDED",
		"video_url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/aaa.mp4"
	},
	"usage": {
		"video_count": 1,
		"video_duration": 5,
		"video_ratio": "1280*720"
	}
}

Error code

If the call failed and an error message is returned, see Error messages.

Specific status codes for this API:

HTTP status code	code	message	Description
400	InvalidParameter	InvalidParameter	The request parameter is invalid.
400	IPInfringementSuspect	Input data is suspected of being involved in IP infringement.	The input data (such as prompts) may involve intellectual property infringement. Check your input to ensure it does not contain such content.
400	DataInspectionFailed	Input data may contain inappropriate content.	The input data (such as prompts) may contain sensitive content. Please check your input and try again.
500	InternalError	InternalError	Service exception. Please try again first to rule out occasional issues.

FAQ

Does the plus model support outputting 480p videos?

No, it does not.

To generate videos with 480P resolution, use the wan2.1-t2v-turbo model and specify the exact resolution value in the size parameter (such as 624*624, corresponding to 480P video).

The output video resolutions supported by the models are:

wan2.1-t2v-turbo: Supports all resolutions corresponding to 480P and 720P.
wan2.1-t2v-plus: Only supports all resolutions corresponding to 720P.

Billing and throttling

Free quota

Overview: Free quota refers to the duration of successfully generated videos. Abnormal input content and model processing failures do not consume the free quota.
How to claim: You automatically get it after activating Model Studio, valid for 180 days.
Account usage: Alibaba Cloud account and its RAM users share the free quota.
Learn more about New user free quota.

Billing description

When billing has a clear unit price, such as $0.10/second, the model has been commercialized. After the free quota is exhausted or expired, you need to pay for usage.
Billing item: Only successfully generated videos are charged. Other situations are not charged.
Payment method: All payments are made by the Alibaba Cloud account. RAM users pay independently. To check your bills, go to Billing Overview.
Recharge channel: You can recharge on the Expenses and Cost page.
Usage statistics: You can check model usage and request counts on the Model Observation page.
Learn more about Billable items.

Throttling

Overview: Alibaba Cloud account and its RAM users share the limits.

Configure domain whitelist to access video URL from OSS

Generated videos are stored in OSS, and each video is assigned an OSS link, such as https://dashscope-result-xx.oss-cn-xxxx.aliyuncs.com/xxx.mp4. OSS links allow public access. You can use this link to download the video. The link is valid for only 24 hours.

If your business has high security requirements and cannot access OSS links, you need to configure a separate whitelist for external network access Add the following domains to your whitelist to access video links.

# OSS domain list
dashscope-result-bj.oss-cn-beijing.aliyuncs.com
dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com
dashscope-result-sh.oss-cn-shanghai.aliyuncs.com
dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com
dashscope-result-zjk.oss-cn-zhangjiakou.aliyuncs.com
dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com
dashscope-result-hy.oss-cn-heyuan.aliyuncs.com
dashscope-result-cd.oss-cn-chengdu.aliyuncs.com
dashscope-result-gz.oss-cn-guangzhou.aliyuncs.com
dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com

Alibaba Cloud Model Studio:Wan text-to-video API reference

Model overview

Prerequisites

HTTP

Create task

Request parameters

Text-to-video

Headers

Request body

Response parameters

Successful response

Error response

Query results by task ID

Request parameters

Query task results

Headers

Path parameters

Response parameters

Task succeeded

Task failed

Dashscope SDK

Python

Synchronous

Sample request

Sample response

Asynchronous

Sample request

Sample response

Java

Synchronous

Sample request

Sample response

Asynchronous

Sample request

Sample response

Error code

FAQ

Does the plus model support outputting 480p videos?

Billing and throttling

Configure domain whitelist to access video URL from OSS