Wan2.1 - general image editing API reference

This topic describes the input and output parameters for the Wan - general image editing model. Important

This document is for the Chinese mainland (Beijing) region only. To use the model, use an API key from the Chinese mainland (Beijing) region.

This model uses simple instructions to perform various image editing tasks (image expansion, watermark removal, style transfer, image inpainting, and image enhancement). The following features are currently supported:

Image stylization: Global and local stylization.
Image content editing: Instruction-based editing (add or modify image content using instructions without specifying a region), inpainting (add, delete, or modify content in a specified area), and text watermark removal (Chinese and English).
Image size and resolution optimization: Image expansion (expand by ratio) and super resolution (enhance to high definition).
Image color processing: Colorization (convert black-and-white or grayscale images to color).
Generation based on a reference image: Sketch-to-image generation (extract a sketch from the input image and then generate an image based on the sketch) and cartoon character reference generation.

Related guide : Image editing - Wan2.1

Model overview

Model	Price	Rate limit (shared by root accounts and RAM users)
Task submission RPS	Concurrent tasks
wanx2.1-imageedit	$0.020070/image	2	2

Model effects

Feature	Input image	Input prompt	Output image
Global stylization	*	Convert to French picture book style
Local stylization		Change the house to a wooden style.
Instruction-based editing		Change her hair to red.
Inpainting	Input image Input mask image (white is the masked area)	A ceramic rabbit holding a ceramic flower.	Output image
Text watermark removal		Remove the text from the image.
Image expansion		A green fairy.
Super resolution	Blurry image	Super resolution.	Clear image
Colorization		Blue background, yellow leaves.
Sketch-to-image generation	Input image	A living room in a minimalist Nordic style.	Extract the sketch from the original image and generate a new image
Cartoon character reference generation	Input reference image (cartoon character)	The cartoon character cautiously peeks out, looking at a sparkling blue gem in the room.	Output image

Prerequisites

Call the Wan - general image editing API using HTTP or the DashScope SDK. Before making a call, get an API key and export the API key as an environment variable.

To call the API using the SDK, install the DashScope SDK. The SDK is available for Python and Java.

HTTP

Image models can take a long time to process. HTTP calls support only asynchronous result retrieval to prevent request timeouts. This requires two requests:

Create a task to obtain a task ID : Sends a request to create a task. Returns a task ID (task_id) in the response.
Query the result by task ID: Uses the task ID from the previous step to query the task status and result. Returns an image URL (valid for 24 hours) if the task succeeds.

Note

After creating a task, it is added to a queue to await scheduling. Call the "Query the result by task ID" API to retrieve the task status and result.

The general image editing model takes about 5 to 15 seconds to process a request. The actual time depends on the number of tasks in the queue and the network conditions. Please wait patiently for the result.

Step 1: Create a task to get task ID

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis

Request parameters

## Global stylization

curl

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \\
--header 'X-DashScope-Async: enable' \\
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \\
--header 'Content-Type: application/json' \\
--data '{
 "model": "wanx2.1-imageedit",
 "input": {
 "function": "stylization_all",
 "prompt": "Convert to French picture book style",
 "base_image_url": "http://wanx.alicdn.com/material/20250318/stylization_all_1.jpeg"
 },
 "parameters": {
 "n": 1
 }
}'

## Pass a local file (Base64)

The following example shows how to pass a Base64-encoded parameter for global stylization. Because the Base64-encoded string is long, download image_base64 and copy its entire content to the base_image_url parameter. For more information about the data format, see Supported formats.

curl

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \\
--header 'X-DashScope-Async: enable' \\
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \\
--header 'Content-Type: application/json' \\
--data '{
 "model": "wanx2.1-imageedit",
 "input": {
 "function": "stylization_all",
 "prompt": "Convert to French picture book style",
 "base_image_url": "data:image/jpeg;base64,/9j/4AAQSkZJR......"
 },
 "parameters": {
 "n": 1
 }
}'

## Local stylization

curl

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \\
--header 'X-DashScope-Async: enable' \\
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \\
--header 'Content-Type: application/json' \\
--data '{
 "model": "wanx2.1-imageedit",
 "input": {
 "function": "stylization_local",
 "prompt": "Change the house to a wooden style.",
 "base_image_url": "http://wanx.alicdn.com/material/20250318/stylization_local_1.png"
 },
 "parameters": {
 "n": 1
 }
}'

## Instruction-based editing

Feature description: Add or modify image content using only instructions, without specifying a region.

