Skip to main content
Image editing

General image editing - Wan2.1

Edit images with text prompts using the Wan model: outpainting, watermark removal, style transfer, instruction-based editing, inpainting, and restoration.

This document applies only to the China (Beijing) region. You must use an API key from the China (Beijing) region to use the model.

Model overview

Performance showcase

image

Original image

image

Change her hair to red

35779519-bfc3-4b0a-a594-d764fe9a46d83005601501

Add a pair of sunglasses to the girl

image

Convert to French picture book style

See Key features.
Pricing
  • Beijing region
The Beijing region does not offer a free quota. All calls are billable. Confirm before you proceed.

Model

Unit price

Rate limit (shared by Alibaba Cloud account and RAM users)

RPS limit for task submission

Number of concurrent tasks

wanx2.1-imageedit

$0.020070/image

2

2

Getting started

Prerequisites

Obtain an API key and set it as an environment variable. If you use the DashScope SDK to make calls, you also need to install the SDK.

Sample code

Call the image editing API to perform local inpainting.
The SDK encapsulates async processing, so the interface behaves synchronously -- a single request waits for the result. The curl example shows two separate async operations: submit task and query result.
  • Python
  • Java
  • curl
Supports three input methods: public URL, Base64 encoding, or local file path.

Request example

import base64
import os
from http import HTTPStatus
from dashscope import ImageSynthesis
import dashscope
import mimetypes

"""
Environment requirements:
    dashscope python SDK >= 1.23.8
Install/Upgrade SDK:
    pip install -U dashscope
"""

dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

# If the environment variable is not configured, replace the following line with: api_key="sk-xxx"
api_key = os.getenv("DASHSCOPE_API_KEY")

# --- Helper function: for Base64 encoding ---
# Format is data:{MIME_type};base64,{base64_data}
def encode_file(file_path):
    mime_type, _ = mimetypes.guess_type(file_path)
    if not mime_type or not mime_type.startswith("image/"):
        raise ValueError("Unsupported or unrecognized image format")
    with open(file_path, "rb") as image_file:
        encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
    return f"data:{mime_type};base64,{encoded_string}"

"""
Image input methods:
Choose one of the following three methods.

1. Use a public URL - suitable for publicly accessible images.
2. Use a local file - suitable for local development and testing.
3. Use Base64 encoding - suitable for private images or scenarios requiring encrypted transmission.
"""

# [Method 1] Use a public image URL
mask_image_url = "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3_mask.png"
base_image_url = "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3.jpeg"

# [Method 2] Use a local file (supports absolute and relative paths)
# Format requirement: file:// + file path
# Example (absolute path):
# mask_image_url = "file://" + "/path/to/your/mask_image.png"     # Linux/macOS
# base_image_url = "file://" + "C:/path/to/your/base_image.jpeg"  # Windows
# Example (relative path):
# mask_image_url = "file://" + "./mask_image.png"                 # Based on the actual path
# base_image_url = "file://" + "./base_image.jpeg"                # Based on the actual path

# [Method 3] Use a Base64-encoded image
# mask_image_url = encode_file("./mask_image.png")               # Based on the actual path
# base_image_url = encode_file("./base_image.jpeg")              # Based on the actual path

def sample_sync_call_imageedit():
    print('please wait...')
    rsp = ImageSynthesis.call(api_key=api_key,
                              model="wanx2.1-imageedit",
                              function="description_edit_with_mask",
                              prompt="A ceramic rabbit holding a ceramic flower",
                              mask_image_url=mask_image_url,
                              base_image_url=base_image_url,
                              n=1)
    assert rsp.status_code == HTTPStatus.OK

    print('response: %s' % rsp)
    if rsp.status_code == HTTPStatus.OK:
        for result in rsp.output.results:
            print("---------------------------")
            print(result.url)
    else:
        print('sync_call Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))

if __name__ == '__main__':
    sample_sync_call_imageedit()

Response example

The URL is valid for 24 hours. Download the image promptly.
{
    "status_code": 200,
    "request_id": "dc41682c-4e4a-9010-bc6f-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "6e319d88-a07a-420c-9493-xxxxxx",
        "task_status": "SUCCEEDED",
        "results": [
            {
                "url": "https://dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com/xxx.png?xxxxxx"
            }
        ],
        "submit_time": "2025-05-26 14:58:27.320",
        "scheduled_time": "2025-05-26 14:58:27.339",
        "end_time": "2025-05-26 14:58:39.170",
        "task_metrics": {
            "TOTAL": 1,
            "SUCCEEDED": 1,
            "FAILED": 0
        }
    },
    "usage": {
        "image_count": 1
    }
}

Key features

Use the function parameter to specify editing features. All features follow the same calling method from Getting started. Each section below shows the feature-specific input and parameters JSON for curl.
A complete curl request must include top-level fields such as model, input, and parameters, as described in the General image editing API reference.

