All Products
Search

This Product

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

    Document Center

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

    Last Updated:Jan 26, 2026

    Wan text-to-video generates a smooth video from text prompts:

    • Basic features: Supports video durations in integer seconds (2–15 seconds), specified video resolutions (480P, 720P, or 1080P), prompt rewriting, and adding watermarks.

    • Audio features: Supports automatic dubbing or using a custom audio file for audio-visual sync. (wan2.5 and wan2.6)

    • Multi-shot narrative: Generates videos with multiple shots while maintaining subject consistency across shot changes. (wan2.6 only)

    Quick start: Try it online (Singapore｜Virginia｜Beijing)｜ Wan official website

    Note

    The features on the Wan official website may differ from those supported by the API. This document describes the API's capabilities and is updated promptly to reflect any changes.

    Model overview

    Input prompt

    Output video (wan2.6, multi-shot video)

    Shot from a low angle, in a medium close-up, with warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, and a central composition. In a classic detective office, wooden bookshelves are filled with old case files and ashtrays. A green desk lamp illuminates a case file spread out in the center of the desk. A fox, wearing a dark brown trench coat and a light gray fedora, sits in a leather chair, its fur crimson, its tail resting lightly on the edge, its fingers slowly turning yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. It slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera, its mouth clearly moving as it speaks in a smooth, cynical voice: 'The case was cold, colder than a fish in winter. But every chicken has its secrets, and I, for one, intended to find them '.

    Prerequisites

    Before making a call, obtain an API key and set the API key as an environment variable. To make calls using the SDK, install the DashScope SDK.

    Important

    The Beijing and Singapore regions have separate API keys and request endpoints. Do not use them interchangeably. Cross-region calls result in authentication failures or service errors.

    HTTP

    Because text-to-video tasks are time-consuming, typically taking 1 to 5 minutes, the API uses asynchronous invocation. The process involves two core steps: Create task -> Poll for result.

    The actual time required depends on the number of tasks in the queue and the service's execution status.

    Step 1: Create a task to get the task ID

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

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

    Beijing: POST https://dashscope.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 a beginner's tutorial, see Postman.

    Request parameters

    Multi-shot narrative

    Only the wan2.6-t2v model supports generating multi-shot videos.

    Enable this feature by setting "prompt_extend": true and "shot_type":"multi".

    # Note: If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
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.6-t2v",
    "input": {
        "prompt": "Shot from a low angle, in a medium close-up, with warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, and a central composition. In a classic detective office, wooden bookshelves are filled with old case files and ashtrays. A green desk lamp illuminates a case file spread out in the center of the desk. A fox, wearing a dark brown trench coat and a light gray fedora, sits in a leather chair, its fur crimson, its tail resting lightly on the edge, its fingers slowly turning yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. It slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera, its mouth clearly moving as it speaks in a smooth, cynical voice: \"The case was cold, colder than a fish in winter. But every chicken has its secrets, and I, for one, intended to find them \"。",
        "audio_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250929/stjqnq/%E7%8B%90%E7%8B%B8.mp3"
    },
    "parameters": {
        "size": "1280*720",
        "prompt_extend": true,
        "duration": 10,
        "shot_type":"multi"
    }
}'

    Automatic dubbing

    This feature is supported only by wan2.5 and later models.

    If you do not provide input.audio_url, the model automatically generates matching background music or sound effects based on the video content.

    # Note: If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
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.5-t2v-preview",
    "input": {
        "prompt": "Shot from a low angle, in a medium close-up, with warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, and a central composition. In a classic detective office, wooden bookshelves are filled with old case files and ashtrays. A green desk lamp illuminates a case file spread out in the center of the desk. A fox, wearing a dark brown trench coat and a light gray fedora, sits in a leather chair, its fur crimson, its tail resting lightly on the edge, its fingers slowly turning yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. It slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera, its mouth clearly moving as it speaks in a smooth, cynical voice: \"The case was cold, colder than a fish in winter. But every chicken has its secrets, and I, for one, intended to find them \""
    },
    "parameters": {
        "size": "832*480",
        "prompt_extend": true,
        "duration": 10
    }
}'

    Provide an audio file

    This feature is supported only by wan2.5 and later models.

    To specify background music or a voiceover for the video, provide the URL of a custom audio file using the input.audio_url parameter.

    # Note: If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
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.5-t2v-preview",
    "input": {
        "prompt": "Shot from a low angle, in a medium close-up, with warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, and a central composition. In a classic detective office, wooden bookshelves are filled with old case files and ashtrays. A green desk lamp illuminates a case file spread out in the center of the desk. A fox, wearing a dark brown trench coat and a light gray fedora, sits in a leather chair, its fur crimson, its tail resting lightly on the edge, its fingers slowly turning yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. It slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera, its mouth clearly moving as it speaks in a smooth, cynical voice: \"The case was cold, colder than a fish in winter. But every chicken has its secrets, and I, for one, intended to find them \"。",
        "audio_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250929/stjqnq/%E7%8B%90%E7%8B%B8.mp3"
    },
    "parameters": {
        "size": "832*480",
        "prompt_extend": true,
        "duration": 10
    }
}'

    Generate a silent video

    wan2.2 and earlier models generate silent videos by default. No parameters need to be set.

    wan2.5 and later models generate videos with audio by default.
    # Note: If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
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.2-t2v-plus",
    "input": {
        "prompt": "Low contrast, in a retro 70s style subway station, a street musician plays amidst dim colors and rough textures. He wears an old-style jacket, holds a guitar, and plays with concentration. Commuters hurry past, and a small crowd gradually gathers to listen. The camera slowly pans to the right, capturing the scene where the sound of the instrument intertwines with the city's hustle and bustle, with old-fashioned subway signs and mottled walls in the background."
    },
    "parameters": {
        "size": "832*480",
        "prompt_extend": true
    }
}'

    Use a negative prompt

    Use `negative_prompt` to exclude the "flower" element and prevent it from appearing in the video.

    # Note: If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
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.2-t2v-plus",
    "input": {
        "prompt": "A kitten running in the moonlight",
        "negative_prompt": "flower"
    },
    "parameters": {
        "size": "832*480"
    }
}'
    Headers

    Content-Type string (Required)

    The content type of the request. Must be application/json.

    Authorization string (Required)

    The authentication credentials using a Model Studio API key.

    Example: Bearer sk-xxxx

    X-DashScope-Async string (Required)

    Enables asynchronous processing. Must be enable as HTTP requests support only asynchronous processing.

    Important

    Returns "current user api does not support synchronous calls" error if not included.

    Request body

    model string (Required)

    The model name. For a list of models and their prices, see Model pricing.

    Example: wan2.6-t2v.

    input object (Required)

    Basic input information, such as the prompt.

    Properties

    prompt string (Required)

    The text prompt. Describes the desired elements and visual characteristics of the generated video.

    Supports both Chinese and English. Each Chinese character or letter counts as one character. Any text exceeding the limit is automatically truncated. The length limit varies by model version:

    • wan2.6-t2v: Up to 1,500 characters.

    • wan2.5-t2v-preview: Up to 1,500 characters.

    • wan2.2 and earlier models: Up to 800 characters.

    Example: A kitten running in the moonlight.

    For tips, see Text-to-video/image-to-video prompt guide.

    negative_prompt string (Optional)

    The negative prompt. Describes content that you do not want to see in the video, which lets you constrain the video output.

    Supports both Chinese and English. The length is limited to 500 characters. Any text exceeding the 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-t2v, wan2.5-t2v-preview.

    The URL of the audio file. The model uses this audio to generate the video. For usage instructions, see Set audio parameters.

    Supports the HTTP or HTTPS protocol.

    Audio limits:

    • Format: WAV, MP3.

    • Duration: 3–30s.

    • File size: Up to 15 MB.

    • Handling of limits: If the audio duration exceeds the duration value (for example, 5 seconds), the first 5 seconds are used and the rest is discarded. If the audio is shorter than the video duration, the remaining part of the video will be silent. For example, if the audio is 3 seconds long and the video duration is 5 seconds, the first 3 seconds of the output video will have sound, and the last 2 seconds will be silent.

    Example: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.mp3.

    parameters object (Optional)

    Image editing parameters. Use these to set the video resolution, enable prompt rewriting, add watermarks, and more.

    Properties

    size string (Optional)

    Important

    • The `size` parameter directly affects the cost. Cost = Unit price (based on resolution) × Duration (seconds). For the same model, 1080P > 720P > 480P. Before making a call, confirm the model pricing.

    • The `size` must be set to specific values (such as 1280*720), not ratios like 1:1 or tiers like 480P.

    Specifies the resolution of the generated video in the format width*height. The default value and available enumeration values for this parameter depend on the `model` parameter, as follows:

    • wan2.6-t2v: The default value is 1920*1080 (1080P). Optional resolutions: All resolutions corresponding to 720P and 1080P.

    • wan2.5-t2v-preview: The default value is 1920*1080 (1080P). Optional resolutions: All resolutions corresponding to 480P, 720P, and 1080P.

    • wan2.2-t2v-plus: The default value is 1920*1080 (1080P). Optional resolutions: All resolutions corresponding to 480P and 1080P.

    • wan2.1-t2v-turbo : The default value is 1280*720 (720P). Optional resolutions: All resolutions corresponding to 480P and 720P.

    • wan2.1-t2v-plus: The default value is 1280*720 (720P). Optional resolutions: All resolutions corresponding to 720P.

    480P tier: The optional video resolutions and their corresponding aspect ratios are:

    • 832*480: 16:9.

    • 480*832: 9:16.

    • 624*624: 1:1.

    720P tier: The optional video resolutions and their corresponding aspect ratios are:

    • 1280*720: 16:9.

    • 720*1280: 9:16.

    • 960*960: 1:1.

    • 1088*832: 4:3.

    • 832*1088: 3:4.

    1080P tier: The optional video resolutions and their corresponding aspect ratios are:

    • 1920*1080: 16:9.

    • 1080*1920: 9:16.

    • 1440*1440: 1:1.

    • 1632*1248: 4:3.

    • 1248*1632: 3:4.

    duration integer (Optional)

    Important

    The `duration` parameter directly affects the cost. Cost = Unit price (based on resolution) × Duration (seconds). Before making a call, confirm the model pricing.

    The duration of the generated video, in seconds. The value of this parameter depends on the `model` parameter:

    • wan2.6-t2v: An integer from 2 to 15. The default value is 5.

    • wan2.5-t2v-preview: Optional values are 5 and 10. The default value is 5.

    • wan2.2-t2v-plus: Fixed at 5 seconds and cannot be modified.

    • wan2.1-t2v-plus: Fixed at 5 seconds and cannot be modified.

    • wan2.1-t2v-turbo: Fixed at 5 seconds and cannot be modified.

    Example: 5.

    prompt_extend boolean (Optional) Defaults to true

    Whether to enable prompt rewriting. When enabled, an LLM rewrites the input prompt. This can significantly improve generation quality for shorter prompts but also increases processing time.

    • true

    • false

    Example: true

    shot_type string (Optional)

    Supported model: wan2.6-t2v.

    Specifies the shot type of the generated video, which determines whether the video consists of a single continuous shot or multiple changing shots.

    Condition for effect: This parameter takes effect only when "prompt_extend": true.

    Parameter priority: shot_type > prompt. For example, if `shot_type` is set to "single", the model will still output a single-shot video even if the prompt includes "generate a multi-shot video".

    Optional values:

    • single (default): Outputs a single-shot video.

    • multi: Outputs a multi-shot video.

    Example: single.

    Note

    Use this parameter when you need to strictly control the narrative structure of the video, such as using a single shot for a product display or multiple shots for a short story.

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

    • false (default): No watermark is added.

    • true: A watermark is added.

    Example: false.

    seed integer (Optional)

    The random number seed. Must be an integer between 0 and 2147483647.

    If not provided, a random seed is generated. Using a fixed seed improves reproducibility, though results may still vary due to model randomness.

    Example: 12345

    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 to resolve the issue.

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

    output object

    Task output information.

    Properties

    task_id string

    The ID of the task. Can be used to query the task for up to 24 hours.

    task_status string

    The status of the task.

    Enumeration

    • PENDING

    • RUNNING

    • SUCCEEDED

    • FAILED

    • CANCELED

    • UNKNOWN: Task does not exist or status is unknown

    request_id string

    Unique identifier for the request. Use for tracing and troubleshooting issues.

    code string

    The error code. Returned only when the request fails. See error codes for details.

    message string

    Detailed error message. Returned only when the request fails. See error codes for details.

    Step 2: Query the result by task ID

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

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

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

    Note

    • Polling suggestion: Video generation can take several minutes. We recommend that you use a polling mechanism with a reasonable query interval, such as 15 seconds, to retrieve the result.

    • Task status transition: PENDING → RUNNING → SUCCEEDED or FAILED.

    • Result URL: After the task is successful, a video URL is returned. The URL is valid for 24 hours. After you retrieve the URL, you must immediately download and save the video to a permanent storage service, such as Object Storage Service (OSS).

    • task_id validity: 24 hours. After this period, you cannot query the result, and the API returns a task status of UNKNOWN.

    Request parameters

    Query task result

    Replace 86ecf553-d340-4e21-xxxxxxxxx with the actual task ID.

    API keys are region-specific. See API key documentation for details.
    For models in the Beijing region, replace base_url with https://dashscope.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx
    curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

    Headers

    Authorization string (Required)

    The authentication credentials using a Model Studio API key.

    Example: Bearer sk-xxxx

    Path parameters

    task_id string (Required)

    The ID of the task to query.

    Response parameters

    Task executed successfully

    Video URLs are retained for only 24 hours and then automatically purged. Save generated videos promptly.

    {
    "request_id": "abbf7aa3-9652-4785-a622-xxxxxx",
    "output": {
        "task_id": "38513c71-5190-48e1-9f3b-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-09-29 14:05:22.119",
        "scheduled_time": "2025-09-29 14:05:28.278",
        "end_time": "2025-09-29 14:10:00.437",
        "orig_prompt": "Shot from a low angle, in a medium close-up, with warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, and a central composition. In a classic detective's office, wooden bookshelves are filled with old case files and ashtrays. A green desk lamp illuminates a case file spread out in the center of the desk. A fox, wearing a dark brown trench coat and a light gray fedora, sits in a leather chair, its fur crimson, its tail resting lightly on the edge, its fingers slowly turning yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. It slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera, its mouth clearly moving as it speaks in a smooth, cynical voice: 'The case was cold, colder than a fish in winter. But every chicken has its secrets, and I, for one, intended to find them '。",
        "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx"
    },
    "usage": {
        "duration": 10,
        "size": "1280*720",
        "input_video_duration": 0,
        "output_video_duration": 10,
        "video_count": 1,
        "SR": 720
    }
}

    Task execution failed

    When a task fails, task_status is set to FAILED with an error code and message. See error codes to resolve the issue.

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

    Task query expired

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

    {
    "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 to query.

    task_status string

    The task status.

    Enumeration

    • PENDING

    • RUNNING

    • SUCCEEDED

    • FAILED

    • CANCELED

    • UNKNOWN: Task does not exist or status is unknown

    submit_time string

    The time when the task was submitted. Time is in UTC+8. Format: YYYY-MM-DD HH:mm:ss.SSS.

    scheduled_time string

    The time when the task started running. Time is in UTC+8. Format: YYYY-MM-DD HH:mm:ss.SSS.

    end_time string

    The time when the task was completed. Time is in UTC+8. Format: YYYY-MM-DD HH:mm:ss.SSS.

    video_url string

    The URL of the generated video. Returned only when task_status is SUCCEEDED.

    URL is valid for 24 hours. Use to download the video in MP4 format with H.264 encoding.

    orig_prompt string

    The original input prompt. This is the value of the prompt request parameter.

    actual_prompt string

    When prompt_extend=true, the system performs prompt rewriting on the input prompt. This field returns the optimized prompt that was actually used for generation.

    • If prompt_extend=false, this field is not returned.

    • Note: The wan2.6 model does not return this field, regardless of the value of prompt_extend.

    code string

    The error code. Returned only when the request fails. See error codes for details.

    message string

    Detailed error message. Returned only when the request fails. See error codes for details.

    usage object

    Statistics for the output. Only successful results are counted.

    Properties

    video_duration integer

    Returned only when using wan2.5 or earlier models. Used for billing.

    The duration of the generated video, in seconds. Enumeration values are 5 and 10.

    duration float

    Returned 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 integer

    Returned only when using the wan2.6 model. The value is fixed at 0.

    output_video_duration integer

    Returned 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 integer

    Returned only when using the wan2.6 model. The resolution tier of the generated video. Example: 720.

    size string

    Returned only when using the wan2.6 model. The resolution of the generated video. The format is "width*height". Example: 1920*1080.

    video_ratio string

    Returned only when using wan2.5 or earlier models. The resolution of the generated video. The format is "width*height". Example: 832*480.

    video_count integer

    The number of generated videos. The value is fixed at 1.

    request_id string

    Unique identifier for the request. Use for tracing and troubleshooting issues.

    DashScope SDK

    The parameter naming in the SDK is mostly consistent with the HTTP API. The parameter structure is adapted for each programming language.

    Because text-to-video tasks are time-consuming, typically taking 1 to 5 minutes, the SDK encapsulates the HTTP asynchronous invocation process and supports both synchronous and asynchronous invocation methods.

    The actual time required depends on the number of tasks in the queue and the service's execution status.

    Python SDK

    Important

    Make sure that your DashScope Python SDK version is at least 1.25.8 before you run the following code.

    If you use an older version, you may encounter errors such as "url error, please check url!". To update the SDK, see Install the SDK.

    Synchronous invocation

    Request example
    from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
import os

# If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# If you have not configured environment variables, replace the following line with your Model Studio API key: api_key="sk-xxx"
# The API keys for the Singapore and Beijing regions are different. To get an API key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")

def sample_sync_call_t2v():
    # Call the sync API. The result is returned.
    print('Please wait...')
    rsp = VideoSynthesis.call(api_key=api_key,
                              model='wan2.6-t2v',
                              prompt="Shot from a low angle, in a medium close-up, with warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, and a central composition. In a classic detective office, wooden bookshelves are filled with old case files and ashtrays. A green desk lamp illuminates a case file spread out in the center of the desk. A fox, wearing a dark brown trench coat and a light gray fedora, sits in a leather chair, its fur crimson, its tail resting lightly on the edge, its fingers slowly turning yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. It slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera, its mouth clearly moving as it speaks in a smooth, cynical voice: 'The case was cold, colder than a fish in winter. But every chicken has its secrets, and I, for one, intended to find them '.",
                              audio_url='https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250929/stjqnq/%E7%8B%90%E7%8B%B8.mp3',
                              size='1280*720',
                              duration=10,
                              negative_prompt="",
                              prompt_extend=True,
                              watermark=False,
                              seed=12345)
    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()
    Response example
    The video_url is valid for 24 hours. Be sure to download the video within this period.
    {
    "status_code": 200,
    "request_id": "167f3beb-3dd0-47fe-a83c-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "5b65411f-d946-4e29-859e-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-result-bj.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
        "submit_time": "2025-10-23 11:47:23.879",
        "scheduled_time": "2025-10-23 11:47:34.351",
        "end_time": "2025-10-23 11:52:35.323",
        "orig_prompt": "Shot from a low angle, in a medium close-up, with warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, and a central composition. In a classic detective's office, wooden bookshelves are filled with old case files and ashtrays. A green desk lamp illuminates a case file spread out in the center of the desk. A fox, wearing a dark brown trench coat and a light gray fedora, sits in a leather chair, its fur crimson, its tail resting lightly on the edge, its fingers slowly turning yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. It slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera, its mouth clearly moving as it speaks in a smooth, cynical voice: 'The case was cold, colder than a fish in winter. But every chicken has its secrets, and I, for one, intended to find them '。"
    },
    "usage": {
        "video_count": 1,
        "video_duration": 0,
        "video_ratio": "",
        "duration": 10,
        "size": "1280*720",
        "input_video_duration": 0,
        "output_video_duration": 10,
        "SR": 720
    }
}

    Asynchronous invocation

    Request example
    from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