curl

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \\
--header 'X-DashScope-Async: enable' \\
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \\
--header 'Content-Type: application/json' \\
--data '{
 "model": "wanx2.1-imageedit",
 "input": {
 "function": "description_edit",
 "prompt": "Change her hair to red.",
 "base_image_url": "http://wanx.alicdn.com/material/20250318/description_edit_2.png"
 },
 "parameters": {
 "n": 1
 }
}'

## Inpainting

Feature description: Add, delete, or modify content in a specified area.

curl

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \\
--header 'X-DashScope-Async: enable' \\
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \\
--header 'Content-Type: application/json' \\
--data '{
 "model": "wanx2.1-imageedit",
 "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_3.jpeg",
 "mask_image_url": "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3_mask.png"
 },
 "parameters": {
 "n": 1
 }
}'

## Text watermark removal

Feature description: Supports removing Chinese and English text watermarks.

curl

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \\
--header 'X-DashScope-Async: enable' \\
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \\
--header 'Content-Type: application/json' \\
--data '{
 "model": "wanx2.1-imageedit",
 "input": {
 "function": "remove_watermark",
 "prompt": "Remove the text from the image",
 "base_image_url": "http://wanx.alicdn.com/material/20250318/remove_watermark_1.png"
 },
 "parameters": {
 "n": 1
 }
}'

## Image expansion

Feature description: Supports expanding the image proportionally up, down, left, and right.

curl

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \\
--header 'X-DashScope-Async: enable' \\
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \\
--header 'Content-Type: application/json' \\
--data '{
 "model": "wanx2.1-imageedit",
 "input": {
 "function": "expand",
 "prompt": "A green fairy",
 "base_image_url": "http://wanx.alicdn.com/material/20250318/expand_2.jpg"
 },
 "parameters": {
 "top_scale": 1.5,
 "bottom_scale": 1.5,
 "left_scale": 1.5,
 "right_scale": 1.5,
 "n": 1
 }
}'

## Super resolution

Feature description: Supports upscaling a blurry image to high definition.

curl

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \\
--header 'X-DashScope-Async: enable' \\
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \\
--header 'Content-Type: application/json' \\
--data '{
 "model": "wanx2.1-imageedit",
 "input": {
 "function": "super_resolution",
 "prompt": "Super resolution.",
 "base_image_url": "http://wanx.alicdn.com/material/20250318/super_resolution_1.jpeg"
 },
 "parameters": {
 "upscale_factor": 2,
 "n": 1
 }
}'

## Colorization

Feature description: Converts a black and white or grayscale image to a color image.

curl

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \\
--header 'X-DashScope-Async: enable' \\
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \\
--header 'Content-Type: application/json' \\
--data '{
 "model": "wanx2.1-imageedit",
 "input": {
 "function": "colorization",
 "prompt": "Blue background, yellow leaves.",
 "base_image_url": "http://wanx.alicdn.com/material/20250318/colorization_1.jpeg"
 },
 "parameters": {
 "n": 1
 }
}'

## Sketch-to-image generation

Feature description: Extracts a sketch from the input image and then generates an image based on the sketch.

curl

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \\
--header 'X-DashScope-Async: enable' \\
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \\
--header 'Content-Type: application/json' \\
--data '{
 "model": "wanx2.1-imageedit",
 "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": {
 "n": 1
 }
}'

## Cartoon character reference generation

Feature description: Supports generating an image based on a reference cartoon character.

curl

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \\
--header 'X-DashScope-Async: enable' \\
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \\
--header 'Content-Type: application/json' \\
--data '{
 "model": "wanx2.1-imageedit",
 "input": {
 "function": "control_cartoon_feature",
 "prompt": "The cartoon character cautiously peeks out, looking at a sparkling blue gem in the room.",
 "base_image_url": "http://wanx.alicdn.com/material/20250318/control_cartoon_feature_1.png"
 },
 "parameters": {
 "n": 1
 }
}'

Request headers

Content-Type <i>string* (Required) The content type of the request. Must be application/json.

Authorization *string* (Required) The authentication credentials using a Model Studio API key. Example: Bearer sk-xxxx

X-DashScope-Async *string* (Required) Enables asynchronous processing. Must be enable as HTTP requests support only asynchronous processing.

**Important ** Returns "current user api does not support synchronous calls" error if not included.

Request body

model *string* (Required) The model name, for example, wanx2.1-imageedit.

input *object* (Required) The basic input information (prompt). Properties

prompt *string* (Required) The prompt used to describe the desired elements and visual features in the generated image. Supports Chinese and English. Maximum length: 800 characters. Each Chinese character or letter counts as one character. Excess characters are automatically truncated. ** Prompts vary for different features. We recommend that you review the corresponding prompting tips for each feature.