Global stylization

Applies an artistic style to the entire image — ideal for picture books, social media backgrounds, or concept art.
  • Set function to stylization_all.
  • Supported styles:
    • French picture book style
    • Gold foil art style
  • parameters.strength (0.0–1.0, default: 0.5) controls modification intensity. Lower values preserve more of the original.
  • Prompt format: "Convert to [style]" (e.g., "Convert to French picture book style").

Request example

{
  "input": {
    "function": "stylization_all",
    "prompt": "Convert to French picture book style",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/stylization_all_3.png"
  },
  "parameters": {
    "strength": 0.5
  }
}

Input image

Output image

Prompt: Convert to French picture book style

Prompt: Convert to gold foil art style

image

image

image

image

image

image

Control the image modification degree with strength
The parameters.strength parameter (0.0–1.0, default: 0.5) controls modification intensity: values near 0 preserve the original, values near 1 modify more.
Input prompt: Convert to French picture book style.

Input image

Output image

strength=0.0 (minimum value)

strength=0.5 (default value)

strength=1.0 (maximum value)

image

image

image

image

Local stylization

Applies a style to a specific area — ideal for character customization or ad product highlights.
  • Set function to stylization_local.
  • Supported styles and parameter values:
    • Ice sculpture: ice
    • Cloud: cloud
    • Chinese festive lantern: chinese festive lantern
    • Plank: wooden
    • Blue and white porcelain: blue and white porcelain
    • Fluffy: fluffy
    • Yarn: weaving
    • Balloon: balloon
  • Prompt format: "Change [object] to [style]" (e.g., "Change the house to wooden style").

Request example

{
  "input": {
    "function": "stylization_local",
    "prompt": "Change the house to wooden style",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/stylization_local_1.png"
  }
}

Input image

Output image

image

image

Ice Sculpture

image

Cloud

image

Chinese festive lantern

image

Wooden

image

Blue and white porcelain

image

Fluffy

image
Weaving

image

Balloon

Instruction-based editing

Adds or modifies content via text instructions, without specifying areas — ideal for simple edits like adding accessories or changing hair color.
  • Set function to description_edit.
  • parameters.strength (0.0–1.0, default: 0.5) controls modification intensity. Lower values preserve more of the original.
  • Prompt: Include action verbs like "add" or "modify". For deletions, use Local inpainting instead.

Request example

{
  "input": {
    "function": "description_edit",
    "prompt": "Add a pair of sunglasses to the kitten",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/description_edit_1.jpeg"
  },
  "parameters": {
    "strength": 0.5
  }
}

Capabilities

Input image

Output image

Add an element

image

image

Add a pair of sunglasses to the kitten.

Modify an element

image

image

Change her hair to red.

Control the image modification degree with strength
The parameters.strength parameter (0.0–1.0, default: 0.5) controls modification intensity: values near 0 preserve the original, values near 1 modify more.
Input prompt: Change her clothes to a colorful printed beach shirt.

Input image

Output image

strength=0.0 (minimum value)

strength=0.5 (default value)

strength=1.0 (maximum value)

image

image

image

image

Local inpainting

Edits a masked area: add, modify, or delete content with precise control over clothing, objects, or unwanted elements.
  • Set function to description_edit_with_mask.
  • Mask requirements: Provide mask_image_url where white = edit area, black = retain area.
  • Prompt: Include actions ("add", "modify") and describe post-deletion content for deletions.
    • Add/Modify: Describe the action or final result.
    • Delete: Leave prompt empty for small objects. For large objects, describe the desired background after deletion -- not the deletion action itself.

Request example

{
  "input": {
    "function": "description_edit_with_mask",
    "prompt": "A ceramic rabbit holding a ceramic flower",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_1.jpeg",
    "mask_image_url": "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_1_mask.png"
  }
}
CapabilitiesInput imageInput mask image(White is the area to be edited)Output image
Add an element
image
image
image
Add a hat to the puppy.
Alternatively, describe the expected result: "A puppy wearing a hat".
Modify an element
image
image
image
A ceramic rabbit holding a ceramic flower.
Alternatively, describe the action: "Replace the carrot held by the ceramic rabbit with a ceramic flower".
Delete an element
image
image
image
A transparent glass vase on the table.
Describe the scene after deletion, not the deletion itself — do not write "Delete the brown bear".

Text and watermark removal

