DocsICP FilingConsole
Documentation
Home Page Alibaba Cloud Model Studio Model API Video Generation Wan Wan2.7 - text-to-video

Wan2.7 - text-to-video API reference

Updated at:
Copy as MD
Product
My Favorites

The Wan text-to-video model generates smooth videos from text prompts .

References: User guide

Availability

To ensure successful calls, make sure the model, endpoint URL, and API key all belong to the same region. Cross-region calls fail.

NoteThe sample code in this topic applies to the Beijing region.

ImportantAlibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing) and Singapore regions. The new dedicated domains deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:

  • China (Beijing): from https://dashscope.aliyuncs.com to https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore: from https://dashscope-intl.aliyuncs.com to https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId} is your workspace ID, which you can find on the Workspace Details page in the Alibaba Cloud Model Studio console. The existing domain remains fully functional.

HTTP invocation

ImportantThis interface uses the new protocol and supports only the wan2.7 model.

Because text-to-video tasks are time-consuming (usually 1 to 5 minutes), the API uses asynchronous invocation. The process consists of two core steps: "Create a task -> Poll for the result", as follows:

Step 1: Create a task to get the task ID

Beijing

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

Singapore

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

Replace {WorkspaceId} with your actual workspace ID when calling.

Note

  • After the task is created, use the task_id returned by the API to query the result. The task_id is valid for 24 hours. Do not create duplicate tasks. Just poll for the result.
  • For guidance for new users, see Postman.

Request parameters

Headers

Content-Typestring(Required)

The request content type. This parameter must be set to application/json.

Authorizationstring(Required)

Request authentication. The API uses an Alibaba Cloud Model Studio API key for authentication. Example: Bearer sk-xxxx.

X-DashScope-Asyncstring(Required)

The asynchronous processing configuration parameter. HTTP requests support only asynchronous calls and must be set to enable.

ImportantIf this request header is missing, the following error is returned: "current user api does not support synchronous calls".

Request body

model string (Required)

Model name. For available models, see Model list.

Example: wan2.7-t2v, wan2.7-t2v-2026-06-12.

input object (Required)

Basic input information, such as the prompt.

Properties

prompt string (Required)

The text prompt. Describes the elements and visual features that you want in the generated video.

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

  • wan2.7-t2v, wan2.7-t2v-2026-06-12: Up to 5,000 characters.

Example: A kitten running in the moonlight.

For tips on writing prompts, see the Text-to-video/image-to-video prompt guide.

negative_prompt string (Optional)

The negative prompt, which describes content that you do not want to see in the video and constrains the video output.

Supports Chinese and English. Up to 500 characters, and excess text is automatically truncated.

Example: low resolution, error, worst quality, low quality, deformed, extra fingers, bad proportions.

audio_url string (Optional)

The URL of the audio file. The model generates the video using this audio.

Supported input formats:

  1. Public URL:

  2. Temporary URL:

Audio limits:

  • Format: WAV, MP3.
  • Duration: 2 to 30 seconds.
  • File size: Up to 15 MB.
  • Over-limit handling: If the audio is longer than the duration value (for example, 5 seconds), only the first 5 seconds are used and the rest is discarded. If the audio is shorter than the video duration, the part beyond the audio length is silent. For example, if the audio is 3 seconds and the video is 5 seconds, the first 3 seconds of the output video have sound and the last 2 seconds are silent.

parameters object (Optional)

Video processing parameters, such as setting the video resolution, enabling prompt rewriting, and adding a watermark.

Properties

resolution string (Optional)

Importantresolution directly affects the cost. Check model pricing before calling.

The resolution tier of the generated video, which controls the video clarity (total pixels).

  • wan2.7-t2v, wan2.7-t2v-2026-06-12: Valid values: 720P, 1080P. Default: 1080P.

ratio string (Optional)

The aspect ratio of the generated video.

  • 16:9 (default)
  • 9:16
  • 1:1
  • 4:3
  • 3:4

The output video resolutions (width and height in pixels) for each aspect ratio are listed in the table below.

Resolution tier

Aspect ratio

Output video resolution (width*height)

720P

16:9

1280*720

9:16

720*1280

1:1

960*960

4:3

1104*832

3:4

832*1104

1080P

