All Products
Search

This Product

    Alibaba Cloud Model Studio:Wan - general image editing API reference

    Document Center

    Alibaba Cloud Model Studio:Wan - general image editing API reference

    Last Updated:Dec 16, 2025

    The Wan image generation model supports image editing and mixed text-and-image output to meet diverse generation and integration needs.

    Model overview

    Model name

    Model description

    Output image specifications

    wan2.6-image

    Wan 2.6 image

    Supports image editing and mixed text-and-image output

    Image format: PNG.

    For image resolution and dimensions, see the size parameter.

    Note

    Before you make a call, see Model List and Prices for supported models and pricing by region.

    Prerequisites

    Before making a call, obtain an API key and set the API key as an environment variable. To make calls using the SDK, install the DashScope SDK.

    Important

    The Beijing and Singapore regions have separate API keys and request endpoints. Do not use them interchangeably. Cross-region calls cause authentication failures or service errors.

    HTTP invocation

    Image generation tasks take a long time (typically 1 to 2 minutes), so the API uses asynchronous invocation. The entire process involves two core steps: Create Task -> Poll for Result. The steps are as follows:

    The specific time required depends on the number of tasks in the queue and the service execution status. Please be patient when retrieving the results.

    Step 1: Create a task to get a task ID

    Singapore region: POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/image-generation/generation

    Beijing region: POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image-generation/generation

    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. Use polling to retrieve the result.

    Request parameters

    Image-to-image with a reference

    curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/image-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'X-DashScope-Async: enable' \
--data '{
    "model": "wan2.6-image",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "Generate an image of scrambled eggs with tomatoes in the style of this reference picture"
                    },
                    {
                        "image": "https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "negative_prompt": "",
        "prompt_extend": true,
        "watermark": false,
        "n": 2,
        "size": "1280*1280"
    }
}'

    Mixed text-and-image output

    curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/image-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'X-DashScope-Async: enable' \