<b>function *string* (Required)** The image editing feature. The following features are currently supported:

stylization_all: Global stylization. Two styles are currently supported. Styles and prompting tips
stylization_local: Local stylization. Eight styles are currently supported. Styles and prompting tips
description_edit: Instruction-based editing. Use instructions to edit images. Recommended for simple editing tasks. Prompting tips
description_edit_with_mask: Inpainting. Specify the editing area. Suitable for scenarios requiring precise control over the editing scope. Prompting tips
remove_watermark: Text watermark removal. Prompting tips
expand: Image expansion. Prompting tips
super_resolution: Super resolution. Prompting tips
colorization: Colorization. Prompting tips
doodle: Sketch-to-image generation. Prompting tips
control_cartoon_feature: Cartoon character reference generation. Prompting tips

base_image_url *string* (Required) The URL or Base64-encoded data of the input image. Image requirements:

File format: JPG, JPEG, PNG, BMP, TIFF, or WEBP
Resolution: Width and height must be 512 to 4,096 pixels
File size: Maximum 10 MB
The URL cannot contain Chinese characters Input image formats:
Use a public URL <li>HTTP or HTTPS protocols are supported.
Example: http://wanx.alicdn.com/material/20250318/stylization_all_1.jpeg </li>
Pass Base64-encoded image string <li>Data format: data:{MIME_type};base64,{base64_data}
Example: data:image/jpeg;base64,GDU7MtCZzEbTbmRZ......
The encoded string in the example is incomplete and for demonstration only. For more information, see Supported formats. </li>

mask_image_url *string* (Optional) This parameter is required only when **function** is set to **description_edit_with_mask** (inpainting). Not required for other features. The URL or Base64-encoded data of the mask image. You can pass a publicly accessible URL (HTTP/HTTPS) or a Base64-encoded string. For more information, see Supported formats. Mask image requirements:

Resolution: Must match the resolution of the image specified by base_image_url. Width and height must be 512 to 4,096 pixels
File format: JPG, JPEG, PNG, BMP, TIFF, or WEBP
File size: Maximum 10 MB
The URL cannot contain Chinese characters Mask area color requirements:
White area: Indicates the part to be edited. Must be pure white (RGB value [255,255,255]). Otherwise, it may not be correctly identified.
Black area: Indicates the part that does not need to be changed. Must be pure black (RGB value [0,0,0]). Otherwise, it may not be correctly identified. To get a mask image, use Photoshop or another tool.

parameters *object* (Optional) The image processing parameters. Properties

## General

n *integer* (Optional) The number of images to generate. Value range: 1 to 4. Default: 1.

**seed *integer* **(Optional) The random number seed, used to control the randomness of the content generated by the model. Value range: [0, 2147483647]. If not provided, the algorithm automatically generates a random number as the seed. To keep generated content relatively stable, use the same seed parameter value.

watermark *bool* (Optional) Specifies whether to add a watermark. The watermark is in the lower-right corner of the image and displays "Generated by AI".

false (default)
true

## Global stylization

n *integer* (Optional) The number of images to generate. The value can be an integer from 1 to 4. The default value is 1.

**seed *integer* **(Optional) The random number seed, used to control the randomness of the content generated by the model. The value of the seed parameter can be an integer from \[0, 2147483647\]. If you do not provide this parameter, the algorithm automatically generates a random number as the seed. If you want the generated content to be relatively stable, use the same seed parameter value.

watermark *bool* (Optional) Specifies whether to add a watermark. The watermark is located in the lower-right corner of the image and displays Generated by AI.

false: The default value. No watermark is added.
true: A watermark is added.

strength *float* (Optional) Specify this parameter when **function** is set to **stylization_all** (global stylization). The degree of image modification. Value range: 0.0 to 1.0. Default: 0.5. A value closer to 0 means the result is closer to the original image. A value closer to 1 means greater modification to the original image.

## Instruction-based editing

n *integer* (Optional) The number of images to generate. The value can be an integer from 1 to 4. The default value is 1.

watermark *bool* (Optional) Specifies whether to add a watermark. The watermark is located in the lower-right corner of the image and displays Generated by AI.

false: The default value. No watermark is added.
true: A watermark is added.

strength *float* (Optional) Specify this parameter when **function** is set to **description_edit** (instruction-based editing). The degree of image modification. The value can be a float from 0.0 to 1.0. The default value is 0.5. A value closer to 0 means the result is closer to the original image. A value closer to 1 means a greater degree of modification to the original image.

## Image expansion

n *integer* (Optional) The number of images to generate. The value can be an integer from 1 to 4. The default value is 1.

