Wan image-to-action API reference

Animate a character image by transferring actions from a reference video.

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 Wan - image-to-motion.

Character image	Reference video	Output video (standard mode `wan-std`)	Output video (professional mode `wan-pro`)
*	视频地址	视频地址	视频地址

Prerequisites

Create an API key and export the API key as an environment variable. Important

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

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://dashscope-intl.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis

Beijing : POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesisNote

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

Request parameters

## Image to action

The base_url is for the Singapore region. If you use a model in the Beijing region, replace the base_url with the following: https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis

curl

curl --location 'https://dashscope-intl.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"
 }
 }'

Request headers

Content-Type <i>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.

**Important ** 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
Content: A single front-facing person with an unobstructed face, occupying a moderate portion of the frame
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
Content: A single front-facing person with an unobstructed face, occupying a moderate portion of the frame
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.

Response parameters

Successful response

Save the task_id to query the task status and result.

json

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

json

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

     **output** `*object*` The task output.

Properties

task_id *string* The task ID. Valid for queries for 24 hours.

task_status *string* The status of the task. Enumeration values

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

request_id *string* Unique request identifier for tracing and troubleshooting.

message *string* Detailed error message. Returned only for failed requests. See Error messages.

code *string* Error code. Returned only for failed requests. See Error messages.

Step 2: Query the result by task ID

Singapore

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

Beijing

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

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_id****validity : 24 hours . After this period, queries return the task status as UNKNOWN.

Request parameters

## Query task result

Replace 0385dc79-5ff8-4d82-bcb6-xxxxxx with your actual task_id. ** The base_url is for the Singapore region. If you use a model in the Beijing region, replace the base_url with the following: https://dashscope.aliyuncs.com/api/v1/tasks/0385dc79-5ff8-4d82-bcb6-xxxxxx

curl

curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/0385dc79-5ff8-4d82-bcb6-xxxxxx \\
 --header "Authorization: Bearer $DASHSCOPE_API_KEY"

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

Response parameters

## Task successful

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

json

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

## Task failed

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

json

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

     **output** `*object*` The task output.

Properties

task_id *string* The task ID. Valid for queries for 24 hours.

task_status *string* The status of the task. Enumeration values

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

submit_time *string* The 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 *string* The 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 *string* The 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 *string* URL 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 *string* Error code. Returned only for failed requests. See Error messages.

message *string* Detailed error message. Returned only for failed requests. See Error messages.

usage *object* Output statistics. Only successful results are counted. Properties

video_duration *float* The duration of the generated video, in seconds.

video_ratio *string* The service mode used for this request. Enumeration values: standard and pro. wan-std returns standard. wan-pro returns pro.

request_id *string* Unique request identifier for tracing and troubleshooting.

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

Billing and rate limiting

For free quota and pricing, see Wan - 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 messages.

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

HELPCODEESCAPE-python
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.

Wan image-to-action API reference ​

Model effects ​

Prerequisites ​

HTTP ​

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

Request parameters ​

## Image to action ​

Request headers ​

Request body ​

Response parameters ​

Successful response ​

Error response ​

Step 2: Query the result by task ID ​

Singapore ​

Beijing ​

Request parameters ​

## Query task result ​

<b>Request headers** ​

URL path parameters ​

Response parameters ​

## Task successful ​

## Task failed ​

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? ​

Wan image-to-action API reference

Model effects

Prerequisites

HTTP

Step 1: Create a task and get the task ID

Request parameters

## Image to action

Request headers

Request body

Response parameters

Successful response

Error response

Step 2: Query the result by task ID

Singapore

Beijing

Request parameters

## Query task result

<b>Request headers**

URL path parameters

Response parameters

## Task successful

## Task failed

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?