Wan image-to-action API reference - Alibaba Cloud Model Studio

Feature summary: Transfer actions and expressions from a reference video to a character image to generate an animated video.
Scenarios: Replicate dances, complex body movements, and facial expressions from film and television performances. A low-cost alternative to motion capture.

Model effects

The wan2.2-animate-move model supports two service modes: standard mode wan-std and professional mode wan-pro, which differ in output quality and pricing. For more information, see Wanx-Image-to-Motion.

Character image	Reference video	Output video (standard mode`wan-std`)	Output video (professional mode`wan-pro`)

Prerequisites

Obtain an API key and export the API key as an environment variable.

The China (Beijing) and Singapore regions have separate API keys and request endpoints. They cannot be used interchangeably. Cross-region calls lead to authentication failures or service errors.

Alibaba 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 can be found on the Workspace Details page in the Alibaba Cloud Model Studio console. The existing domain remains fully functional.

HTTP

Video generation uses asynchronous calls. The process has two steps: create a task, then poll for results.

Step 1: Create a task and get the task ID

Singapore: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis Replace {WorkspaceId} with your actual Workspace ID. Beijing: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis

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 guidance for beginners, see Call APIs with Postman or cURL.

Request parameters

Request headers

Content-Type string (Required)The content type of the request. Must be application/json.Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.X-DashScope-Async string (Required)Enables asynchronous processing. HTTP requests support only asynchronous calls. Must be enable.

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

Request body

model string (Required)The model name. Set this parameter to wan2.2-animate-move.input object (Required)The input parameters. Contains the following fields:

Properties

image_url string (Required)A publicly accessible HTTP or HTTPS URL of the character image. URLs containing non-ASCII characters must be URL-encoded.

Format: JPG, JPEG, PNG, BMP, or WEBP
Dimensions: Width and height must both be in the range of [200, 4096] pixels. Aspect ratio must be between 1:3 and 3:1.
File size: No more than 5 MB
Example: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/adsyrp/move_input_image.jpeg

video_url string (Required)A publicly accessible HTTP or HTTPS URL of the reference video. URLs containing non-ASCII characters must be URL-encoded.Recommendation: For better results, use a reference video with higher resolution and frame rate.

Format: MP4, AVI, or MOV
Duration: 2 to 30 seconds
Dimensions: Width and height must both be in the range of [200, 2048] pixels. Aspect ratio must be between 1:3 and 3:1.
File size: No more than 200 MB
Example: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/kaakcn/move_input_video.mp4

watermark bool (Optional)Whether to add a "Generated by Qwen AI" watermark to the bottom-right corner of the output video.

false (default)
true

parameters object (Required)

Properties

check_image bool (Optional)Whether to validate the input image before processing.

true (default)
false

mode string (Required)The service mode. Valid values:

wan-std: Standard mode. Faster generation at lower cost. Suitable for quick previews and basic animation.
wan-pro: Professional mode. Smoother animation and higher quality, with longer processing time and higher cost.

For more information, see Model effects and Billing and rate limiting.

Image to action

The following is the Singapore region URL. Replace {WorkspaceId} with your Bailian workspace ID. URLs vary by region.

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis' \
    --header 'X-DashScope-Async: enable' \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{
        "model": "wan2.2-animate-move",
        "input": {
            "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/adsyrp/move_input_image.jpeg",
            "video_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/kaakcn/move_input_video.mp4",
            "watermark": true
        },
        "parameters": {
            "mode": "wan-std"
        }
      }'

Response parameters

output objectThe task output.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: The task does not exist or its status is unknown.

request_id stringUnique request identifier for tracing and troubleshooting.message stringDetailed error message. Returned only for failed requests. See Error codes.code stringError code. Returned only for failed requests. See Error codes.

Successful response
Error 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"
}

Step 2: Query the result by task ID

Singapore
China (Beijing)

GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}When calling, replace {WorkspaceId} with your actual workspace ID.

Polling recommendation: Video generation takes several minutes. Use a polling mechanism with a reasonable interval, such as 15 seconds.
Task state transition: PENDING → RUNNING → SUCCEEDED or FAILED.
Result link: After a task succeeds, a video URL valid for 24 hours is returned. Download and save the video to permanent storage, such as OSS.
task_idvalidity: 24 hours. After this period, queries return the task status as UNKNOWN.