watermark *bool** *(Optional) Specifies whether to add a watermark. The watermark is located in the lower-right corner of the image and displays Generated by AI.

false: The default value. No watermark is added.
true: A watermark is added.

top_scale *float** *(Optional) Specify this parameter only when **function** is set to **expand** (image expansion). Expand the centered image upward by a specified ratio. Default: 1.0. Value range: 1.0 to 2.0.

bottom_scale *float** *(Optional) Specify this parameter only when **function** is set to **expand** (image expansion). Expand the centered image downward by a specified ratio. Default: 1.0. Value range: 1.0 to 2.0.

left_scale *float** *(Optional) Specify this parameter only when **function** is set to **expand** (image expansion). Expand the centered image to the left by a specified ratio. Default: 1.0. Value range: 1.0 to 2.0.

right_scale *float** *(Optional) Specify this parameter only when **function** is set to **expand** (image expansion). Expand the centered image to the right by a specified ratio. Default: 1.0. Value range: 1.0 to 2.0.

## Super resolution

n *integer* (Optional) The number of images to generate. The value can be an integer from 1 to 4. The default value is 1.

watermark *bool** *(Optional) Specifies whether to add a watermark. The watermark is located in the lower-right corner of the image and displays Generated by AI.

false: The default value. No watermark is added.
true: A watermark is added.

upscale_factor *integer** *(Optional) Specify this parameter only when **function** is set to **super_resolution** (super resolution). The upscaling factor for super resolution, which enhances details while enlarging the image and improves resolution for high-definition processing. Value range: 1 to 4. Default: 1. When upscale_factor is set to 1, the image is processed for high definition without being enlarged.

## Sketch-to-image generation

n *integer* (Optional) The number of images to generate. The value can be an integer from 1 to 4. The default value is 1.

watermark *bool* (Optional) Specifies whether to add a watermark. The watermark is located in the lower-right corner of the image and displays Generated by AI.

false: The default value. No watermark is added.
true: A watermark is added.

is_sketch *bool* (Optional) Specify this parameter only when **function** is set to **doodle** (sketch-to-image generation). Specifies whether the input image is a sketch image.

false (default): The input image is not a sketch. The model first extracts a sketch from the input image and then generates a new image based on the sketch.
true: The input image is a sketch. The model generates an image directly based on the input image. Suitable for doodle-to-painting scenarios.

Response parameters

Successful response

Save the task_id to query the task status and result.

json

