All Products
Search

This Product

    Alibaba Cloud Model Studio:Wan - video character swap API reference

    Document Center

    Alibaba Cloud Model Studio:Wan - video character swap API reference

    Last Updated:Feb 11, 2026

    The Wan video character swap model replaces the main character in a video with a character from an image while preserving the original video's scene, lighting, and tone to ensure seamless integration.

    • Core feature: Replaces the main character in a video with a character from a specified image while preserving the original video’s actions, expressions, and environment.

    • Scenarios: This feature is suitable for use cases such as derivative content creation and film post-production.

    Examples

    The Wan wan2.2-animate-mix video character swap model supports two service modes: standard mode wan-std and professional mode wan-pro. These modes differ in performance and billing. For more information, see Billing and rate limiting.

    Character image

    Reference video

    Output video (Standard mode wan-std)

    Output video (Professional mode wan-pro)

    mix_input_image

    HTTP

    You must obtain an API key and set 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 generation is time-consuming. The HTTP API operates in asynchronous mode. The call process consists of two steps:

    1. Create a task to get a task ID: Submit a request to create a task. The response includes a task_id.

    2. Query the result by task ID: Use the task_id to poll the task status until the task completes and the video URL is returned.

    Step 1: Create a task

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

    Beijing region: 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 Postman.

    Request parameters

    Video character swap

    The following example shows the request for the Singapore region. To use the model in 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"
    }
  }'

    Request 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 parameter to wan2.2-animate-mix.

    input object (Required)

    The input parameter object, which contains the following fields:

    Properties

    image_url string (Required)

    The publicly accessible HTTP or HTTPS URL of the input image. The URL must not contain non-ASCII characters, such as Chinese characters. If it does, encode the URL before passing it in the request.

    • Formats: JPG, JPEG, PNG, BMP, WEBP

    • Dimension limits: The width and height of the image must each be within the [200,4096] pixel range, and the aspect ratio must be between 1:3 and 3:1.

    • Size limit: No more than 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)

    The publicly accessible HTTP or HTTPS URL of the input video. The URL must not contain non-ASCII characters, such as Chinese characters. If it does, encode the URL before passing it in the request.

    Recommendation: For better video quality, use a reference video with a higher resolution and frame rate.

    • Formats: MP4, AVI, MOV

    • Dimension limits: The width and height of the video must both be within the range of [200, 2048] pixels. The aspect ratio must be between 1:3 and 3:1.

    • Size limit: No more than 200 MB

    • Duration limit: The duration must be between 2 s and 30 s.

    • Example: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/wqefue/mix_input_video.mp4

    watermark bool (Optional)

    Specifies whether to add a watermark. The watermark appears in the bottom-right corner of the video and displays the text "Tongyi AI Generated".

    • false (default)

    • true

    parameters object (Required)

    Properties

    check_image bool (Optional)

    Specifies whether to perform an image check.

    • true (default)

    • false

    mode string (Required)

    The model service mode. Two modes are supported.

    • wan-std

    • wan-pro

    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

    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. We recommend that you 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 the actual task_id.

    The following example shows the request for the Singapore region. To 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"
    Request 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

    Usage statistics for the task. Only successful results are counted.

    Properties

    video_duration float

    The billable duration of the video generated by this request, in seconds.

    video_ratio string

    The video service mode selected for this request. Enumeration values: standard, pro.

    If you select the standard mode wan-std, the value is standard. If you select the professional mode wan-pro, the value is pro.

    request_id string

    Unique identifier for the request. Use for tracing and troubleshooting issues.

    Limitations

    Data retention: The task_id and video URL are retained for only 24 hours. After this period, they cannot be queried or downloaded. Promptly download the video to your local device.

    Content moderation: Both input and output content are subject to content moderation. Requests containing non-compliant content return the error "IPInfringementSuspect" or "DataInspectionFailed". For more information, see Error messages.

    Network access configuration: The video URL is stored in Object Storage Service (OSS). If your business system cannot access external OSS URLs due to security policies, add the following OSS domain names to the network access whitelist.

    # OSS domain name list
dashscope-result-bj.oss-cn-beijing.aliyuncs.com
dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com
dashscope-result-sh.oss-cn-shanghai.aliyuncs.com
dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com
dashscope-result-zjk.oss-cn-zhangjiakou.aliyuncs.com
dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com
dashscope-result-hy.oss-cn-heyuan.aliyuncs.com
dashscope-result-cd.oss-cn-chengdu.aliyuncs.com
dashscope-result-gz.oss-cn-guangzhou.aliyuncs.com
dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com

    Billing and rate limiting

    • For free quota and unit price, see Model pricing.

    • For rate limits, see Wan series.

    • Billing description:

      • Input is not billed. Output is billed. You are charged based on the duration in seconds of successfully generated videos.

      • If a model call fails or an error occurs during processing, no fees are charged, and your free quota is not consumed.

    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 calling information is subject to an hourly delay. About one hour after a model is invoked, go to the Monitoring (Singapore or Beijing) page to view metrics such as the number of calls and the success rate. How to view model call records?

    Q: How can I improve the quality of the generated video?

    A: Follow these suggestions:

    1. Ensure the character is framed similarly in the input image and the reference video.

    2. Try to keep the body proportions of the character consistent between the image and the video.

    3. Use high-definition source materials. Avoid blurry images and low-frame-rate videos to ensure accurate detail recognition.

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

    A: You cannot convert the URL directly. The correct procedure is for your backend service to retrieve the URL, download the video file programmatically, and then upload it to a permanent object storage service—such as OSS—to generate a new, permanent access URL.

    Example code: Download 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 a 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)

    Q: Can the returned video URL be played directly in a browser?

    A: This is not recommended because the URL expires after 24 hours. The best practice is to have your backend download and store the video, then use the permanent URL for playback.