import os

# If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# If you have not configured environment variables, replace the following line with your Model Studio API key: api_key="sk-xxx"
# The API keys for the Singapore and Beijing regions are different. To get an API key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")

def sample_async_call_t2v():
    # Call the async API. The task information is returned.
    # You can get the task status with the returned task ID.
    rsp = VideoSynthesis.async_call(api_key=api_key,
                                    model='wan2.6-t2v',
                                    prompt="Shot from a low angle, in a medium close-up, with warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, and a central composition. In a classic detective office, wooden bookshelves are filled with old case files and ashtrays. A green desk lamp illuminates a case file spread out in the center of the desk. A fox, wearing a dark brown trench coat and a light gray fedora, sits in a leather chair, its fur crimson, its tail resting lightly on the edge, its fingers slowly turning yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. It slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera, its mouth clearly moving as it speaks in a smooth, cynical voice: 'The case was cold, colder than a fish in winter. But every chicken has its secrets, and I, for one, intended to find them '.",
                                    audio_url='https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250929/stjqnq/%E7%8B%90%E7%8B%B8.mp3',
                                    size='1280*720',
                                    duration=10,
                                    negative_prompt="",
                                    prompt_extend=True,
                                    watermark=False,
                                    seed=12345)
    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, including the task status.
    status = VideoSynthesis.fetch(task=rsp, api_key=api_key)
    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 for the task to complete. This calls fetch at intervals and checks if the task is in a finished state.
    rsp = VideoSynthesis.wait(task=rsp, api_key=api_key)
    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()
    Response example

    1. Example of a response to a task creation request

    {
	"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. Example of a response to a task query request

    The video_url is valid for 24 hours. Be sure to download the video within this period.
    {
    "status_code": 200,
    "request_id": "167f3beb-3dd0-47fe-a83c-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "5b65411f-d946-4e29-859e-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-result-bj.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
        "submit_time": "2025-10-23 11:47:23.879",
        "scheduled_time": "2025-10-23 11:47:34.351",
        "end_time": "2025-10-23 11:52:35.323",
        "orig_prompt": "Shot from a low angle, in a medium close-up, with warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, and a central composition. In a classic detective's office, wooden bookshelves are filled with old case files and ashtrays. A green desk lamp illuminates a case file spread out in the center of the desk. A fox, wearing a dark brown trench coat and a light gray fedora, sits in a leather chair, its fur crimson, its tail resting lightly on the edge, its fingers slowly turning yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. It slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera, its mouth clearly moving as it speaks in a smooth, cynical voice: 'The case was cold, colder than a fish in winter. But every chicken has its secrets, and I, for one, intended to find them '。"
    },
    "usage": {
        "video_count": 1,
        "video_duration": 0,
        "video_ratio": "",
        "duration": 10,
        "size": "1280*720",
        "input_video_duration": 0,
        "output_video_duration": 10,
        "SR": 720
    }
}

    Java SDK

    Important

    Ensure that your DashScope Java SDK version is 2.22.6 or later, and then run the following code.

    If you use an older version, you may encounter errors such as "url error, please check url!". To update the SDK, see Install the SDK.

    Synchronous call

    Request example
    // 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;