16:9

1920*1080

9:16

1080*1920

1:1

1440*1440

4:3

1648*1248

3:4

1248*1648

duration integer (Optional)

Importantduration directly affects the cost. Billing is per second. Check model pricing before calling.

The duration of the generated video, in seconds.

  • wan2.7-t2v, wan2.7-t2v-2026-06-12: An integer between 2 and 15. Default: 5.

prompt_extendboolean (Optional)

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

  • true: Default. Enable prompt rewriting.
  • false: Disable prompt rewriting.

watermark boolean (Optional)

Whether to add a watermark. The watermark is in the lower-right corner of the video with the fixed text "AI Generated".

  • false: Default. No watermark.
  • true: Add a watermark.

seedinteger (Optional)

The random number seed, in the range [0, 2147483647].

If not specified, the system generates a random seed. To improve the reproducibility of generation results, use a fixed seed value.

Note that model generation is probabilistic. Even with the same seed, identical results are not guaranteed each time.

Multi-shot narrative

Control the shot structure with natural language in prompt. There is no need to set the shot_type parameter, and setting it has no effect.

  • Single shot: Input "Generate a single-shot video".
  • Multi-shot: Input "Generate a multi-shot video" or describe shots with timestamps (for example, "Shot 1 [0-3 seconds] wide shot: A rainy New York street at night").
  • Default: If unspecified, the model interprets the prompt content.
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.7-t2v-2026-06-12",
    "input": {
        "prompt": "A tense detective story with cinematic storytelling. Shot 1 [0-3 seconds] wide shot: Rainy New York street at night, neon lights flicker, a detective in a black trench coat walks briskly. Shot 2 [3-6 seconds] medium shot: The detective enters an old building, rain wets his coat, the door closes slowly behind him. Shot 3 [6-9 seconds] close-up: The detective's focused eyes, distant sirens sound, he frowns slightly. Shot 4 [9-12 seconds] medium shot: The detective moves carefully down a dim hallway, his flashlight illuminating the way. Shot 5 [12-15 seconds] close-up: The detective discovers a key clue, his face shows sudden realization."
    },
    "parameters": {
        "resolution": "720P",
        "ratio": "16:9",
        "prompt_extend": true,
        "watermark": true,
        "duration": 15
    }
}'

Provide an audio file

You can pass a custom audio URL in the input.audio_url parameter.

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.7-t2v-2026-06-12",
    "input": {
        "prompt": "An epic and cute scene. A small, adorable cartoon kitten general, wearing exquisitely detailed golden armor and a slightly oversized helmet, stands bravely on a cliff. He rides a small but heroic warhorse and says: 'The long clouds of Qinghai darken the snowy mountains, a lone city gazes at Yumen Pass from afar. Through a hundred battles in the yellow sand, the golden armor is worn, but we will not return until we have broken Loulan'. Below the cliff, a vast and endless army of mice with makeshift weapons is charging forward. This is a dramatic, large-scale battle scene inspired by ancient Chinese war epics. In the distance, dark clouds gather in the sky over the snowy mountains. The overall atmosphere is a comical and epic fusion of 'cute' and 'domineering'.",
        "audio_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250923/hbiayh/%E4%BB%8E%E5%86%9B%E8%A1%8C.mp3"
    },
    "parameters": {
        "resolution": "720P",
        "ratio": "16:9",
        "prompt_extend": true,
        "duration": 10
    }
}'

Automatic dubbing

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

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.7-t2v-2026-06-12",
    "input": {
        "prompt": "An epic and cute scene. A small, adorable cartoon kitten general, wearing exquisitely detailed golden armor and a slightly oversized helmet, stands bravely on a cliff. He rides a small but heroic warhorse and says: 'The long clouds of Qinghai darken the snowy mountains, a lone city gazes at Yumen Pass from afar. Through a hundred battles in the yellow sand, the golden armor is worn, but we will not return until we have broken Loulan'. Below the cliff, a vast and endless army of mice with makeshift weapons is charging forward. This is a dramatic, large-scale battle scene inspired by ancient Chinese war epics. In the distance, dark clouds gather in the sky over the snowy mountains. The overall atmosphere is a comical and epic fusion of 'cute' and 'domineering'."
    },
    "parameters": {
        "resolution": "720P",
        "ratio": "16:9",
        "prompt_extend": true,
        "duration": 10
    }
}'

