Skip to main content
Alibaba Cloud Model Studio home pageAlibaba Cloud Model Studio
Wan

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.
Alibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing) and Singapore regions. The new dedicated domains deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:
  • China (Beijing): from https://dashscope.aliyuncs.com to https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore: from https://dashscope-intl.aliyuncs.com to https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} is your workspace ID, which can be found on the Workspace Details page in the Alibaba Cloud 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 imageReference videoOutput video (standard modewan-std)Output video (professional modewan-pro)
mix_input_image

HTTP

Obtain an API key and export the API key as an environment variable.
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

Singapore:POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis Beijing:POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis Replace {WorkspaceId} with your actual workspace ID.
  • 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

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.
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.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.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.
  • Video character swap
The following is the Singapore region URL. Replace {WorkspaceId} with your Bailian workspace ID. URLs vary by region.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.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"
        }
      }'

Response parameters

output objectTask output information.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: The task does not exist or its status is unknown.
request_id stringUnique request identifier for tracing and troubleshooting.message stringDetailed error message. Returned only for failed requests. See Error codes.code stringError code. Returned only for failed requests. See Error codes.
  • Successful response
  • Error 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"
}

Step 2: Query the result by task ID

  • Singapore
  • China (Beijing)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}When calling, replace {WorkspaceId} with your actual workspace ID.
  • 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_idvalidity: 24 hours. After this period, queries return the task status as UNKNOWN.

Request parameters

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.
  • Query task result
Replace 0385dc79-5ff8-4d82-bcb6-xxxxxx with your actual task_id.
The following is the Singapore region URL. Replace {WorkspaceId} with your Bailian workspace ID. URLs vary by region. 
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/0385dc79-5ff8-4d82-bcb6-xxxxxx \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY"

Response parameters

output objectTask output information.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: The task does not exist or its status is unknown.
submit_time stringThe 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 stringThe 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 stringThe 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 stringURL 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 stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.
usage objectReturned for successful tasks only.

Properties

video_duration floatDuration of the generated video, in seconds.video_ratio stringThe service mode used for this request. Returns standard for wan-std mode, or pro for wan-pro mode.
request_id stringUnique request identifier for tracing and troubleshooting.
  • Task succeeded
  • Task failed
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"
    }
}

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 (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. 
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.
Alibaba Cloud Model Studio home pageAlibaba Cloud Model Studio
API Usage
Text Generation
Image Generation
  • FAQ
Video Generation
Audio
Real-time Multimodal
Realtime API
Text Embedding
More Models
Toolkit/Framework
Model Production
File Management
More
Wan - video character swap API reference - Alibaba Cloud Model Studio