{
 "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 to resolve the issue.

json

{
 "code": "InvalidApiKey",
 "message": "No API-key provided.",
 "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

   **output** `*object*` The task output information.

Properties

task_id *string* The ID of the task. Can be used to query the task for up to 24 hours.

task_status *string* The status of the task. Enumeration

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: Task does not exist or status is unknown

request_id *string* Unique identifier for the request. Use for tracing and troubleshooting issues.

code *string* The error code. Returned only when the request fails. See error codes for details.

message *string* Detailed error message. Returned only when the request fails. See error codes for details.

Step 2: Query result by task ID

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

Request parameters

## Query task result

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

curl

curl -X GET https://dashscope.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \\
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Request headers

Authorization *string* (Required) The authentication credentials using a Model Studio API key. Example: Bearer sk-xxxx

Path parameters

task_id *string* (Required) The ID of the task to query.

Response parameters

## Task successful

Task data (task status and image URLs) is retained for only 24 hours and then automatically purged. Save generated images promptly.

json

{
 "request_id": "eeef0935-02e9-9742-bb55-xxxxxx",
 "output": {
 "task_id": "a425c46f-dc0a-400f-879e-xxxxxx",
 "task_status": "SUCCEEDED",
 "submit_time": "2025-02-21 17:56:31.786",
 "scheduled_time": "2025-02-21 17:56:31.821",
 "end_time": "2025-02-21 17:56:42.530",
 "results": \[
 {
 "url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/aaa.png"
 }
 \],
 "task_metrics": {
 "TOTAL": 1,
 "SUCCEEDED": 1,
 "FAILED": 0
 }
 },
 "usage": {
 "image_count": 1
 }
}

## Task failed

When a task fails, task_status is set to FAILED with an error code and message. See error codes to resolve the issue.

json

{
 "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
 "output": {
 "task_id": "86ecf553-d340-4e21-af6e-xxxxxx",
 "task_status": "FAILED",
 "code": "InvalidParameter",
 "message": "xxxxxx",
 "task_metrics": {
 "TOTAL": 4,
 "SUCCEEDED": 0,
 "FAILED": 4
 }
 }
}

## Task partially failed

The model can generate multiple images in a single task. If at least one image generates successfully, the task status is marked as SUCCEEDED and returns the URLs of successful images. For any images that fail to generate, the result includes a failure reason. To resolve these failures, see error codes. Only successfully generated images count toward usage statistics.

json

{
 "request_id": "85eaba38-0185-99d7-8d16-xxxxxx",
 "output": {
 "task_id": "86ecf553-d340-4e21-af6e-xxxxxx",
 "task_status": "SUCCEEDED",
 "results": \[
 {
 "url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/123/a1.png"
 },
 {
 "code": "InternalError.Timeout",
 "message": "An internal timeout error has occured during execution, please try again later or contact service support."
 }
 \],
 "task_metrics": {
 "TOTAL": 2,
 "SUCCEEDED": 1,
 "FAILED": 1
 }
 },
 "usage": {
 "image_count": 1
 }
}

   **output **`*object*`* *The task output information.

Properties

task_id *string* The ID of the task. Can be used to query the task for up to 24 hours.

task_status *string* The status of the task. Enumeration

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: Task does not exist or status is unknown

submit_time *string* The time when the task was submitted. Time is in UTC+8. Format: YYYY-MM-DD HH:mm:ss.SSS.

scheduled_time *string* The time when the task started running. Time is in UTC+8. Format: YYYY-MM-DD HH:mm:ss.SSS.

end_time *string* The time when the task was completed. Time is in UTC+8. Format: YYYY-MM-DD HH:mm:ss.SSS.

results *array object* A list of task results, including image URLs and error messages for partially failed tasks. Data structure

json

{
 "results": \[
 {
 "url": ""
 },
 {
 "code": "",
 "message": ""
 }
 \]
}

task_metrics *object* Statistics about the task results. Properties

TOTAL *integer* Total number of tasks.

SUCCEEDED *integer* Number of successful tasks.

FAILED *integer* Number of failed tasks.

code *string* The error code. Returned only when the request fails. See error codes for details.

message *string* Detailed error message. Returned only when the request fails. See error codes for details.

usage *object* The output information statistics. Only successful results are counted. Properties

image_count *integer* Number of images successfully generated by the model. Billing formula: Fee = (Number of images) × (Unit price).

request_id *string* Unique identifier for the request. Use for tracing and troubleshooting issues.

DashScope SDK

First, ensure you have installed the latest version of the DashScope SDK. Otherwise, a runtime error may occur.

The DashScope SDK currently supports Python and Java.

The parameter names in the SDK are mostly consistent with those in the HTTP API. The parameter structure depends on the SDK encapsulation for different languages. For parameter descriptions, see HTTP.

Video model processing takes a long time, so the service uses an asynchronous approach. The SDK provides a wrapper supporting both synchronous and asynchronous calls.

The general image editing model takes about 5 to 15 seconds to process a request. The actual time depends on the number of tasks in the queue and the network conditions. Please wait patiently for the result.

Python SDK

When using the Python SDK to process image files, input an image using one of the following three methods. Select the method that best fits your scenario.

Public URL: A publicly accessible image URL using HTTP or HTTPS protocol.
Base64 encoding: The Base64-encoded file string in the format data:{MIME_type};base64,{base64_data}.
Local file path: Supports both absolute and relative paths. See the following table for valid file path formats.

System	File path to be provided	Example (absolute path)	Example (relative path)
Linux or macOS	file://	file:///home/images/test.png	file://./images/test.png
Windows operating system	file://D:/images/test.png	file://./images/test.png

Sample code

Note

Before calling the code, ensure you have installed the DashScope Python SDK. We recommend upgrading to the latest version by running pip install -U dashscope. See SDK installation.

Synchronous call

This example shows a synchronous call and supports three image input methods: public URL, Base64 encoding, and local file path.

Request example

HELPCODEESCAPE-python
import base64
import os
from http import HTTPStatus
from dashscope import ImageSynthesis
import mimetypes

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


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.

HELPCODEESCAPE-json
{
    "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
    }
}

Asynchronous call

This example shows only the asynchronous call method.

Request example

HELPCODEESCAPE-python
import os
from http import HTTPStatus
from dashscope import ImageSynthesis

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

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

# 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"


def sample_async_call_imageedit():
    # Asynchronous call, returns a task_id
    rsp = ImageSynthesis.async_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)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print("task_id: %s" % rsp.output.task_id)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))

    # Get asynchronous task information
    status = ImageSynthesis.fetch(task=rsp, api_key=api_key)
    if status.status_code == HTTPStatus.OK:
        print(status.output.task_status)  # check the task status
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (status.status_code, status.code, status.message))

    # Wait for the asynchronous task to finish
    rsp = ImageSynthesis.wait(rsp)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output)
        for result in rsp.output.results:
            print("---------------------------")
            print(result.url)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))


