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

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

Step 1: Create a task and get the task ID

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"
    },
    "parameters": {
        "mode": "wan-std"
    }
  }'

Step 2: Query the result by task ID

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

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

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

The wan2.2-animate-mix model provides two service modes, standard mode wan-std and professional mode wan-pro, to support video character replacement effects in different scenarios.

Billing rules

• Billing mode: This service is billed on a pay-as-you-go basis. You are charged based on the duration (in seconds) of successfully generated videos. The billable duration is determined by the usage.video_duration field in the successful task response.

  Click to view a billing example

  Fees are calculated after the free quota is used up. The formula is: Total fee = Actual video duration (seconds) × Unit price of the selected service mode.

  For example, if you call a model in the Singapore region to generate a video using the standard mode wan-std, and the usage.video_duration returned after the task is successful is 5.2 seconds.

  The fee is calculated as: 5.2 seconds × $0.18/second = $0.936

  Note: The billing duration is based on the usage.video_duration field that is returned after a task is successfully completed.

• Consumption order: The free quota is consumed first. After the free quota is used up, the pay-as-you-go billing method is used by default. You can enable the "Free quota only" feature to avoid extra charges after your free quota is used up. For more information, see Free quota for new users.

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

Rate limiting: An Alibaba Cloud account and its RAM users share a total request frequency limit of 5 requests per second. A maximum of 1 task can be processed at a time. New tasks that exceed the limit are added to a queue. For more information about model throttling rules and FAQ, see Rate limits.

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 Model Observation (Singapore or Beijing) page to view metrics such as the number of calls and the success rate. How do I 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 using code, and then upload it to a permanent object storage service, such as Alibaba Cloud OSS, to generate a new, permanent access URL.

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.