--data '{
    "model": "wan2.6-image",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "Give me a 3-image tutorial for stir-fried pork with chili peppers"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "n": 1,
        "size": "1280*1280",
        "enable_interleave":true
    }
}'
    Headers

    Content-Type string (Required)

    The content type of the request. Set this parameter to application/json.

    Authorization string (Required)

    The identity authentication credentials for the request. This API uses an Model Studio API key for identity authentication. Example: Bearer sk-xxxx.

    X-DashScope-Async string (Required)

    The asynchronous processing configuration parameter. HTTP requests support only asynchronous processing. You must set this parameter to enable.

    Important

    If this request header is missing, the error message "current user api does not support synchronous calls" is returned.

    Request Body

    model string (Required)

    The model name.

    Example: wan2.6-image.

    input object (Required)

    Basic input information.

    Properties

    messages array (Required)

    An array of request content. Currently, only single-turn conversations are supported. This means you pass one set of role and content parameters. Multi-turn conversations are not supported.

    Properties

    role string (Required)

    The role of the message. This parameter is fixed to user.

    content array (Required)

    An array of message content.

    Properties

    text string (Required)

    The positive prompt. It describes the content, style, and composition of the image you want to generate.

    It supports Chinese and English, with a maximum length of 2000 characters. Each Chinese character, letter, number, or symbol counts as one character. Any excess is automatically truncated.

    Example: Generate an image of scrambled eggs with tomatoes in the style of this reference picture.

    Note: Only one text input is supported. An error is reported if no text or multiple texts are provided.

    image string (Optional)

    An array of input image URLs.

    The length of the array depends on the parameters.enable_interleave parameter.

    • When enable_interleave=true, the array length is 0 to 1. You can choose not to pass an image.

    • When enable_interleave=false, the array length is 1 to 3. You must pass at least one image.

    • For multi-image input, the order of images is defined by their order in the array.

    Image limits:

    • Image format: JPEG, JPG, PNG (alpha channel not supported), BMP, WEBP.

    • Image resolution: The width and height of the image must both be in the range of [384, 5000] pixels.

    • File size: Does not exceed 10 MB.

    Supported input formats:

    1. Publicly accessible URL

      • Supports HTTP or HTTPS protocol.

      • Example: http://wanx.alicdn.com/material/xxx.jpeg.

    2. A string containing a Base64-encoded image

      • Format: data:{MIME_type};base64,{base64_data}

      • Example: data:image/jpeg;base64,GDU7MtCZzEbTbmRZ... (for illustration only; the complete string must be provided)

      • For the Base64 encoding specifications, see Image input methods.

    parameters object (Optional)

    Image editing parameters.

    Properties

    negative_prompt string (Optional)

    A negative prompt that describes the content that you do not want to see in the image. It can be used to constrain the image.

    The maximum length is 500 characters. This parameter supports both Chinese and English. Excess characters are automatically truncated.

    Example: low resolution, error, worst quality, low quality, deformed, extra fingers, bad proportions.

    size string (Optional)

    The resolution of the output image, in the format of width*height.

    • wan2.6-image: The default value is 1280*1280. The total pixels must be between 768×768 and 1280×1280, and the aspect ratio must be between 1:4 and 4:1. For example, 768×2700 is a valid resolution.

    Example: 1280*1280.

    Recommended resolutions for common aspect ratios

    • 1:1: 1280×1280 or 1024×1024

    • 2:3: 800×1200

    • 3:2: 1200×800

    • 3:4: 960×1280

    • 4:3: 1280×960

    • 9:16: 720×1280

    • 16:9: 1280×720

    • 21:9: 1344×576

    Rules for output image dimensions

    Method 1: Specify the size parameter: The output image is generated strictly according to the width and height specified by size.

    Method 2: Do not specify size: The output image dimensions are determined by both the maximum total pixels and the aspect ratio rules. The system processes the image based on the total pixels and aspect ratio rules before outputting it.

    • Total pixel rule: Controlled by enable_interleave.

      • When enable_interleave=true:

        • If the total pixels of the input image are ≤ 1280×1280, the output has the same total pixels as the input.

        • If the total pixels of the input image are > 1280×1280, the output total pixels are fixed at 1280×1280.

      • When enable_interleave=false: The output total pixels are fixed at 1280×1280.

    • Aspect ratio rule (approximate):

      • Single-image input: The output aspect ratio is the same as the input image.

      • Multi-image input: The output aspect ratio is the same as the last input image.

    Example: When enable_interleave=true and a 720×720 image is input, the output image is 720×720, matching the input aspect ratio.

    max_images integer (Optional)

    This parameter takes effect only in mixed text-and-image generation mode (when enable_interleave=true).
    It specifies the maximum number of images the model can generate. The value ranges from 1 to 5, with a default of 5.

    Note: This parameter sets an upper limit. The actual number of generated images may be less than the set value (for example, if set to 5, only 3 images might be returned), depending on the model inference result.

    enable_interleave bool (Optional)

    Controls the image generation mode:

    • false: The default value. This indicates image edit mode (supports multi-image input and subject consistency generation).

    • true: Enables mixed text-and-image output mode (supports passing one image or no image).

    prompt_extend bool (Optional)

    Specifies whether to enable intelligent prompt rewriting. When enabled, a large language model optimizes the positive prompt. This significantly improves results for simple or less descriptive prompts but adds 3 to 4 seconds to the processing time.

    Effective condition: This feature takes effect only when enable_interleave=false. It does not apply to mixed text-and-image mode.

    Optional values:

    • true: The default value. Enables intelligent rewriting.

    • false: Disables intelligent rewriting.

    n integer (Optional)

    Important

    The value of n directly affects the cost. Cost = Unit Price × Number of Images.

    The number of images to generate. The value is set dynamically based on the mode:

    • When enable_interleave=true, the value is fixed at 1.

    • When enable_interleave=false, the value ranges from 1 to 4, with a default of 4.

    During testing, we recommend setting this to 1 for low-cost verification.

    watermark bool (Optional)

    Specifies whether to add a watermark. The watermark is placed in the bottom-right corner of the image with the fixed text "AI Generated".

    • false: The default value. Does not add a watermark.

    • true: Adds a watermark.

    seed integer (Optional)

    The random number seed is used to control the randomness of the content generated by the model, with a value range of [0, 2147483647].

    Using the same seed value produces more consistent results. If you do not provide a seed, the algorithm uses a random number.

    Note: The model generation process is probabilistic. Even with the same seed, the results are not guaranteed to be identical for every call.

    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

    The task creation failed. For more information, see Error messages to resolve the issue.

    {
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"fb53c4ec-1c12-4fc4-a580-xxxxxx"
}

    output object

    The task output information.

    Properties

    task_id string

    The task ID. The query is valid for 24 hours.

    task_status string

    The task status.

    Enumeration

    • PENDING

    • RUNNING

    • SUCCEEDED

    • FAILED

    • CANCELED

    • UNKNOWN: The task does not exist or its status cannot be determined.

    request_id string

    The unique request ID. You can use this ID to trace and troubleshoot issues.

    code string

    The error code for a failed request. This parameter is not returned if the request is successful. For more information, see Error messages.

    message string

    The detailed information about a failed request. This parameter is not returned if the request is successful. For more information, see Error messages.

    Step 2: Query the result by task ID

    Singapore region: GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}

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

    Note

    • Polling suggestion: Image generation takes several minutes. Use a polling mechanism and set a reasonable query interval, such as 10 seconds, to retrieve the result.

    • Task status transition: PENDING → RUNNING → SUCCEEDED or FAILED.

    • Result link: After the task is successful, an image link is returned. The link is valid for 24 hours. After you retrieve the link, immediately download and save the image to a permanent storage service, such as Object Storage Service.

    Request parameters

    Query task result

    Replace 86ecf553-d340-4e21-xxxxxxxxx with the actual task ID.

    The API keys for the Singapore and Beijing regions are different. Create an API key.
    The following `base_url` is for the Singapore region. For models in the Beijing region, replace the `base_url` with `https://dashscope.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx`.
    curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
    Headers

    Authorization string (Required)

    The identity authentication credentials for the request. This API uses an Model Studio API key for identity authentication. Example: Bearer sk-xxxx.

    URL path parameters

    task_id string (Required)

    The task ID.

    Response parameters

    Task succeeded

    Task data, such as the task status and image URLs, is retained for only 24 hours and is automatically purged after this period. You must save the generated images promptly.

    {
    "request_id": "43d9e959-25bc-4dc7-9888-xxxxxx",
    "output": {
        "task_id": "858cad55-4bdc-4ba3-ae6c-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-12-16 04:21:02.275",
        "scheduled_time": "2025-12-16 04:21:02.304",
        "end_time": "2025-12-16 04:24:46.658",
        "finished": true,
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/1xxx.png?Expires=xxx",
                            "type": "image"
                        }
                    ]
                }
            },
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/1xxx.png?Expires=xxx",
                            "type": "image"
                        }
                    ]
                }
            }
        ]
    },
    "usage": {
        "size": "1280*1280",
        "total_tokens": 0,
        "image_count": 2,
        "output_tokens": 0,
        "input_tokens": 0
    }
}

    Task error

    If task execution fails, the returned information includes code and message fields that specify the cause of the error. See Error messages for solutions.

    {
    "request_id": "a4d78a5f-655f-9639-8437-xxxxxx",
    "code": "InvalidParameter",
    "message": "num_images_per_prompt must be 1"
}

    output object

    The task output information.

    Properties

    task_id string

    The task ID. The query is valid for 24 hours.

    task_status string

    The task status.

    Enumeration

    • PENDING

    • RUNNING

    • SUCCEEDED

    • FAILED

    • CANCELED

    • UNKNOWN: The task does not exist or its status cannot be determined.

    Status transitions during polling:

    • PENDING → RUNNING → SUCCEEDED or FAILED.

    • The status of the first query is usually PENDING or RUNNING.

    • If the status changes to SUCCEEDED, the response contains the generated image URL.

    • If the status is FAILED, check the error message and retry.

    submit_time string

    The time when the task was submitted. The time is in the UTC+8 time zone. The format is YYYY-MM-DD HH:mm:ss.SSS.

    scheduled_time string

    The time when the task started running. The time is in the UTC+8 time zone. The format is YYYY-MM-DD HH:mm:ss.SSS.

    end_time string

    The time when the task was completed. The time is in the UTC+8 time zone. The format is YYYY-MM-DD HH:mm:ss.SSS.

    finished bool

    A flag indicating if the request has finished.

    • true: The request has finished.

    • false: The request has not finished.

    choices array

    The output content generated by the model. This array contains only one element.

    Properties

    finish_reason string

    The reason the task stopped. A value of stop indicates a natural stop.

    messages object

    The message returned by the model.

    Properties

    role string

    The role of the message, fixed to assistant.

    content array

    Properties

    image string

    The URL of the generated image. The image format is PNG. The link is valid for 24 hours. Download and save the image promptly.

    type string

    The type of the output. The enumerated values are image and text.

    usage object

    Statistics for the output. Only successful results are counted.

    Properties

    image_count integer

    The number of images generated by the model. Currently fixed at 1.

    size string

    The resolution of the generated image. Example: 1328*1328.

    input_tokens integer

    The input tokens. Text-to-image is billed per image, so this value is currently fixed at 0.

    output_tokens integer

    The output tokens. Text-to-image is billed per image, so this value is currently fixed at 0.

    total_tokens integer

    The total tokens. Text-to-image is billed per image, so this value is currently fixed at 0.

    request_id string

    The unique request ID. You can use this ID to trace and troubleshoot issues.

    code string

    The error code for a failed request. This parameter is not returned if the request is successful. For more information, see Error messages.

    message string

    The detailed information about a failed request. This parameter is not returned if the request is successful. For more information, see Error messages.

    Limits

    • Data retention: The task_id and image URL are retained for only 24 hours. After they expire, they cannot be queried or downloaded.

    • Content moderation: Both the input prompt and the output image undergo content moderation. Requests that contain violating content return an "IPInfringementSuspect" or "DataInspectionFailed" error. For more information, see Error messages.

    • Network access configuration: Image links are stored in Alibaba Cloud OSS. If your business system cannot access external OSS links due to security policies, add the following OSS domain names to your 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 throttling

    • For the model's free quota and billing rate, see Model List.

    • For more information about model rate limiting, see Wan.

    • Billing details:

      • Billing is based on the number of successfully generated images. You are charged only when the query result API returns a task_status of SUCCEEDED and an image is successfully generated.

      • Failed model calls or processing errors do not incur any charges or consume the free quota.

    Error codes

    If a call fails, see Error messages for troubleshooting.

    FAQ

    Q: How do I view model usage?

    A: One hour after a model is called, you can view metrics such as the number of calls and the success rate on the Model Monitoring (Singapore)Model Monitoring (Beijing) page. How do I view model call records?