if __name__ == '__main__':
    sample_async_call_imageedit()

Response example

Response example for creating a task

HELPCODEESCAPE-json
{
"status_code": 200,
"request_id": "6dc3bf6c-be18-9268-9c27-xxxxxx",
"code": "",
"message": "",
"output": {
	"task_id": "686391d9-7ecf-4290-a8e9-xxxxxx",
	"task_status": "PENDING",
	"video_url": ""
},
"usage": null
}

Response example for querying a task result

The URL is valid for 24 hours. Download the image promptly.

HELPCODEESCAPE-json
{
    "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?Expires=17xxxxxx"
            }
        ],
        "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
    }
}

Java SDK

When using the Java SDK to process image files, input an image using one of the following three methods. Select the method that best fits your scenario.

Public URL: A publicly accessible image URL using HTTP or HTTPS protocol.
Base64 encoding: The Base64-encoded file string in the format data:{MIME_type};base64,{base64_data}.
Local file path: Only absolute paths are supported. See the following table for correct file path formats.

System	File path to be provided	Example
Linux or macOS	file://	file:///home/images/test.png
Windows operating system	file:///	file:///D:/images/test.png

Sample code

Note

Before calling the code, ensure you have installed the DashScope Java SDK. We recommend upgrading to the latest version. See SDK installation.

Synchronous call

This example shows a synchronous call and supports three image input methods: public URL, Base64 encoding, and local file path.

Request example

HELPCODEESCAPE-java
// Copyright (c) Alibaba, Inc. and its affiliates.

import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.Base64;
import java.util.HashMap;
import java.util.Map;

/**
 * Environment requirements
 *      dashscope java SDK >=2.20.9
 * Update Maven dependency:
 *      https://mvnrepository.com/artifact/com.alibaba/dashscope-sdk-java
 */

public class ImageEditSync {

    // If the environment variable is not configured, replace the following line with: apiKey="sk-xxx"
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    /**
     * Image input methods: Choose one of the following three.
     *
     * 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] Public URL
    static String maskImageUrl = "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3_mask.png";
    static String baseImageUrl = "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3.jpeg";

    //[Method 2] Local file path (file://+absolute path or file:///+absolute path)
    // static String maskImageUrl = "file://" + "/your/path/to/mask_image.png";    // Linux/macOS
    // static String baseImageUrl = "file:///" + "C:/your/path/to/base_image.png";  // Windows

    //[Method 3] Base64 encoding
    // static String maskImageUrl = encodeFile("/your/path/to/mask_image.png");
    // static String baseImageUrl = encodeFile("/your/path/to/base_image.png");


    public static void syncCall() {
        // Set the parameters parameter
        Map&lt;String, Object&gt; parameters = new HashMap<>();
        parameters.put("prompt_extend", true);

        ImageSynthesisParam param =
                ImageSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wanx2.1-imageedit")
                        .function(ImageSynthesis.ImageEditFunction.DESCRIPTION_EDIT_WITH_MASK)
                        .prompt("A ceramic rabbit holding a ceramic flower")
                        .maskImageUrl(maskImageUrl)
                        .baseImageUrl(baseImageUrl)
                        .n(1)
                        .size("1024*1024")
                        .parameters(parameters)
                        .build();

        ImageSynthesis imageSynthesis = new ImageSynthesis();
        ImageSynthesisResult result = null;
        try {
            System.out.println("---sync call, please wait a moment----");
            result = imageSynthesis.call(param);
        } catch (ApiException | NoApiKeyException e){
            throw new RuntimeException(e.getMessage());
        }
        System.out.println(JsonUtils.toJson(result));
    }

    /**
     * Encodes a file into a Base64 string
     * @param filePath The file path
     * @return A Base64 string in the format data:{MIME_type};base64,{base64_data}
     */
    public static String encodeFile(String filePath) {
        Path path = Paths.get(filePath);
        if (!Files.exists(path)) {
            throw new IllegalArgumentException("File does not exist: " + filePath);
        }
        // Detect the MIME type
        String mimeType = null;
        try {
            mimeType = Files.probeContentType(path);
        } catch (IOException e) {
            throw new IllegalArgumentException("Cannot detect file type: " + filePath);
        }
        if (mimeType == null || !mimeType.startsWith("image/")) {
            throw new IllegalArgumentException("Unsupported or unrecognized image format");
        }
        // Read the file content and encode it
        byte[] fileBytes = null;
        try{
            fileBytes = Files.readAllBytes(path);
        } catch (IOException e) {
            throw new IllegalArgumentException("Cannot read file content: " + filePath);
        }

        String encodedString = Base64.getEncoder().encodeToString(fileBytes);
        return "data:" + mimeType + ";base64," + encodedString;
    }