Use a negative prompt

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

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.7-t2v-2026-06-12",
    "input": {
        "prompt": "A kitten running in the moonlight",
        "negative_prompt": "flower"
    },
    "parameters": {
        "resolution": "720P",
        "ratio": "16:9"
    }
}'

dashscope CLI

export DASHSCOPE_API_KEY="your-api-key"
# Replace {WorkspaceId} with your workspace ID, and cn-beijing with the corresponding region (Singapore: ap-southeast-1, US East: us-east-1)
export DASHSCOPE_HTTP_BASE_URL="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"
dashscope video-synthesis create -m wan2.7-t2v -p "A kitten running"

ImportantThe SDK Expert interactive assistant can accomplish the same development and troubleshooting tasks in natural language. See

DashScope SDK Expert.

For the complete region table, see Base URL overview.

Response parameters

output object

Task output information.

Properties

task_id string

The task ID. Valid for queries for 24 hours.

task_status string

The task status.

Enumeration values

  • PENDING: Task queued
  • RUNNING: Task processing
  • SUCCEEDED: Task completed successfully
  • FAILED: Task failed
  • CANCELED: Task canceled
  • UNKNOWN: The task does not exist or its status is unknown

request_idstring

Unique request identifier. Useful for tracing request details and troubleshooting.

codestring

The error code returned for failed requests. This parameter is not returned for successful requests. For details, see Error codes.

messagestring

Detailed error information returned for failed requests. This parameter is not returned for successful requests. For details, see Error codes.

Successful response

Save the task_id for querying 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 for troubleshooting.

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

Step 2: Query the result by task ID

Beijing

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

Singapore

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

Replace {WorkspaceId} with your actual workspace ID when calling.

Note

  • Polling recommendation: Video generation takes several minutes. We recommend using a polling mechanism with a reasonable query interval (for example, 15 seconds) to obtain the result.
  • Task state transitions: PENDING (queued) → RUNNING (processing) → SUCCEEDED (success) / FAILED (failure).
  • Result link: After the task succeeds, a video URL is returned, valid for 24 hours. We recommend downloading the video immediately after obtaining the URL and saving it to permanent storage (such as Alibaba Cloud OSS).
  • task_id validity: 24 hours. After expiration, the result can no longer be queried, and the API returns the task status as UNKNOWN.
  • RPS limit: The default RPS of the query API is 20. For higher-frequency queries or event notifications, we recommend that you configure an asynchronous task callback.
  • More operations: For batch queries, task cancellation, and other operations, see Manage asynchronous tasks.

Request parameters

Headers

Authorizationstring(Required)

Request authentication. The API uses an Alibaba Cloud Model Studio API key for authentication. Example: Bearer sk-xxxx.

URL path parameters

task_id string(Required)

The task ID.

Query task result

Replace {task_id} with the exact task_id value returned by the previous API call. The task_id is valid for queries for 24 hours. Also replace {WorkspaceId} with your actual workspace ID.

curl -X GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Response parameters

outputobject

Task output information.

Properties

task_id string

The task ID. Valid for queries for 24 hours.

task_status string

The task status.

Enumeration values

  • PENDING: Task queued
  • RUNNING: Task processing
  • SUCCEEDED: Task completed successfully
  • FAILED: Task failed
  • CANCELED: Task canceled
  • UNKNOWN: The task does not exist or its status is unknown
State transitions during polling:
  • PENDING (queued) → RUNNING (processing) → SUCCEEDED (success) / FAILED (failure).
  • The first query usually returns PENDING (queued) or RUNNING (processing).
  • When the status becomes SUCCEEDED, the response contains the generated video URL.
  • If the status is FAILED, check the error message and retry.
  • If the status is CANCELED, the task has been canceled. To continue, submit a new task.
  • If the status is UNKNOWN, the task does not exist or its status is unknown. This may occur when the task_id does not exist or has expired after the 24-hour validity period.

submit_time string

The task submission time. The format is YYYY-MM-DD HH:mm:ss.SSS.

scheduled_time string

The task execution time. The format is YYYY-MM-DD HH:mm:ss.SSS.

end_time string

