Multi-image edit and fuse
Getting started
Prerequisites
Before making a call, get an API key and set it as an environment variable. To use the SDK, install it.
Example code
This example shows multi-image editing. Pass two images in the content array along with a text prompt. The model outputs an edited image.
Input prompt: Place the alarm clock from image 1 next to the vase on the dining table in image 2.
| Input image 1 | Input image 2 | Output image |
|---|---|---|
![]() | ![]() | ![]() |
- Synchronous
- Asynchronous
Ensure that the DashScope Python SDK is version
1.25.15 or later and the DashScope Java SDK is version 2.22.13 or later.Outdated versions may trigger errors. Install or upgrade the SDK.The URL is valid for 24 hours. Download the image promptly.
To use Wan2.6 instead of Wan2.7, change the model parameter from
wan2.7-image-pro to wan2.6-image. The API structure is the same.Wan2.5 examples (legacy)
Wan2.5 examples (legacy)
Ensure that the DashScope Python SDK is version
1.25.2 or later and the DashScope Java SDK is version 2.22.2 or later.Outdated versions may trigger errors, such as "url error, please check url!". Install or upgrade the SDK.- For asynchronous invocations, you must set the
X-DashScope-Asyncheader parameter toenable. - The
task_idfor an asynchronous task is valid for queries for 24 hours. After this period, the task status changes toUNKNOWN.
The URL is valid for 24 hours. Download the image promptly.
- Response example for a task creation request
- Response example for a task query request
The URL is valid for 24 hours. Download the image promptly.
Model availability
For model details and pricing, see Image models.
Input parameters
Input images (images)
images is an array of input images for editing or fusion. The number of images and constraints vary by model:
| Constraint | Wan2.7 | Wan2.6 | Wan2.5 |
|---|---|---|---|
| Max input images | 9 | 4 | 3 |
| Resolution (per side) | 240 - 8,000 px | 240 - 8,000 px | 384 - 5,000 px |
| Max file size | 20 MB | 10 MB | 10 MB |
| Prompt max length | 5,000 chars | 2,000 chars | 2,000 chars |
- Image format: JPEG, JPG, PNG (alpha channels are ignored), BMP, and WEBP are supported.
Image input order
For multi-image input, the order of the images is defined by their sequence in the array. Therefore, the image numbers referenced in the prompt must correspond to the order in the image array. For example, the first image in the array is "image 1", the second is "image 2", or you can use markers such as "[Image 1]" and "[Image 2]".
| Input images | Output images | ||
|---|---|---|---|
![]() | ![]() | ![]() | ![]() |
Image input methods
This model supports the following three methods for passing images:
Method 1: Public URL
Method 1: Public URL
- Provide a publicly accessible image URL that supports the HTTP or HTTPS protocol.
- Example value:
https://xxxx/img.png. - Applicable scenario: The image is already hosted on Object Storage Service (OSS) or a public image hosting service.
Method 2: Base64 encoding
Method 2: Base64 encoding
Convert the image file to a Base64-encoded string and concatenate it in the format:
data:{MIME_type};base64,{base64_data}.-
Example value:
data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAABDg......(This is only a snippet due to length limitations.) When calling the API, you must pass the complete string. -
base64_data: Represents the Base64-encoded string of the image file. -
MIME_type: Represents the media type of the image, which must correspond to the file format.Image format MIME type JPEG image/jpeg JPG image/jpeg PNG image/png BMP image/bmp WEBP image/webp - Applicable scenario: Suitable for private images or scenarios that require encrypted transmission.
Code example: Image Base64 encoding
Code example: Image Base64 encoding
Method 3: Local file path (SDK only)
Method 3: Local file path (SDK only)
-
Python SDK: Supports passing both absolute and relative paths of files. The file path rules are as follows:
System Passed file path Example (absolute path) Example (relative path) Linux or macOS file://<absolute or relative path of the file>file:///home/images/test.pngfile://./images/test.pngWindows file://<absolute or relative path of the file>file://D:/images/test.pngfile://./images/test.png -
Java SDK: Supports passing only the absolute path of files. The file path rules are as follows:
System Passed file path Example (absolute path) Linux or macOS file://<absolute path of the file>file:///home/images/test.pngWindows file:///<absolute path of the file>file:///D:/images/test.png - Applicable scenario: Suitable for quick testing in a local development environment.
Optional parameters
These models provide several optional parameters to adjust the image generation effect:
-
size: Specifies the output image resolution. The format and defaults vary by model: Wan2.7: Defaults to2K. Use preset keywords1K,2K, or4K(recommended), or specify awidth*heightvalue in pixels.4Kis only available for wan2.7-image-pro in text-to-image mode (no image input, sequential mode disabled). Pixel range: 768*768 to 2048*2048 for editing, up to 4096*4096 for text-to-image (pro only). Aspect ratio: 1:8 to 8:1. Wan2.6: Default1K. Use1Kor2K, or specifywidth*height. Pixel range: 768*768 to 2048*2048 (editing mode). Aspect ratio: 1:4 to 4:1. Wan2.5: Defaults to1280*1280. Use thewidth*heightformat only. Total pixels: 589,824 (768*768) to 1,638,400 (1280*1280). Aspect ratio: 1:4 to 4:1.If you do not specifyRecommended resolutions and aspect ratios
- 1280*1280: 1:1
- 1024*1024: 1:1
- 800*1200: 2:3
- 1200*800: 3:2
- 960*1280: 3:4
- 1280*960: 4:3
- 720*1280: 9:16
- 1280*720: 16:9
- 1344*576: 21:9
size, the output preserves an aspect ratio similar to the input image:- For single-image input, the aspect ratio matches the input image.
- For multi-image input, the aspect ratio matches the last image in the array.
-
n: Sets the number of output images. Range: 1-4, default4. For Wan2.7 withenable_sequential=true, the range extends to 1-12 (default12). We recommend setting it to 1 for testing. -
negative_prompt(Wan2.5 and Wan2.6 only): A negative prompt describes content that you do not want to appear in the image, such as "blurry" or "extra fingers". Max 500 characters. -
watermark: Specifies whether to add a watermark. The watermark is located in the lower-right corner of the image, saying "AI-generated". The default isfalse, which means no watermark is added. -
prompt_extend(Wan2.5 and Wan2.6 only): Enables smart prompt rewriting. When enabled, the model enhances your prompt for better results, at the cost of longer processing time. Default:true. -
seed: A random number seed. The value must be within the range of[0, 2147483647]. If you do not provide a seed, the algorithm automatically generates a random number to use. To keep the generated content relatively consistent, use the same seed value for each request.Because model generation is probabilistic, using the same seed does not guarantee that the results will be identical every time.
Wan2.7-only parameters
The following parameters are available only for Wan2.7 models (wan2.7-image-pro, wan2.7-image):
-
thinking_mode: Enables thinking mode for enhanced inference and image quality. Increases the generation time. Defaults totrue. Only effective when the sequential mode is disabled and there is no image input. -
enable_sequential: Enables image set output mode for generating character-consistent multi-image sets. Default:false. When enabled, thenparameter range extends to 1-12 (default12). -
bbox_list: Specifies bounding boxes for interactive editing. Each image can have up to 2 bounding boxes. The format is a list of lists, where each inner list contains[x1, y1, x2, y2]coordinates (top-left and bottom-right corners in absolute pixels). The length of the outer list must match the number of input images. Pass[]for images that do not require region-specific editing. -
color_palette: Applies a custom color theme. Accepts an array of 3-10 color objects, each withhex(color in hex format, e.g.#C2D1E6) andratio(percentage, e.g."25.00%"). The sum of all ratios must equal100.00%. Only available when the sequential mode is disabled.
Output parameters
- Image format: PNG.
- Number of images: 1-4 per request. For Wan2.7 with
enable_sequential=true, up to 12. - Image resolution: You can specify the resolution using the
sizeinput parameter. If this parameter is not specified, see the description of the size parameter above.
All output images will have the same resolution.
Examples
Multi-image fusion
| Input images | Output image |
|---|---|
![]() | ![]() |
![]() | ![]() |
![]() | ![]() |
![]() | ![]() |
Image understanding
Object detection and localization
Detects specified objects in an image and outputs an image with bounding boxes and labels.
| Input image | Output image |
|---|---|
![]() | ![]() |
Instance segmentation
The model generates a unique color region for each individual object in the image, showing its complete outline. For example, the purple area in the output image represents the segmented headphone instance.
| Input image | Output image |
|---|---|
![]() | ![]() |
Subject feature preservation
| Input image | Output image |
|---|---|
![]() | ![]() |
![]() | ![]() |
![]() | ![]() |
Modification and upscaling
| Feature | Input image | Output image |
|---|---|---|
| Modify element | ![]() | ![]() |
| Modify lighting | ![]() | ![]() |
| Upscale subject element | ![]() | ![]() |
| Upscale image details | ![]() | ![]() |
Element extraction
| Input image | Output image |
|---|---|
![]() | ![]() |
Sketch-to-image generation
| Input image | Output image |
|---|---|
![]() | ![]() |
Text generation
| Input image | Output image |
|---|---|
![]() | ![]() |
Watermark removal
| Input image | Output image |
|---|---|
![]() | ![]() |
Outpainting
| Input image | Output image |
|---|---|
![]() | ![]() |
Billing and rate limits
- For free quotas and unit prices, see Models and pricing.
- For rate limits, see Rate limits.
- Billing description:
- Billing is based on the number of successfully generated images. You are charged only when the API returns a
task_statusofSUCCEEDEDand an image is successfully generated. - Failed model calls or processing errors do not incur any fees and do not consume your free quota.
- Billing is based on the number of successfully generated images. You are charged only when the API returns a
Limitations
- Data retention: Task IDs and image URLs expire after 24 hours.
- Content moderation: All inputs and outputs are automatically moderated. Non-compliant content triggers
IPInfringementSuspectorDataInspectionFailederrors — see Error codes.
API reference
- Wan2.7: Wan 2.7 image generation and editing API reference
- Wan2.6: Wan 2.6 image generation and editing API reference
- Wan2.5: Wan 2.5 general image editing API reference
FAQ
Q: What is the difference between Wan2.6 and Wan2.7 for image editing?
Both use the same API pattern (ImageGeneration class with messages). To switch between them, change the model name (wan2.6-image vs wan2.7-image-pro / wan2.7-image). Wan2.7 adds additional parameters like thinking_mode, bbox_list, and enable_sequential.
Q: I was using wan2.5-i2i-preview. If I switch to wan2.7-image-pro, do I need to change how I call the SDK?
Yes. The API design is different:
- wan2.5: Uses the
ImageSynthesisclass withpromptandimagesparameters. - wan2.7: Uses the
ImageGenerationclass with amessagesarray. Images and text are passed together in thecontentarray. See the example code above for details.
- General image editing: Requires both the
promptandfunctionparameters. - General image editing 2.5: Only requires the
promptparameter. Describe all editing operations through text instructions. Thefunctionparameter is no longer supported or required.









































