DocsICP FilingConsole
官方文档
首页

Wan - video character swap API reference

更新时间：
复制 MD 格式
产品详情
我的收藏

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.

Important

Model Studio has released a workspace-specific domain for the Singapore region: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com. The new dedicated domain delivers superior performance and higher stability for inference requests. We recommend migrating from https://dashscope-intl.aliyuncs.com to the new domain.

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

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)

mix_input_image

HTTP

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

Important

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.

Character swap is time-consuming, so the API uses asynchronous invocation: create a task, then poll for the result.

Step 1: Create a task

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

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

Replace WorkspaceId with your actual Workspace ID.

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

Request parameters

Video character swap

The following is the China (Beijing) region URL. URLs vary by region.

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

For local files, see Upload a file to obtain a temporary URL.

  • 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.jpeg

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

For local files, see Upload a file to obtain a temporary URL.

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

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

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

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

code string

Error code. Returned only for failed requests. See Error codes.

Step 2: Query the result by task ID

China (Beijing)

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

Singapore

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

When calling, replace WorkspaceId with your actual workspace 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.

  • RPS limit: The default RPS for 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

Query task result

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

The following is the China (Beijing) region URL. URLs vary by region.
curl -X GET https://dashscope.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.

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

{
    "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. format is YYYY-MM-DD HH:mm:ss.SSS.

scheduled_time string

The time when the task was executed. format is YYYY-MM-DD HH:mm:ss.SSS.

end_time string

The time when the task was completed. 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 codes.

message string

Detailed error message. Returned only for failed requests. See Error codes.

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

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

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 (Beijing or Singapore) 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.

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

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

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

Previous：Wan - image-to-actionNext：Wanxiang - Digital Human