The task completion time. The format is YYYY-MM-DD HH:mm:ss.SSS.

video_urlstring

The video URL. Returned only when task_status is SUCCEEDED.

The link is valid for 24 hours and can be used to download the video. The video format is MP4 (H.264 encoding).

orig_prompt string

The original input prompt, corresponding to the request parameter prompt.

codestring

The error code returned for failed requests. This parameter is not returned for successful requests. For details, see Error codes.

messagestring

Detailed error information returned for failed requests. This parameter is not returned for successful requests. For details, see Error codes.

usage object

Output statistics. Only successful results are counted.

Properties

duration float

The total duration of the output video, used for billing.

Specifically, duration=output_video_duration.

input_video_duration integer

Fixed at 0.

output_video_duration integer

The duration of the output video, in seconds. Equal to the value of input.duration.

SR integer

The resolution tier of the generated video. Example: 720.

ratio string

The aspect ratio of the generated video. Example: 16:9.

video_count integer

The number of videos generated. Fixed at 1.

request_idstring

Unique request identifier. Useful for tracing request details and troubleshooting.

Task executed successfully

The video URL is retained for only 24 hours and is automatically deleted after that. Save the generated video promptly.

{
    "request_id": "caa62a12-8841-41a6-8af2-xxxxxx",
    "output": {
        "task_id": "eff1443c-ccab-4676-aad3-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-09-29 14:18:52.331",
        "scheduled_time": "2025-09-29 14:18:59.290",
        "end_time": "2025-09-29 14:23:39.407",
        "orig_prompt": "An epic and cute scene. A small, adorable cartoon kitten general, wearing exquisitely detailed golden armor and a slightly oversized helmet, stands bravely on a cliff. He rides a small but heroic warhorse and says: 'The long clouds of Qinghai darken the snowy mountains, a lone city gazes at Yumen Pass from afar. Through a hundred battles in the yellow sand, the golden armor is worn, but we will not return until we have broken Loulan'. Below the cliff, a vast and endless army of mice with makeshift weapons is charging forward. This is a dramatic, large-scale battle scene inspired by ancient Chinese war epics. In the distance, dark clouds gather in the sky over the snowy mountains. The overall atmosphere is a comical and epic fusion of 'cute' and 'domineering'.",
        "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx"
    },
    "usage": {
        "duration": 10,
        "input_video_duration": 0,
        "output_video_duration": 10,
        "video_count": 1,
        "ratio": "16:9",
        "SR": 720
    }
}

Task execution failed

If the task fails, task_status is set to FAILED with an error code and message. See Error codes for troubleshooting.