    public static void main(String[] args) {
        syncCall();
    }
}

Response example

The URL is valid for 24 hours. Download the image promptly.

HELPCODEESCAPE-json
{
    "request_id": "bf6c6361-f0fc-949c-9d60-xxxxxx",
    "output": {
        "task_id": "958db858-153b-4c81-b243-xxxxxx",
        "task_status": "SUCCEEDED",
        "results": [
            {
                "url": "https://dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com/xxx.png?xxxxxx"
            }
        ],
        "task_metrics": {
            "TOTAL": 1,
            "SUCCEEDED": 1,
            "FAILED": 0
        }
    },
    "usage": {
        "image_count": 1
    }
}

Asynchronous call

This example shows only the asynchronous call method.

Request example

HELPCODEESCAPE-java
// Copyright (c) Alibaba, Inc. and its affiliates.

import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisListResult;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.task.AsyncTaskListParam;
import com.alibaba.dashscope.utils.JsonUtils;

import java.util.HashMap;
import java.util.Map;

/**
 * Environment requirements
 *      dashscope java SDK >= 2.20.1
 * Update Maven dependency:
 *      https://mvnrepository.com/artifact/com.alibaba/dashscope-sdk-java
 */

public class ImageEditAsync {

    // If the environment variable is not configured, replace the following line with: apiKey="sk-xxx"
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    //[Method 1] Public URL
    static String maskImageUrl = "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3_mask.png";
    static String baseImageUrl = "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3.jpeg";

    public static void asyncCall() {
        // Set the parameters parameter
        Map&lt;String, Object&gt; parameters = new HashMap<>();
        parameters.put("prompt_extend", true);

        ImageSynthesisParam param =
                ImageSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wanx2.1-imageedit")
                        .function(ImageSynthesis.ImageEditFunction.DESCRIPTION_EDIT_WITH_MASK)
                        .prompt("A ceramic rabbit holding a ceramic flower")
                        .maskImageUrl(maskImageUrl)
                        .baseImageUrl(baseImageUrl)
                        .n(1)
                        .size("1024*1024")
                        .parameters(parameters)
                        .build();
        ImageSynthesis imageSynthesis = new ImageSynthesis();
        ImageSynthesisResult result = null;
        try {
            System.out.println("---async call, please wait a moment----");
            result = imageSynthesis.asyncCall(param);
        } catch (ApiException | NoApiKeyException e){
            throw new RuntimeException(e.getMessage());
        }

        System.out.println(JsonUtils.toJson(result));

        String taskId = result.getOutput().getTaskId();

        System.out.println("taskId=" + taskId);


        try {
            result = imageSynthesis.wait(taskId, apiKey);
        } catch (ApiException | NoApiKeyException e){
            throw new RuntimeException(e.getMessage());
        }
        System.out.println(JsonUtils.toJson(result));
        System.out.println(JsonUtils.toJson(result.getOutput()));
    }

    public static void listTask() throws ApiException, NoApiKeyException {
        ImageSynthesis is = new ImageSynthesis();
        AsyncTaskListParam param = AsyncTaskListParam.builder().build();
        param.setApiKey(apiKey);
        ImageSynthesisListResult result = is.list(param);
        System.out.println(result);
    }

    public void fetchTask(String taskId) throws ApiException, NoApiKeyException {
        ImageSynthesis is = new ImageSynthesis();
        // If DASHSCOPE_API_KEY is set as an environment variable, apiKey can be empty.
        ImageSynthesisResult result = is.fetch(taskId, apiKey);
        System.out.println(result.getOutput());
        System.out.println(result.getUsage());
    }


    public static void main(String[] args) {
        asyncCall();
    }
}

Response example

Response example for creating a task

HELPCODEESCAPE-json
{
"request_id": "5dbf9dc5-4f4c-9605-85ea-xxxxxxxx",
"output": {
	"task_id": "7277e20e-aa01-4709-xxxxxxxx",
	"task_status": "PENDING"
}
}

Response example for querying a task result

The URL is valid for 24 hours. Download the image promptly.

