Edit images with text prompts using the Wan model: outpainting, watermark removal, style transfer, instruction-based editing, inpainting, and restoration.
Model overview
Performance showcase
![]() Original image | ![]() Change her hair to red | ![]() Add a pair of sunglasses to the girl | ![]() Convert to French picture book style |
See Key features.Pricing
- Beijing region
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
Request example
Response example
The URL is valid for 24 hours. Download the image promptly.
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
functiontostylization_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
Request example
Input image | Output image | |
|---|---|---|
Prompt: Convert to French picture book style | Prompt: Convert to gold foil art style | |
![]() | ![]() | ![]() |
![]() | ![]() | ![]() |
Control the image modification degree with strength
Theparameters.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) | |
![]() | ![]() | ![]() | ![]() |
Local stylization
Applies a style to a specific area — ideal for character customization or ad product highlights.
-
Set
functiontostylization_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
Request example
Input image | Output image | |||
|---|---|---|---|---|
![]() | ![]() Ice Sculpture | ![]() Cloud | ![]() Chinese festive lantern | ![]() Wooden |
![]() Blue and white porcelain | ![]() Fluffy | ![]() | ![]() 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
functiontodescription_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
Request example
Capabilities | Input image | Output image |
|---|---|---|
Add an element | ![]() | ![]() Add a pair of sunglasses to the kitten. |
Modify an element | ![]() | ![]() Change her hair to red. |
Control the image modification degree with strength
Theparameters.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) | |
![]() | ![]() | ![]() | ![]() |
Local inpainting
Edits a masked area: add, modify, or delete content with precise control over clothing, objects, or unwanted elements.
-
Set
functiontodescription_edit_with_mask. -
Mask requirements: Provide
mask_image_urlwhere 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
promptempty for small objects. For large objects, describe the desired background after deletion -- not the deletion action itself.
Request example
Request example
| Capabilities | Input image | Input mask image(White is the area to be edited) | Output image |
|---|---|---|---|
| Add an element | ![]() | ![]() | ![]() Alternatively, describe the expected result: "A puppy wearing a hat". |
| Modify an element | ![]() | ![]() | ![]() Alternatively, describe the action: "Replace the carrot held by the ceramic rabbit with a ceramic flower". |
| Delete an element | ![]() | ![]() | ![]() Describe the scene after deletion, not the deletion itself — do not write "Delete the brown bear". |
Text and watermark removal
- Set
functiontoremove_watermark. - Prompt: Use general instructions ("Remove the text") or specify type ("Remove English text").
Request example
Request example
Input image | Output image (Remove the text in the image) |
|---|---|
![]() | ![]() |
![]() | ![]() |
Outpainting
Expands the image proportionally in all directions with intelligent fill — ideal for adjusting composition or converting aspect ratios.
- Set
functiontoexpand. - Related parameters:
top_scale,bottom_scale,left_scale, andright_scalecontrol 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
Request example
Input image | Output image |
|---|---|
![]() | ![]() |
Image super resolution
Enhances clarity and upscales low-resolution or blurry images — ideal for restoring old photos or preparing HD prints.
- Set
functiontosuper_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
Request example
Input image (blurry image) | Output image (clear image) |
|---|---|
![]() | ![]() |
Image colorization
Colorizes black-and-white or grayscale images — useful for historical photos or line art.
- Set
functiontocolorization. - Prompt: Leave empty for automatic colorization, or specify key element colors (e.g., "blue background, yellow leaves").
Example request
Example request
Input image | Output image |
|---|---|
![]() | ![]() |
Line art to image
Generates images from line art and text prompts, including doodle-based drawing — useful for architectural concepts and illustrations.
-
Set
functiontodoodle. -
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.
Request example 1: Line art to image
Request example 1: Line art to image
Request example 2: Doodle-based drawing
Request example 2: Doodle-based drawing
Capabilities | Input image | Output image |
|---|---|---|
Line art to image (is_sketch=false) | ![]() | ![]() A living room in a minimalist Nordic style. |
Doodle-based drawing (is_sketch=true) | ![]() | ![]() A tree, in a two-dimensional anime style. |
Generate image based on a reference cartoon character
- Set
functiontocontrol_cartoon_feature. - Prompt format: "The cartoon character [action/environment details]..."
Request example
Request example
Input image | Output 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
strengthin 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_statusin query results. IfFAILED, recordcodeandmessagefor 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_statusisSUCCEEDED. - Failed calls do not incur charges or consume Free quota for new users.
- Billed per successfully generated image. Charges apply only when
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:
- Content moderation failure: Input or output triggered security policy.
- Parameter error: Invalid request parameters (e.g., incorrect
functionname or inaccessible URL). - Internal model error: unexpected processing issue. Check the
codeanderrorfields in the query response.





















