Legal risk warningUsing this feature to process copyrighted images (such as removing another brand's watermark) may constitute copyright infringement. Ensure that you have the legal right to use the processed image and assume all related legal responsibilities.
Removes Chinese/English text or watermarks from images — useful for material processing or ad cleanup.
  • Set function to remove_watermark.
  • Prompt: Use general instructions ("Remove the text") or specify type ("Remove English text").

Request example

{
  "input": {
    "function": "remove_watermark",
    "prompt": "Remove the text in the image",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/remove_watermark_1.png"
  }
}

Input image

Output image (Remove the text in the image)

image

image

image

image

Outpainting

Expands the image proportionally in all directions with intelligent fill — ideal for adjusting composition or converting aspect ratios.
  • Set function to expand.
  • Related parameters: top_scale, bottom_scale, left_scale, and right_scale control expansion ratios per direction (e.g., 1.5 = 1.5× size).
  • Prompt tip: Describe the complete scene you expect to see after expansion.

Request example

{
  "input": {
    "function": "expand",
    "prompt": "A family on the lawn in a park",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/expand_1.jpeg"
  },
  "parameters": {
    "top_scale": 1.5,
    "bottom_scale": 1.5,
    "left_scale": 1.5,
    "right_scale": 1.5
  }
}

Input image

Output image

image

image

Image super resolution

Enhances clarity and upscales low-resolution or blurry images — ideal for restoring old photos or preparing HD prints.
  • Set function to super_resolution.
  • parameters.upscale_factor (1–4, default: 1) controls upscaling. Value 1 improves clarity only, without enlarging.
  • Prompt tip: Use "Image super resolution" or describe the image content.

Request example

{
  "input": {
    "function": "super_resolution",
    "prompt": "Image super resolution",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/super_resolution_1.jpeg"
  },
  "parameters": {
    "upscale_factor": 2
  }
}

Input image (blurry image)

Output image (clear image)

image

image

Image colorization

Colorizes black-and-white or grayscale images — useful for historical photos or line art.
  • Set function to colorization.
  • Prompt: Leave empty for automatic colorization, or specify key element colors (e.g., "blue background, yellow leaves").

Example request

{
  "input": {
    "function": "colorization",
    "prompt": "blue background, yellow leaves",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/colorization_1.jpeg"
  }
}

Input image

Output image

image

image

Line art to image

Generates images from line art and text prompts, including doodle-based drawing — useful for architectural concepts and illustrations.
  • Set function to doodle.
  • Related parameter: parameters.is_sketch — controls how the model processes input.
    • false (default): Model extracts line art from RGB input, then generates image (RGB → line art → image).
    • true: Model generates directly from RGB input like doodles (RGB → image).
  • Prompt: Describe expected content -- more detail yields better results.
{
  "input": {
    "function": "doodle",
    "prompt": "A living room in a minimalist Nordic style.",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/doodle_1.png"
  },
  "parameters": {
    "is_sketch": false
  }
}

Request example 2: Doodle-based drawing

{
  "input": {
    "function": "doodle",
    "prompt": "A tree, in a two-dimensional anime style",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/doodle_2.png"
  },
  "parameters": {
    "is_sketch": true
  }
}

Capabilities

Input image

Output image

Line art to image

(is_sketch=false)

image

image

A living room in a minimalist Nordic style.

Doodle-based drawing

(is_sketch=true)

image

image

A tree, in a two-dimensional anime style.

Generate image based on a reference cartoon character

Legal risk warningUsing this feature to process copyrighted cartoon characters may constitute copyright infringement. You must have the legal right to use the referenced character or use your own original character. You must also assume all related legal responsibilities.
  • Set function to control_cartoon_feature.
  • Prompt format: "The cartoon character [action/environment details]..."

Request example

{
  "input": {
    "function": "control_cartoon_feature",
    "prompt": "The cartoon character cautiously peeks out, peering at a brilliant blue gem in the room",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/control_cartoon_feature_1.png"
  }
}

Input image

Output image

image

image

Going live

Best practices

  • Asynchronous polling: Use graduated polling intervals (e.g., every 3s for 30s, then increase) to avoid rate limits.
  • Parameter tuning: Test key parameters like strength in small-scale trials before production to find optimal values.
  • Image storage: Result URLs expire after 24 hours. Download and transfer to persistent storage (e.g., OSS) promptly.

Risk prevention

  • Error handling: Check task_status in query results. If FAILED, record code and message for troubleshooting. Transient errors (e.g., timeouts) may succeed on retry.
  • Content moderation: All input and output is reviewed for compliance. Non-compliant content returns DataInspectionFailed.

API reference

Input and response parameters are documented in the General image editing API reference.

Billing and rate limiting

  • Free quotas and pricing: Wan image editing 2.1.
  • For model rate limiting, see Wanxiang.
  • Billing details:
    • Billed per successfully generated image. Charges apply only when task_status is SUCCEEDED.
    • Failed calls do not incur charges or consume Free quota for new users.

Error codes

If the model call fails and returns an error message, see Error codes for resolution.

FAQ

Q: Why did my task fail (FAILED)? Common causes:
  1. Content moderation failure: Input or output triggered security policy.
  2. Parameter error: Invalid request parameters (e.g., incorrect function name or inaccessible URL).
  3. Internal model error: unexpected processing issue. Check the code and error fields in the query response.
Token Plan
Model Playground
Statistics and Monitoring
Support