Request parameters

Request headers

Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

URL path parameters

task_id string (Required)The ID of the task.

Query task result

Replace 0385dc79-5ff8-4d82-bcb6-xxxxxx with your actual task_id.

The following is the Singapore region URL. Replace {WorkspaceId} with your Bailian workspace ID. URLs vary by region.

curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/0385dc79-5ff8-4d82-bcb6-xxxxxx \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY"

Response parameters

output objectThe task output.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: The task does not exist or its status is unknown.

submit_time stringThe time when the task was submitted. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringThe time when the task was executed. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.end_time stringThe time when the task was completed. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.results object

Properties

video_url stringURL of the generated video. Returned only when task_status is SUCCEEDED.Valid for 24 hours. The video is in MP4 format with H.264 encoding.

code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.

usage objectOutput statistics. Only successful results are counted.

Properties

video_duration floatThe duration of the generated video, in seconds.video_ratio stringThe service mode used for this request. Enumeration values: standard and pro.wan-std returns standard. wan-pro returns pro.

request_id stringUnique request identifier for tracing and troubleshooting.

Task successful
Task failed

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

{
    "request_id": "a67f8716-18ef-447c-a286-xxxxxx",
    "output": {
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-09-18 15:32:00.105",
        "scheduled_time": "2025-09-18 15:32:15.066",
        "end_time": "2025-09-18 15:34:41.898",
        "results": {
            "video_url": "http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxx.mp4?Expires=xxxxxx"
        }
    },
    "usage": {
        "video_duration": 5.2,
        "video_ratio": "standard"
    }
}

When a task fails, task_status is FAILED with an error code and message. See Error codes.

{
    "request_id": "daad9007-6acd-9fb3-a6bc-xxxxxx",
    "output": {
        "task_id": "fe8aa114-d9f1-4f76-b598-xxxxxx",
        "task_status": "FAILED",
        "code": "InternalError",
        "message": "xxxxxx"
    }
}

Limitations

Data validity: Task IDs and video URLs expire after 24 hours. Download videos promptly. Content moderation: All inputs and outputs are automatically moderated. Non-compliant content returns an IPInfringementSuspect or DataInspectionFailed error. For more information, see Error codes.

Billing and rate limiting

For free quota and pricing, see Wanx-Image-to-Motion.
For rate limits, see Wan series.
Billing details:
- Only output is billed, based on video duration in seconds.
- Failed calls are free and do not consume the new user free quota.

Error codes

If a model call fails and returns an error message, see Error codes.

FAQ

How can I improve output video quality?

Ensure the character occupies a similar portion of the frame in both the input image and the reference video.
Keep body proportions consistent between the image and the video.
Use high-definition source materials. Blurry images or low-frame-rate videos reduce output quality.

How can I convert a temporary video link to a permanent one?

The link cannot be converted directly. Download the video from your backend and upload it to permanent object storage (such as OSS) to get a permanent URL.

Example code: Download the 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 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 downloaded successfully 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)

Can I play the returned video link directly in a browser?

Not recommended. The link expires after 24 hours. Download and save the video from your backend, then serve it via a permanent link.

How do I get the domain name whitelist for video storage?

A: Videos generated by models are stored in OSS. The API returns a temporary public URL. To configure a firewall whitelist for this download URL, note the following: The underlying storage may change dynamically. This topic does not provide a fixed OSS domain name whitelist to prevent access issues caused by outdated information. If you have security control requirements, contact your account manager to obtain the latest OSS domain name list.

​Model effects

​Prerequisites

​HTTP

​Step 1: Create a task and get the task ID

Request parameters

Request headers

Request body

Response parameters

​Step 2: Query the result by task ID

Request parameters

Request headers

URL path parameters

Response parameters

​Limitations

​Billing and rate limiting

​Error codes

​FAQ

​How can I improve output video quality?

​How can I convert a temporary video link to a permanent one?

​Can I play the returned video link directly in a browser?

​How do I get the domain name whitelist for video storage?

Model effects

Prerequisites

HTTP

Step 1: Create a task and get the task ID

Step 2: Query the result by task ID

Limitations

Billing and rate limiting

Error codes

FAQ

How can I improve output video quality?

How can I convert a temporary video link to a permanent one?

Can I play the returned video link directly in a browser?

How do I get the domain name whitelist for video storage?