HELPCODEESCAPE-json
{
"request_id": "3d740fc4-a968-9c36-b0e7-xxxxxxxx",
"output": {
	"task_id": "34dcf4b0-ed84-441e-91cb-xxxxxxxx",
	"task_status": "SUCCEEDED",
	"results": [
		{
			"url": "https://dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com/xxx.png"
		}
	],
	"submit_time": "2025-02-21 17:56:31.786",
	"scheduled_time": "2025-02-21 17:56:31.821",
	"end_time": "2025-02-21 17:56:42.530",
	"task_metrics": {
		"TOTAL": 1,
		"SUCCEEDED": 1,
		"FAILED": 0
	}
},
"usage": {
	"image_count": 1
}
}

Error codes

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

This API also has specific status codes, as shown in the following table.

HTTP status code	API error code (code)	API error message (message)	Description
400	InvalidParameter	InvalidParameter	The request parameters are invalid.
400	IPInfringementSuspect	Input data is suspected of being involved in IP infringement.	The input data (such as the prompt or image) is suspected of intellectual property infringement. Check the input to ensure it does not contain content that poses an infringement risk.
400	DataInspectionFailed	Input data may contain inappropriate content.	The input data (such as the prompt or image) may contain inappropriate content. Modify the input and try again.
500	InternalError	InternalError	The service is abnormal. Try again to rule out an occasional issue.

Input image formats

Supported formats

Input images support multiple string formats, as shown in the following table.

Invocation method	HTTP	Python SDK	Java SDK
Supported input image methods	- Public URL - Base64 encoding	- Public URL - Base64 encoding - Local file path	- Public URL - Base64 encoding - Local file path

Method 1: Use public URL

Provide a publicly accessible image address. HTTP or HTTPS protocols are supported.
Example: https://xxxx/img.png

Method 2: Use Base64 encoding

Convert a local image file to a Base64 string and concatenate it into the format data:{MIME_type};base64,{base64_data}.

For the conversion code, see Sample code
{MIME_type}: The media type of the image, which must match the file format
{base64_data}: The Base64-encoded string of the image file
MIME type reference:

Image format	MIME Type
JPEG	image/jpeg
JPG	image/jpeg
PNG	image/png
BMP	image/bmp
TIFF	image/tiff
WEBP	image/webp

Example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAABDg......
Note: The Base64 string above is truncated for demonstration. In actual use, pass the complete encoded string.

Method 3: Use local file path

HTTP does not support local file paths. Only the Python SDK and Java SDK support this method.
For local file path rules, see Python SDK and Java SDK.

FAQ

For common questions about image models (model billing, rate limiting rules, and frequent API errors), see FAQ.

Wan2.1 - general image editing API reference ​

Model overview ​

Model effects ​

Prerequisites ​

HTTP ​

Step 1: Create a task to get task ID ​

Request parameters ​

## Global stylization ​

## Pass a local file (Base64) ​

## Local stylization ​

## Instruction-based editing ​

## Inpainting ​

## Text watermark removal ​

## Image expansion ​

## Super resolution ​

## Colorization ​

## Sketch-to-image generation ​

## Cartoon character reference generation ​

Request headers ​

Request body ​

## General ​

## Global stylization ​

## Instruction-based editing ​

## Image expansion ​

## Super resolution ​

## Sketch-to-image generation ​

Response parameters ​

Successful response ​

Error response ​

Step 2: Query result by task ID ​

Request parameters ​

## Query task result ​

Request headers ​

Path parameters ​

Response parameters ​

## Task successful ​

## Task failed ​

## Task partially failed ​

DashScope SDK ​

Python SDK ​

Sample code ​

Synchronous call ​

Request example ​

Response example ​

Asynchronous call ​

Request example ​

Response example ​

Java SDK ​

Sample code ​

Synchronous call ​

Request example ​

Response example ​

Asynchronous call ​

Request example ​

Response example ​

Error codes ​

Input image formats ​

Supported formats ​

FAQ ​

Wan2.1 - general image editing API reference

Model overview

Model effects

Prerequisites

HTTP

Step 1: Create a task to get task ID

Request parameters

## Global stylization

## Pass a local file (Base64)

## Local stylization

## Instruction-based editing

## Inpainting

## Text watermark removal

## Image expansion

## Super resolution

## Colorization

## Sketch-to-image generation

## Cartoon character reference generation

Request headers

Request body

## General

## Global stylization

## Instruction-based editing

## Image expansion

## Super resolution

## Sketch-to-image generation

Response parameters

Successful response

Error response

Step 2: Query result by task ID

Request parameters

## Query task result

Request headers

Path parameters

Response parameters

## Task successful

## Task failed

## Task partially failed

DashScope SDK

Python SDK

Sample code

Synchronous call

Request example

Response example

Asynchronous call

Request example

Response example

Java SDK

Sample code

Synchronous call

Request example

Response example

Asynchronous call

Request example

Response example

Error codes

Input image formats

Supported formats

FAQ