The Wan text-to-video model generates smooth videos from text prompts .
References: User guide
To ensure successful calls, the model, Endpoint URL, and API Key must all belong to the same region. Cross-region calls will fail.
Because text-to-video tasks take a long time (typically 1 to 5 minutes), the API uses asynchronous invocation. The entire process involves two core steps: Create a task -> Poll for the result. The process is as follows:
The parameter names in the SDK are mostly consistent with the HTTP API, and the parameter structure is encapsulated to align with the features of the programming language.
Because text-to-video tasks can take a long time to complete (typically 1 to 5 minutes), the SDK encapsulates the HTTP asynchronous call process and supports both synchronous and asynchronous invocation methods.
Set
Set
If the model call fails and returns an error message, see Error codes for resolution.
A: You cannot convert the link directly. The correct procedure is to have your backend service retrieve the URL, download the video file, and then upload it to a permanent object storage service, such as Alibaba Cloud Object Storage Service (OSS), to generate a new, permanent access link.
A: No. You should not play the link directly in a browser because it expires after 24 hours. Instead, you should download and store the video, and then use a permanent link for playback.
Availability
To ensure successful calls, the model, Endpoint URL, and API Key must all belong to the same region. Cross-region calls will fail.
- Select a model: Confirm the region of the model.
- Select a URL: Choose the corresponding regional Endpoint URL. HTTP URLs and DashScope SDK URLs are supported.
- Configure an API key: Select a region, get an API key, and then configure the API key as an environment variable (to be deprecated and merged into API key configuration).
- Install the SDK: To make calls using the SDK, you must install the DashScope SDK.
The sample code in this topic applies to the Singapore region.
HTTP
Because text-to-video tasks take a long time (typically 1 to 5 minutes), the API uses asynchronous invocation. The entire process involves two core steps: Create a task -> Poll for the result. The process is as follows:
Step 1: Create a task and get the task ID
- Singapore
- Virginia
- Frankfurt
- Beijing
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesisReplace {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 headersContent-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 bodymodelstring (Required)The name of the model to use. For a list of available models, see the model list.Example: wan2.6-t2v.input object (Required)Contains basic input information, such as the prompt.
Properties prompt string (Required)The text prompt. It describes the desired elements and visual characteristics of the generated video.The prompt can be in Chinese or English. The length is measured in characters, where each Chinese character or letter is counted as one character. Text that exceeds the character limit is automatically truncated. The length limit varies by model version:
string (Optional)A prompt that describes the content to exclude from the video. This helps refine the generated content.The prompt can be in Chinese or English. The maximum length is 500 characters. Text that exceeds this limit is automatically truncated.Example: low resolution, error, worst quality, low quality, deformed, extra fingers, bad proportions.audio_url string (Optional)Supported models: wan2.6 and wan2.5 series models.The URL of the audio file. The model will use this audio to generate the video.Supported input formats:
object (Optional)Video processing parameters, such as setting the video resolution, enabling prompt rewriting, and adding a watermark.
Properties size string (Optional)Specifies the resolution of the generated video in width*height format. The default value and valid values for this parameter depend on the model parameter, as described below:
integer (Optional)The duration of the generated video in seconds. The valid values for this parameter depend on the model parameter:
boolean (Optional)Specifies whether to enable prompt rewriting. When enabled, a model intelligently rewrites the input prompt. This significantly improves the quality of the generated video for shorter prompts but increases the running time.
string (Optional)Supported models: wan2.6 models.Specifies the shot type of the generated video, that is, whether the video consists of a single continuous shot or multiple changing shots.Valid values:
"prompt_extend": true is set.Parameter priority: shot_type > prompt. For example, if shot_type is set to "single", the model outputs a single-shot video even if the prompt contains "generate a multi-shot video".watermark boolean (Optional)Specifies whether to add a watermark. The watermark is placed in the lower-right corner of the video with the fixed text "AI Generated".
integer (Optional)The random number seed must be an integer in the range [0, 2147483647].If not specified, a random seed is generated. A fixed seed improves reproducibility.Because model generation is probabilistic, the same seed does not guarantee identical results. |
|
Response parametersoutputobjectContains the task 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 the result by task ID
- Singapore
- Virginia
- Frankfurt
- Beijing
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}Replace {WorkspaceId} with your actual workspace 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 headersAuthorizationstring (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.URL path parameterstask_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 parametersoutputobjectContains the task output information.
Properties task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.
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.video_url stringURL of the generated video. Returned only when task_status is SUCCEEDED.Valid for 24 hours. The video is in MP4 format with H.264 encoding.orig_prompt stringThe original input prompt, corresponding to the request parameter prompt.actual_prompt stringWhen prompt_extend=true, the system rewrites the input prompt. This field returns the optimized prompt used for generation.
stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.objectContains statistics about the output. This information is provided only for successful tasks.
Properties video_duration integerReturned only when using wan2.5 and earlier models. Used for billing.The duration of the generated video in seconds. Valid values are 5 and 10.duration floatReturned only when using the wan2.6 model. Used for billing.Indicates the total video duration, where duration = input_video_duration + output_video_duration.input_video_duration integerReturned only when using the wan2.6 model. Fixed at 0.output_video_duration integerReturned only when using the wan2.6 model.The duration of the output video in seconds. Its value is the same as the value of input.duration.SR integerReturned only when using the wan2.6 model. The resolution tier of the generated video. Example: 720.size stringReturned only when using the wan2.6 model. The resolution of the generated video. The format is "widthheight". Example: 19201080.video_ratio stringReturned only when using wan2.5 and earlier models. The resolution of the generated video. The format is "widthheight". Example: 832480.video_count integerThe number of generated videos. Fixed at 1.stringUnique request identifier for tracing and troubleshooting. |
Video URLs are valid for only 24 hours and then automatically purged. Save generated videos promptly. |
DashScope SDK
The parameter names in the SDK are mostly consistent with the HTTP API, and the parameter structure is encapsulated to align with the features of the programming language.
Because text-to-video tasks can take a long time to complete (typically 1 to 5 minutes), the SDK encapsulates the HTTP asynchronous call process and supports both synchronous and asynchronous invocation methods.
The actual processing time depends on the number of tasks in the queue and the service status. Wait for the result.
Python
Set dashscope.base_http_api_url based on the region where the model is located:
- Singapore
- Virginia
- Beijing
- Frankfurt
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'Replace {WorkspaceId} with your actual workspace ID.- Synchronous invocation
- Asynchronous invocation
Request example
Response example
The video_url is valid for 24 hours. Download promptly.
Java
Set Constants.baseHttpApiUrl based on the region where the model is located:
- Singapore
- Virginia
- Beijing
- Frankfurt
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";Replace {WorkspaceId} with your actual workspace ID.- Synchronous invocation
- Asynchronous invocation
Request example
Response example
The video_url is valid for 24 hours. Download promptly.
Error codes
If the model call fails and returns an error message, see Error codes for resolution.
FAQ
Q: How do I convert a temporary video link to a permanent one?
A: You cannot convert the link directly. The correct procedure is to have your backend service retrieve the URL, download the video file, and then upload it to a permanent object storage service, such as Alibaba Cloud Object Storage Service (OSS), to generate a new, permanent access link.
Example code: Download a video to a local device
Example code: Download a video to a local device