import java.util.HashMap;
import java.util.Map;

public class Text2Video {
    /**
     * Create a video synthesis task and wait for the task to complete.
     */
    static {
     Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
     // If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
    }
    
    // If you have not configured environment variables, replace the following line with your Model Studio API key: apiKey="sk-xxx"
    // The API keys for the Singapore and Beijing regions are different. To get an API key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");


    public static void text2Video() throws ApiException, NoApiKeyException, InputRequiredException {
        VideoSynthesis vs = new VideoSynthesis();
        Map<String, Object> parameters = new HashMap<>();
        parameters.put("prompt_extend", true);
        parameters.put("watermark", false);
        parameters.put("seed", 12345);

        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.6-t2v")
                        .prompt("Shot from a low angle, in a medium close-up, with warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, and a central composition. In a classic detective office, wooden bookshelves are filled with old case files and ashtrays. A green desk lamp illuminates a case file spread out in the center of the desk. A fox, wearing a dark brown trench coat and a light gray fedora, sits in a leather chair, its fur crimson, its tail resting lightly on the edge, its fingers slowly turning yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. It slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera, its mouth clearly moving as it speaks in a smooth, cynical voice: 'The case was cold, colder than a fish in winter. But every chicken has its secrets, and I, for one, intended to find them '.")
                        .audioUrl("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250929/stjqnq/%E7%8B%90%E7%8B%B8.mp3")
                        .negativePrompt("")
                        .size("1280*720")
                        .duration(10)
                        .parameters(parameters)
                        .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);
    }
}
    Response example
    The video_url is valid for 24 hours. Be sure to download the video within this period.
    {
    "request_id": "c1209113-8437-424f-a386-xxxxxx",
    "output": {
        "task_id": "966cebcd-dedc-4962-af88-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
        "orig_prompt": "Shot from a low angle, in a medium close-up, with warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, and a central composition. In a classic detective office, wooden bookshelves are filled with old case files and ashtrays. A green desk lamp illuminates a case file spread out in the center of the desk. A fox, wearing a dark brown trench coat and a light gray fedora, sits in a leather chair, its fur crimson, its tail resting lightly on the edge, its fingers slowly turning yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. It slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera, its mouth clearly moving as it speaks in a smooth, cynical voice: 'The case was cold, colder than a fish in winter. But every chicken has its secrets, and I, for one, intended to find them '",
        "submit_time": "2026-01-22 23:13:40.553",
        "scheduled_time": "2026-01-22 23:13:49.415",
        "end_time": "2026-01-22 23:17:56.380"
    },
    "usage": {
        "video_count": 1,
        "duration": 10.0,
        "size": "1280*720",
        "input_video_duration": 0.0,
        "output_video_duration": 10.0,
        "SR": "720"
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

    Asynchronous invocation

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

import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesis;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisListResult;
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.task.AsyncTaskListParam;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;

import java.util.HashMap;
import java.util.Map;

public class Text2Video {
    /**
     * Create a video synthesis task and wait for the task to complete.
     */
    static {
        // If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
        Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
    }

     // If you have not configured environment variables, replace the following line with your Model Studio API key: apiKey="sk-xxx"
    // The API keys for the Singapore and Beijing regions are different. To get an API key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void text2Video() throws ApiException, NoApiKeyException, InputRequiredException {
        VideoSynthesis vs = new VideoSynthesis();
        Map<String, Object> parameters = new HashMap<>();
        parameters.put("prompt_extend", true);
        parameters.put("watermark", false);
        parameters.put("seed", 12345);

        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.6-t2v")
                        .prompt("Shot from a low angle, in a medium close-up, with warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, and a central composition. In a classic detective office, wooden bookshelves are filled with old case files and ashtrays. A green desk lamp illuminates a case file spread out in the center of the desk. A fox, wearing a dark brown trench coat and a light gray fedora, sits in a leather chair, its fur crimson, its tail resting lightly on the edge, its fingers slowly turning yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. It slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera, its mouth clearly moving as it speaks in a smooth, cynical voice: 'The case was cold, colder than a fish in winter. But every chicken has its secrets, and I, for one, intended to find them '.")
                        .audioUrl("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250929/stjqnq/%E7%8B%90%E7%8B%B8.mp3")
                        .negativePrompt("")
                        .size("1280*720")
                        .duration(10)
                        .parameters(parameters)
                        .build();

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

        // Get the result
        VideoSynthesisResult result = vs.wait(task, apiKey);
        System.out.println(JsonUtils.toJson(result));
    }

     // Get the task list
    public static void listTask() throws ApiException, NoApiKeyException {
        VideoSynthesis is = new VideoSynthesis();
        AsyncTaskListParam param = AsyncTaskListParam.builder().build();
        param.setApiKey(apiKey);
        VideoSynthesisListResult result = is.list(param);
        System.out.println(result);
    }

    // Get the result of a single task
    public static void fetchTask(String taskId) throws ApiException, NoApiKeyException {
        VideoSynthesis is = new VideoSynthesis();
        // If DASHSCOPE_API_KEY is set as an environment variable, apiKey can be null.
        VideoSynthesisResult result = is.fetch(taskId, apiKey);
        System.out.println(result.getOutput());
        System.out.println(result.getUsage());
    }

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

    1. Example of a response to a task creation request.

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

    2. Example of a response to a task query request

    The video_url is valid for 24 hours. Be sure to download the video within this period.
    {
    "request_id": "c1209113-8437-424f-a386-xxxxxx",
    "output": {
        "task_id": "966cebcd-dedc-4962-af88-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
        "orig_prompt": "Shot from a low angle, in a medium close-up, with warm tones, mixed lighting (the practical light from the desk lamp blends with the overcast light from the window), side lighting, and a central composition. In a classic detective office, wooden bookshelves are filled with old case files and ashtrays. A green desk lamp illuminates a case file spread out in the center of the desk. A fox, wearing a dark brown trench coat and a light gray fedora, sits in a leather chair, its fur crimson, its tail resting lightly on the edge, its fingers slowly turning yellowed pages. Outside, a steady drizzle falls beneath a blue sky, streaking the glass with meandering streaks. It slowly raises its head, its ears twitching slightly, its amber eyes gazing directly at the camera, its mouth clearly moving as it speaks in a smooth, cynical voice: 'The case was cold, colder than a fish in winter. But every chicken has its secrets, and I, for one, intended to find them '",
        "submit_time": "2026-01-22 23:13:40.553",
        "scheduled_time": "2026-01-22 23:13:49.415",
        "end_time": "2026-01-22 23:17:56.380"
    },
    "usage": {
        "video_count": 1,
        "duration": 10.0,
        "size": "1280*720",
        "input_video_duration": 0.0,
        "output_video_duration": 10.0,
        "SR": "720"
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

    Limitations

    • Data validity: The task ID and video URL are valid for 24 hours. After they expire, you can no longer query task details or download the video.

    • Audio support: wan2.5 and later models generate videos with audio by default (supporting automatic dubbing or custom audio files). wan2.2 and earlier models only support generating silent videos. If needed, you can use speech synthesis to generate audio.

    • Content moderation: Both the input content and the output video are subject to content moderation. Requests containing prohibited content will result in an "IPInfringementSuspect" or "DataInspectionFailed" error. For more information, see Error messages.

    • Network access configuration: Video links are stored in Object Storage Service (OSS). If your business system cannot access external OSS links due to security policies, add the following OSS domain names to your network access whitelist.

      # OSS domain name 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

    Key parameter descriptions

    Set audio parameters

    Supported models: wan2.6-t2v, wan2.5-t2v-preview.

    Audio settings: wan2.5 and later models generate videos with audio by default. The audio behavior is determined by whether you provide the input.audio_url parameter. The following two modes are supported:

    1. Automatic dubbing: When audio_url is not provided, the model automatically generates matching background audio or music based on the prompt and video content.

    2. Use custom audio: When audio_url is provided, the model uses your audio file to generate the video. The model generates video content, such as lip movements and rhythm, that aligns with the audio.

    Billing and rate limiting

    • For the free quota and unit prices, see Model list and pricing.

    • For rate limits, see Wan series.

    • Billing description:

      • Billing is based on the duration in seconds of successfully generated videos. You are charged only when the task query API returns a task_status of SUCCEEDED and a video is successfully generated.

      • Failed model calls or processing errors do not incur any fees and do not consume the free quota for new users.

    Error codes

    If a call fails, see Error messages for troubleshooting.

    FAQ

    Q: How do I convert a temporary video link to a permanent one?

    A: You cannot directly convert the link. The correct method is for your backend service to retrieve the URL, download the video file programmatically, and then upload it to a permanent object storage service, such as Alibaba Cloud OSS, to generate a new, permanent access link.

    Example code: Download a video to a local device

    import requests

def download_and_save_video(video_url, save_path):
    try:
        response = requests.get(video_url, stream=True, timeout=300) # Set a timeout
        response.raise_for_status() # If the HTTP status code is not 200, raise an exception
        with open(save_path, 'wb') as f:
            for chunk in response.iter_content(chunk_size=8192):
                f.write(chunk)
        print(f"Video successfully downloaded to: {save_path}")
        # You can add the logic to upload to permanent storage here
    except requests.exceptions.RequestException as e:
        print(f"Failed to download video: {e}")

if __name__ == '__main__':
    video_url = "http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxxx"
    save_path = "video.mp4"
    download_and_save_video(video_url, save_path)

    Q: Can the returned video link be played directly in a browser?

    A: This is not recommended because the link expires after 24 hours. The best practice is to have your backend download and store the video, and then use the new permanent link for playback.