Swap Video Characters with Wan2.2 Animate Mix - Model Studio

Examples

wan2.2-animate-mix offers two service modes: standard mode (wan-std) and professional mode (wan-pro). See Billing and rate limiting for performance and billing differences.

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

HTTP

Get 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. Do not use them interchangeably. Cross-region calls result in authentication failures or service errors.

Video character swap tasks are time-consuming, so the API uses asynchronous invocation with two steps: create a task, then poll for the result.

Step 1: Create a task

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-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 Use Postman or cURL.

Request parameters	Video character swap The following is the base_url for the Singapore region. If you use a model from the Beijing region, replace the base_url with:`https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis` 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-mix", "input": { "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/bhkfor/mix_input_image.jpeg", "video_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/wqefue/mix_input_video.mp4", "watermark": true }, "parameters": { "mode": "wan-std" } }'
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. Set this to `wan2.2-animate-mix`.
input `object` (Required) Basic input information. Properties image_url `string` (Required) A publicly accessible HTTP or HTTPS link to the input image. The URL must not contain non-ASCII characters (e.g., Chinese). If it does, encode the URL before passing it. Format: JPG, JPEG, PNG, BMP, or WEBP. Resolution limits: The width and height of the image must be within the range of `[200, 4096]` pixels. The aspect ratio must be between 1:3 and 3:1. File size: Up to 5 MB Example: `https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/bhkfor/mix_input_image.jpeg` video_url `string` (Required) A publicly accessible HTTP or HTTPS link to the input video. The URL must not contain non-ASCII characters (e.g., Chinese). If it does, encode the URL before passing it. Tip: Higher resolution and frame rate in the reference video improves output quality. Format: MP4, AVI, or MOV. Resolution limits: The width and height of the video must be within the range of `[200, 2048]` pixels. The aspect ratio must be between 1:3 and 3:1. File size: Up to 200 MB Duration: 2 to 30s Example: `https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/wqefue/mix_input_video.mp4` watermark `boolean` (Optional) Specifies whether to add a watermark ("AI Generated" in the lower-right corner). false (default) true
parameters `object` (Required) Properties check_image `boolean` (Optional) Specifies whether to perform image detection. `true` (default): Detects the input image. `false`: Image detection is skipped and the image is processed directly. mode `string` (Required) The model service mode. The following two modes are supported: `wan-std`: Standard mode. Faster generation and cost-effective. Ideal for quick previews and basic animations. `wan-pro`: Professional mode. Smoother animations and better effects with longer processing time and higher costs. For more information, see Examples and Billing and rate limiting.

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.
message `string` Detailed error message. Returned only when the request fails. See error codes for details.
code `string` The error code. 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}

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

Note

Polling suggestion: Video generation can take several minutes. 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 `0385dc79-5ff8-4d82-bcb6-xxxxxx` with your actual task_id. The base URL below is for the Singapore region. If you use a model in the Beijing region, replace the base URL with: `https://dashscope.aliyuncs.com/api/v1/tasks/0385dc79-5ff8-4d82-bcb6-xxxxxx` `curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/0385dc79-5ff8-4d82-bcb6-xxxxxx \ --header "Authorization: Bearer $DASHSCOPE_API_KEY"`
Headers
Authorization `string` (Required) The authentication credentials using a Model Studio API key. Example: `Bearer sk-xxxx`
URL path parameters
task_id `string` (Required) The ID of the task to query.

Response parameters	Task succeeded Video URLs are retained 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" } }` Task 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": "daad9007-6acd-9fb3-a6bc-xxxxxx", "output": { "task_id": "fe8aa114-d9f1-4f76-b598-xxxxxx", "task_status": "FAILED", "code": "InternalError", "message": "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 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`. results `object` Properties 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. 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 successful tasks only. Properties video_duration `float` The duration of the generated video, in seconds. video_ratio `string` The model service mode used for this request. Valid values: `standard` and `pro`. Returns `standard` for `wan-std` mode, or `pro` for `wan-pro` mode.
request_id `string` Unique identifier for the request. Use for tracing and troubleshooting issues.

Limitations

Data retention: Task ID and video URL are retained for 24 hours only. Download the video to your local device before expiration.

Content moderation: Input and output content are subject to moderation. Prohibited content returns `IPInfringementSuspect` or `DataInspectionFailed` errors. For more information, see Error messages.

Billing and rate limiting

For free quota and unit price, see model pricing.
For rate limits, see Wan series.
Billing details:
- Billing is based on output video duration (in seconds) for successfully generated videos only. Input is not billed.
- Failed calls and processing errors do not incur fees or consume free quota.

Error codes

If a model call fails and an error message is returned, see Error messages to resolve the issue.

FAQ

Q: How do I view model call usage?

A: Model invocation data has approximately 1-hour delay. View metrics (invocation volume, count, success rate) on the Monitoring (Singapore or Beijing) page after invocation. For more information, see How do I view model invocation records?

Q: How can I optimize the quality of generated videos?

A: To optimize quality:

Ensure consistent character framing between input image and reference video.
Maintain consistent body proportions between image and video.
Use high-definition source material. Avoid blurry images or low-frame-rate videos for accurate detail recognition.

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

A: You cannot convert the link directly. Have your backend service download the video file and upload it to Object Storage Service (OSS) to generate a permanent access link.

Sample 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 timeout
        response.raise_for_status() # Raise an exception if the HTTP status code is not 200
        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}")
        # Logic for uploading to permanent storage can be added 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: Not recommended -- links expire after 24 hours. Best practice: download and store the video on your backend, then use a permanent link for playback.

Q: 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.

Examples

HTTP

Step 1: Create a task

Request parameters

Video character swap

Headers

Request body

Response parameters

Successful response

Error response