All Products
Search

This Product

    Alibaba Cloud Model Studio:Wan image-to-action API reference

    Document Center

    Alibaba Cloud Model Studio:Wan image-to-action API reference

    Last Updated:Jun 16, 2026

    Animate a character image by transferring actions from a reference video.

    • Feature summary: Transfer actions and expressions from a reference video to a character image to generate an animated video.

    • Scenarios: Replicate dances, complex body movements, and facial expressions from film and television performances. A low-cost alternative to motion capture.

    Model effects

    The wan2.2-animate-move model supports two service modes: standard mode wan-std and professional mode wan-pro, which differ in output quality and pricing. For more information, see Wanx-Image-to-Motion.

    Character image

    Reference video

    Output video (standard mode wan-std)

    Output video (professional mode wan-pro)

    move_input_image

    Prerequisites

    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.

    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.

    HTTP

    Video generation uses asynchronous calls. The process has two steps: create a task, then poll for results.

    Step 1: Create a task and get the task ID

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

    Replace WorkspaceId with your actual Workspace ID.

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

    Request parameters

    Image to action

    The following is the Singapore region URL. Replace WorkspaceId with your actual 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-move",
        "input": {
            "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/adsyrp/move_input_image.jpeg",
            "video_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/kaakcn/move_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)

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

    input object (Required)

    The input parameters. Contains the following fields:

    Properties

    image_url string (Required)

    A publicly accessible HTTP or HTTPS URL of the character image. URLs containing non-ASCII characters must be URL-encoded.

    • Format: JPG, JPEG, PNG, BMP, or WEBP

    • Dimensions: Width and height must both be in the range of [200, 4096] pixels. Aspect ratio must be between 1:3 and 3:1.

    • File size: No more than 5 MB

    • Example: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/adsyrp/move_input_image.jpeg

    video_url string (Required)

    A publicly accessible HTTP or HTTPS URL of the reference video. URLs containing non-ASCII characters must be URL-encoded.

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

    • Format: MP4, AVI, or MOV

    • Duration: 2 to 30 seconds

    • Dimensions: Width and height must both be in the range of [200, 2048] pixels. Aspect ratio must be between 1:3 and 3:1.

    • File size: No more than 200 MB

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

    watermark bool (Optional)

    Whether to add a "Generated by Qwen AI" watermark to the bottom-right corner of the output video.

    • false (default)

    • true

    parameters object (Required)

    Properties

    check_image bool (Optional)

    Whether to validate the input image before processing.

    • true (default)

    • false

    mode string (Required)

    The service mode. Valid values:

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

    • wan-pro: Professional mode. Smoother animation and higher quality, with longer processing time and higher cost.

    For more information, see Model effects 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

    The task output.

    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

    Singapore

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

    When calling, replace WorkspaceId with your actual workspace ID.

    China (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 following is the Singapore region URL. Replace WorkspaceId with your actual 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"
    Request 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 successful

    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

    The task output.

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

    message string

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

    usage object

    Output statistics. Only successful results are counted.

    Properties

    video_duration float

    The duration of the generated video, in seconds.

    video_ratio string

    The service mode used for this request. Enumeration values: standard and pro.

    wan-std returns standard. wan-pro returns pro.

    request_id string

    Unique request identifier for tracing and troubleshooting.

    Limitations

    Data validity: Task IDs and video URLs expire after 24 hours. Download videos promptly.

    Content moderation: All inputs and outputs are automatically moderated. Non-compliant content returns an IPInfringementSuspect or DataInspectionFailed error. For more information, see Error codes.

    Billing and rate limiting

    Error codes

    If a model call fails and returns an error message, see Error codes.

    FAQ

    How can I improve output video quality?

    1. Ensure the character occupies a similar portion of the frame 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 materials. Blurry images or low-frame-rate videos reduce output quality.

    How can I convert a temporary video link to a permanent one?

    The link cannot be converted directly. Download the video from your backend and upload it to permanent object storage (such as OSS) to get a permanent URL.

    Example code: Download the 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() # 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)

    Can I play the returned video link directly in a browser?

    Not recommended. The link expires after 24 hours. Download and save the video from your backend, then serve it via a permanent link.

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