Alibaba AI Docs

Appearance

Wan - video character swap API reference ​

Replaces the main character in a video with a character from an image while preserving the original scene, lighting, and tone for seamless integration.

  • Core features: Replaces the character in a video with a person from a specified image while preserving the actions, expressions, and environment of the original video.

  • Scenarios: Ideal for character replacement in derivative content creation and post-production.

Examples ​

wan2.2-animate-mix supports 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 ​

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.

Character swap is time-consuming, so the API uses asynchronous invocation: 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-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 ​

## 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
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)** 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 to `wan2.2-animate-mix`.       **input** `object` **(Required)** Input images and video for the character swap.  **Properties**   **image_url** `string` **(Required)** A publicly accessible HTTP or HTTPS URL for the character 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: Width and height must each be in the range \[200, 4096\] pixels. 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.jpegvideo_url string (Required) A publicly accessible HTTP or HTTPS URL for the reference 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 improve output quality.

  • Format: MP4, AVI, or MOV.

  • Resolution: Width and height must each be in the range \[200, 2048\] pixels. Aspect ratio must be between 1:3 and 3:1.

  • File size: Up to 200 MB.

  • Duration: 2 to 30 seconds.

  • Example: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/wqefue/mix_input_video.mp4watermark boolean (Optional) Adds an "AI Generated" watermark in the lower-right corner of the output video.

  • false (default): No watermark.

  • true: Watermark added. parameters object (Required) Properties check_image boolean (Optional) Controls whether the input image is checked before processing.

  • true (default): Checks the input image before processing.

  • false: Skips the check and processes the image directly. mode string (Required) The service mode. Two modes are available:

  • wan-std: Standard mode. Faster generation at lower cost. Best for quick previews and basic animations.

  • wan-pro: Professional mode. Smoother animations and better visual quality, with longer processing time and higher cost. For details, see Examples 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`  Task output information.  **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 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
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)** 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 succeeded ​

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` Task output information.  **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 Returned for successful tasks only. Properties video_duration float Duration of the generated video, in seconds. video_ratio string The service mode used for this request. Returns standard for wan-std mode, or pro for wan-pro mode. request_id string Unique request identifier for tracing and troubleshooting.

Limitations ​

Data retention : Task IDs and video URLs are retained for 24 hours. Download the video to your local device before they expire.

Content moderation : All input and output content is subject to moderation. Prohibited content returns IPInfringementSuspect or DataInspectionFailed errors. For details, 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 the 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 call fails, see Error messages.

FAQ ​

Q: How do I view model call usage? ​

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

Q: How can I improve the quality of generated videos? ​

A: To get better results:

  1. Frame the character consistently in both the input image and the reference video.

  2. Keep body proportions consistent between the image and the video.

  3. Use high-definition source material --- blurry images or low-frame-rate videos reduce detail accuracy.

A: Direct conversion is not supported. Have your backend download the video and upload it to Object Storage Service (OSS) to get a permanent access link. Sample code: Download a 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() # 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)

A: This is not recommended --- links expire after 24 hours. Download and store the video on your backend, then serve it via a permanent link.

Q: How do I get the domain name allowlist 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.

Mirror of Alibaba Cloud Model Studio docs for reference and RAG. Not affiliated with Alibaba Cloud.

Source: alibabacloud.com/help/en/model-studio