{
    "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 queries for 24 hours. After expiration, the result can no longer be queried, and the following error is returned.

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

DashScope SDK invocation

SDK parameter names are basically the same as those of the HTTP API, with parameter structures encapsulated according to the conventions of each language.

Because text-to-video tasks are time-consuming (usually 1 to 5 minutes), the SDK encapsulates the asynchronous HTTP call flow at the underlying layer and supports both synchronous and asynchronous invocation.

The actual processing time depends on the number of queued tasks and service execution. Be patient while waiting for the result.

Python SDK invocation

ImportantMake sure the DashScope Python SDK version is 2.0.1 or later before running the following code.

Set region based on the region of the model (pass it in when constructing the Client; the region value varies by region):

Beijing

region="cn-beijing"

Singapore

region="ap-southeast-1"

Replace {WorkspaceId} with your actual workspace ID when calling.

Synchronous invocation

Request example 
import dashscope
import os
from dashscope.v2 import DashScopeError

# The following is the configuration for the China (Beijing) region. Replace {WorkspaceId} with your Model Studio workspace ID. The region value varies by region.
client = dashscope.Client(
    # If no environment variable is configured, replace the following line with your Model Studio API key: api_key="sk-xxx"
    # API keys vary by region. Get an API key: https://help.aliyun.com/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

def sample_sync_call_t2v():
    # generate is a one-step call (submits the task and waits for completion) that returns a completed Job
    print('please wait...')
    try:
        # audio_url / negative_prompt are input-section fields, not in the named signature; pass them through extra_input
        job = client.videos.generate(model='wan2.7-t2v-2026-06-12',
                                     prompt='An epic and cute scene. A small, adorable cartoon kitten general, wearing exquisitely detailed golden armor and a slightly oversized helmet, stands bravely on a cliff. He rides a small but heroic warhorse and says: "The long clouds of Qinghai darken the snowy mountains, a lone city gazes at Yumen Pass from afar. Through a hundred battles in the yellow sand, the golden armor is worn, but we will not return until we have broken Loulan". Below the cliff, a vast and endless army of mice with makeshift weapons is charging forward. This is a dramatic, large-scale battle scene inspired by ancient Chinese war epics. In the distance, dark clouds gather in the sky over the snowy mountains. The overall atmosphere is a comical and epic fusion of "cute" and "domineering".',
                                     extra_input={'audio_url': 'https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250923/hbiayh/%E4%BB%8E%E5%86%9B%E8%A1%8C.mp3',
                                                  'negative_prompt': ""},
                                     resolution='720P',
                                     ratio='16:9',
                                     duration=10,
                                     prompt_extend=True,
                                     watermark=False,
                                     seed=12345)
        print(job)
        print(job.video_url)
    except DashScopeError as e:
        print(f"HTTP status code: {e.status_code}")
        print(f"Error code: {e.code}")
        print(f"Error message: {e.message}")
        print("See the documentation: https://help.aliyun.com/en/model-studio/developer-reference/error-code")

if __name__ == '__main__':
    sample_sync_call_t2v()
Response example

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

{
    "request_id": "72082605-4559-9bb7-aa5c-xxxxxx",
    "task_id": "43b954a2-3e86-4681-9443-xxxxxx",
    "status": "SUCCEEDED",
    "results": [
        {
            "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxxx"
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 1,
        "FAILED": 0
    },
    "usage": {
        "video_count": 1,
        "video_duration": 0,
        "video_ratio": "",
        "duration": 10,
        "input_video_duration": 0,
        "output_video_duration": 10,
        "SR": 720,
        "ratio": "16:9"
    }
}

Asynchronous invocation

Request example 
import dashscope
import os
from dashscope.v2 import DashScopeError

# The following is the configuration for the China (Beijing) region. Replace {WorkspaceId} with your Model Studio workspace ID. The region value varies by region.
client = dashscope.Client(
    # If no environment variable is configured, replace the following line with your Model Studio API key: api_key="sk-xxx"
    # API keys vary by region. Get an API key: https://help.aliyun.com/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

def sample_async_call_t2v():
    # call async api, will return the task information
    # you can get task status with the returned task id.
    try:
        # audio_url / negative_prompt are input-section fields, not in the named signature; pass them through extra_input
        job = client.videos.jobs.create(model='wan2.7-t2v-2026-06-12',
                                        prompt='An epic and cute scene. A small, adorable cartoon kitten general, wearing exquisitely detailed golden armor and a slightly oversized helmet, stands bravely on a cliff. He rides a small but heroic warhorse and says: "The long clouds of Qinghai darken the snowy mountains, a lone city gazes at Yumen Pass from afar. Through a hundred battles in the yellow sand, the golden armor is worn, but we will not return until we have broken Loulan". Below the cliff, a vast and endless army of mice with makeshift weapons is charging forward. This is a dramatic, large-scale battle scene inspired by ancient Chinese war epics. In the distance, dark clouds gather in the sky over the snowy mountains. The overall atmosphere is a comical and epic fusion of "cute" and "domineering".',
                                        extra_input={'audio_url': 'https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250923/hbiayh/%E4%BB%8E%E5%86%9B%E8%A1%8C.mp3',
                                                     'negative_prompt': ""},
                                        resolution='720P',
                                        ratio='16:9',
                                        duration=10,
                                        prompt_extend=True,
                                        watermark=False,
                                        seed=12345)
        print(job)
        print("task_id: %s" % job.task_id)
    except DashScopeError as e:
        print(f"HTTP status code: {e.status_code}")
        print(f"Error code: {e.code}")
        print(f"Error message: {e.message}")
        print("See the documentation: https://help.aliyun.com/en/model-studio/developer-reference/error-code")
        return

    # get the task information include the task status.
    try:
        snapshot = client.videos.jobs.fetch(job.task_id)
        print(snapshot.status)  # check the task status
    except DashScopeError as e:
        print(f"HTTP status code: {e.status_code}")
        print(f"Error code: {e.code}")
        print(f"Error message: {e.message}")
        print("See the documentation: https://help.aliyun.com/en/model-studio/developer-reference/error-code")

    # wait the task complete, will call fetch interval, and check it's in finished status.
    # (2.0 jobs.wait uses exponential backoff polling with a default total budget of 24 hours; a FAILED task raises an exception)
    try:
        done = client.videos.jobs.wait(job)
        print(done)
        print(done.video_url)
    except DashScopeError as e:
        print(f"HTTP status code: {e.status_code}")
        print(f"Error code: {e.code}")
        print(f"Error message: {e.message}")
        print("See the documentation: https://help.aliyun.com/en/model-studio/developer-reference/error-code")

if __name__ == '__main__':
    sample_async_call_t2v()
Response example
  1. Response example for task creation
{
	"request_id": "c86ff7ba-8377-917a-90ed-xxxxxx",
	"task_id": "721164c6-8619-4a35-a6d9-xxxxxx",
	"status": "PENDING"
}
  1. Response example for querying the task result

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

{
    "request_id": "72082605-4559-9bb7-aa5c-xxxxxx",
    "task_id": "43b954a2-3e86-4681-9443-xxxxxx",
    "status": "SUCCEEDED",
    "results": [
        {
            "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxxx"
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 1,
        "FAILED": 0
    },
    "usage": {
        "video_count": 1,
        "video_duration": 0,
        "video_ratio": "",
        "duration": 10,
        "input_video_duration": 0,
        "output_video_duration": 10,
        "SR": 720,
        "ratio": "16:9"
    }
}

Java SDK invocation

ImportantMake sure the DashScope Java SDK version is 2.22.14 or later before running the following code.

Set Constants.baseHttpApiUrl based on the region of the model:

Beijing

Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";

Singapore

Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";

Replace {WorkspaceId} with your actual workspace ID when calling.

Synchronous invocation

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

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 {

    static {
        // The following is the URL for the Beijing region. URLs vary by region. For more information, see: https://help.aliyun.com/en/model-studio/text-to-video-api-reference
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
    }

    // If no environment variable is configured, replace the following line with your Model Studio API key: api_key="sk-xxx"
    // API keys vary by region. Get an API key: https://help.aliyun.com/en/model-studio/get-api-key
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    /**
     * Create a video compositing task and wait for the task to complete.
     */
    public static void text2Video() throws ApiException, NoApiKeyException, InputRequiredException {
        VideoSynthesis vs = new VideoSynthesis();

        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.7-t2v-2026-06-12")
                        .prompt("An epic and cute scene. A small, adorable cartoon kitten general, wearing exquisitely detailed golden armor and a slightly oversized helmet, stands bravely on a cliff. He rides a small but heroic warhorse and says: 'The long clouds of Qinghai darken the snowy mountains, a lone city gazes at Yumen Pass from afar. Through a hundred battles in the yellow sand, the golden armor is worn, but we will not return until we have broken Loulan'. Below the cliff, a vast and endless army of mice with makeshift weapons is charging forward. This is a dramatic, large-scale battle scene inspired by ancient Chinese war epics. In the distance, dark clouds gather in the sky over the snowy mountains. The overall atmosphere is a comical and epic fusion of 'cute' and 'domineering'.")
                        .audioUrl("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250923/hbiayh/%E4%BB%8E%E5%86%9B%E8%A1%8C.mp3")
                        .negativePrompt("")
                        .resolution("720P")
                        .ratio("16:9")
                        .duration(10)
                        .promptExtend(true)
                        .watermark(false)
                        .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. Download the video promptly.

{
    "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": "An epic and cute scene. A small, adorable cartoon kitten general, wearing exquisitely detailed golden armor and a slightly oversized helmet, stands bravely on a cliff. He rides a small but heroic warhorse and says: 'The long clouds of Qinghai darken the snowy mountains, a lone city gazes at Yumen Pass from afar. Through a hundred battles in the yellow sand, the golden armor is worn, but we will not return until we have broken Loulan'. Below the cliff, a vast and endless army of mice with makeshift weapons is charging forward. This is a dramatic, large-scale battle scene inspired by ancient Chinese war epics. In the distance, dark clouds gather in the sky over the snowy mountains. The overall atmosphere is a comical and epic fusion of 'cute' and 'domineering'.",
        "submit_time": "2026-04-16 23:13:40.553",
        "scheduled_time": "2026-04-16 23:13:49.415",
        "end_time": "2026-04-16 23:17:56.380"
    },
    "usage": {
        "video_count": 1,
        "duration": 10.0,
        "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 {

    static {
        // The following is the URL for the Beijing region. URLs vary by region. For more information, see: https://help.aliyun.com/en/model-studio/text-to-video-api-reference
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
    }

    // If no environment variable is configured, replace the following line with your Model Studio API key: api_key="sk-xxx"
    // API keys vary by region. Get an API key: https://help.aliyun.com/en/model-studio/get-api-key
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    /**
     * Create a video compositing task and wait for the task to complete.
     */
    public static void text2Video() throws ApiException, NoApiKeyException, InputRequiredException {
        VideoSynthesis vs = new VideoSynthesis();

        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.7-t2v-2026-06-12")
                        .prompt("An epic and cute scene. A small, adorable cartoon kitten general, wearing exquisitely detailed golden armor and a slightly oversized helmet, stands bravely on a cliff. He rides a small but heroic warhorse and says: 'The long clouds of Qinghai darken the snowy mountains, a lone city gazes at Yumen Pass from afar. Through a hundred battles in the yellow sand, the golden armor is worn, but we will not return until we have broken Loulan'. Below the cliff, a vast and endless army of mice with makeshift weapons is charging forward. This is a dramatic, large-scale battle scene inspired by ancient Chinese war epics. In the distance, dark clouds gather in the sky over the snowy mountains. The overall atmosphere is a comical and epic fusion of 'cute' and 'domineering'.")
                        .audioUrl("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250923/hbiayh/%E4%BB%8E%E5%86%9B%E8%A1%8C.mp3")
                        .negativePrompt("")
                        .resolution("720P")
                        .ratio("16:9")
                        .duration(10)
                        .promptExtend(true)
                        .watermark(false)
                        .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 empty
        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. Response example for task creation.
{
        "request_id": "5dbf9dc5-4f4c-9605-85ea-xxxxxxxx",
	"output": {
		"task_id": "7277e20e-aa01-4709-xxxxxxxx",
		"task_status": "PENDING"
	}
}
  1. Response example for querying the task result

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

{
    "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": "An epic and cute scene. A small, adorable cartoon kitten general, wearing exquisitely detailed golden armor and a slightly oversized helmet, stands bravely on a cliff. He rides a small but heroic warhorse and says: 'The long clouds of Qinghai darken the snowy mountains, a lone city gazes at Yumen Pass from afar. Through a hundred battles in the yellow sand, the golden armor is worn, but we will not return until we have broken Loulan'. Below the cliff, a vast and endless army of mice with makeshift weapons is charging forward. This is a dramatic, large-scale battle scene inspired by ancient Chinese war epics. In the distance, dark clouds gather in the sky over the snowy mountains. The overall atmosphere is a comical and epic fusion of 'cute' and 'domineering'.",
        "submit_time": "2026-04-16 23:13:40.553",
        "scheduled_time": "2026-04-16 23:13:49.415",
        "end_time": "2026-04-16 23:17:56.380"
    },
    "usage": {
        "video_count": 1,
        "duration": 10.0,
        "input_video_duration": 0.0,
        "output_video_duration": 10.0,
        "SR": "720"
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

Error codes

If the model call fails and returns an error message, see Error codes for troubleshooting.

FAQ

Q: What code changes are required to upgrade from wan2.6 to wan2.7?

A: There are two main changes. Adjust these parameters during migration:

  • Change how the output video resolution is controlled: wan2.7 no longer uses the size field. Instead, the output video resolution is defined by combining resolution (resolution tier) and ratio (aspect ratio). Earlier models used the size field directly.
  • Shot type field removed: wan2.7 no longer supports the shot_type field, which is deprecated. Describe the shot type directly in the prompt. Earlier models supported controlling the shot type through this field.
Previous：Wan 2.7 - image-to-video APINext：Wan2.7 - reference-to-video