Skip to main content
Wan

Wanxiang – General Image Editing 2.5

The Wanxiang General Image Editing wan2.5 model edits and fuses images from text instructions alone, maintaining subject consistency across edits.

Quick start: User guide
Alibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing) and Singapore regions. The new dedicated domains deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:
  • China (Beijing): from https://dashscope.aliyuncs.com to https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore: from https://dashscope-intl.aliyuncs.com to https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} is your workspace ID, which can be found on the Workspace Details page in the Alibaba Cloud Model Studio console. The existing domain remains fully functional.

Model overview

Model capabilities

Input example

Output image

Single-image editing

damotest2023 Portrait photography outdoors fashionable beauty

a26b226d-f044-4e95-a41c-d1c0d301c30b

Replace the floral dress with a vintage-style lace gown featuring delicate embroidery on the collar and cuffs.

Multi-image fusion

image

p1028883

Place the alarm clock from image 1 beside the vase on the dining table in image 2.

Model name

Model description

Output image specifications

wan2.5-i2i-preview

Wanxiang 2.5 preview

Supports single-image editing and multi-image fusion

Image format: PNG.

Image resolution:

  • Use the parameters.size parameter to specify the resolution of the output image in the format width*height (in pixels).

  • If no resolution is specified, defaults to 1280×1280 total pixels. Approximate aspect ratio rules:

    • For single-image input: matches the aspect ratio of the input image.

    • For multi-image input: matches the aspect ratio of the last input image.

Before calling the API, review the supported models and pricing for your region.

Prerequisites

Before making a call, get an API key and export the API key as an environment variable. To make calls using the SDK, install the DashScope SDK.
The China (Beijing) and Singapore regions have separate API keys and request endpoints. They cannot be used interchangeably. Cross-region calls lead to authentication failures or service errors.

HTTP API call

Image editing takes 1–2 minutes, so the API uses asynchronous invocation: Create task → Poll for result.
Actual runtime varies with queue length and service load.

Step 1: Create a task and get the task ID

Singapore region: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis Beijing region: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis Replace {WorkspaceId} with your actual workspace ID.
  • 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. Instead, use polling to retrieve the result.
  • For guidance for beginners, see Call APIs with Postman or cURL.

Request parameters

Request headers
Content-Type string (Required)The content type of the request. Must be application/json.Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.X-DashScope-Async string (Required)Enables asynchronous processing. HTTP requests support only asynchronous calls. Must be enable.
If this request header is missing, the error "current user api does not support synchronous calls" is returned.
Request body
model string (required)Model name. Supported models and pricing.Example value: wan2.5-i2i-preview.input object (required)Input fields such as the prompt and images.

Properties

prompt string (required)A positive prompt describing elements and visual features to include in the generated image.Supports Chinese and English. Maximum: 2000 characters (each character counts as one); excess is truncated.For prompt-writing tips, see the Text-to-image prompt guide.Example value: A cheerful orange cat sitting down, realistic and detailed.images array of string (required)An array of image URLs.
  • Maximum array length: 3 (up to three images).
  • For multi-image input, order matters. Images follow the array sequence.
Image requirements:
  • Formats: JPEG, JPG, PNG (no alpha channel), BMP, WEBP.
  • Resolution: Width and height must be between 384 and 5000 pixels.
  • File size: Up to 10 MB.
Supported input formats:
  1. Publicly accessible URL
    • Protocols: HTTP or HTTPS.
    • Example value: http://wanx.alicdn.com/material/20250318/stylization_all_1.jpeg.
  2. Base64-encoded image string
    • Format: data:{MIME_type};base64,{base64_data}
    • Example: data:image/jpeg;base64,GDU7MtCZzEbTbmRZ... (example only; use full string).
    • Base64 encoding details: Image input methods.
negative_prompt string (optional)A negative prompt describing elements to exclude from the image.Supports Chinese and English. Maximum: 500 characters; excess is truncated.Example value: low resolution, errors, worst quality, low quality, incomplete, extra fingers, poor proportions.
parameters object (optional)Controls resolution, prompt rewriting, and watermarking.

Properties

size string (optional)Set output image resolution in width×height format. Default: 1280×1280.
  • Resolution range: Total pixels between 768×768 and 1280×1280. Aspect ratio range: 1:4 to 4:1.
  • Example value: 1280×1280.

Recommended resolutions and aspect ratios

If size is omitted, defaults to 1280×1280 pixels with approximate aspect ratio:
  • Single-image input: matches the input image’s aspect ratio.
  • Multi-image input: matches the aspect ratio of the last input image.
n integer (optional)
The value of n directly affects cost. Higher values cost more. Confirm pricing in Model pricing before calling.
Number of images to generate. Range: 1–4. Default: 4. Set to 1 during testing to control costs.watermark boolean (optional)Adds an “AI Generated” watermark to the bottom-right corner.
  • false: default. No watermark.
  • true: Add watermark.
prompt_extend boolean (optional)Enables LLM-based prompt rewriting to improve image quality. Adds latency.
  • true: default. Enable rewriting.
  • false: Disable rewriting.
Example value: true.seed integer (optional)Random number seed. Valid range: [0, 2147483647].If omitted, a random seed is generated. If specified, sequential seeds are assigned to each of the n images based on n. For example, if n=4, seeds are: seed, seed+1, seed+2, seed+3.To improve reproducibility, fix the seed value.Identical seeds do not guarantee identical outputs due to probabilistic generation.
 curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.5-i2i-preview",
    "input": {
        "prompt": "Replace the floral dress with a vintage-style lace gown featuring delicate embroidery on the collar and cuffs.",
        "images": [
            "https://img.alicdn.com/imgextra/i2/O1CN01vHOj4h28jOxUJPwY8_!!6000000007968-49-tps-1344-896.webp"
        ]
    },
    "parameters": {
        "prompt_extend": true,
        "n": 1
    }
}'

Response parameters

output objectTask output information.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: The task does not exist or its status is unknown.
request_id stringUnique request identifier for tracing and troubleshooting.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.
  • Successful response
  • Error 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"
}

Step 2: Query results using the task ID

  • Singapore
  • China (Beijing)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}When calling, replace {WorkspaceId} with your actual workspace ID.
  • Polling recommendation: Image generation is time-consuming. Use a polling mechanism with a reasonable interval, such as 10 seconds.
  • Task state transition: PENDING → RUNNING → SUCCEEDED or FAILED.
  • Result link: After a task succeeds, an image URL valid for 24 hours is returned. Download and save the image to permanent storage, such as OSS.

Request parameters

Request headers
Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.
URL path parameter
task_id string (Required)The ID of the task.
  • Query task result
Replace 86ecf553-d340-4e21-xxxxxxxxx with your actual task_id.
API keys are different for each region. For more information, see Obtain an API key.
If you use a model in the China (Beijing) region, replace base_url with https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx, where {WorkspaceId} is your actual workspace ID.
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Response parameters

output objectTask output information.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: The task does not exist or its status is unknown.
submit_time stringThe time when the task was submitted. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringThe time when the task was executed. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.end_time stringThe time when the task was completed. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.results array of objectList of task results, including image URLs, prompts, and error details for partial failures.

Properties

orig_prompt stringThe original input prompt, corresponding to the request parameter prompt.actual_prompt stringThe optimized prompt used when prompt rewriting is enabled. Not returned when disabled.url stringURL of the generated image.code stringError code for failed images. Returned only for partial failures.message stringError message for failed images. Returned only for partial failures.
task_metrics objectStatistics for the task result.

Properties

TOTAL integerThe total number of tasks.SUCCEEDED integerThe number of successful tasks.FAILED integerThe number of failed tasks.
code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.
usage objectUsage statistics. Counts only successful results.

Properties

image_count integerNumber of images successfully generated. Billing: Cost = Number of images × Unit price.
request_id stringUnique request identifier for tracing and troubleshooting.
  • Task succeeded
  • Task failed
  • Partial failure
  • Task query expired
Image URLs are valid for only 24 hours and then automatically purged. Save generated images promptly.
{
    "request_id": "d1f2a1be-9c58-48af-b43f-xxxxxx",
    "output": {
        "task_id": "7f4836cd-1c47-41b3-b3a4-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-09-23 22:14:10.800",
        "scheduled_time": "2025-09-23 22:14:10.825",
        "end_time": "2025-09-23 22:15:23.456",
        "results": [
            {
                "orig_prompt": "Replace the floral dress with a vintage-style lace gown featuring delicate embroidery on the collar and cuffs.",
                "actual_prompt": "Replace the pink pleated dress with a vintage-style lace gown featuring delicate embroidery on the collar and cuffs. Keep the person’s hairstyle, makeup, and pose unchanged. Match the original image’s soft tones and classical atmosphere.",
                "url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx"
            }
        ],
        "task_metrics": {
            "TOTAL": 1,
            "FAILED": 0,
            "SUCCEEDED": 1
        }
    },
    "usage": {
        "image_count": 1
    }
}

DashScope SDK call

SDK parameters match the HTTP API call, wrapped to suit each language. Image editing takes 30–60 seconds. The SDK wraps the async HTTP flow, supporting both synchronous and asynchronous calls.
Actual runtime varies with queue length and service load.

Python SDK call

Ensure your DashScope Python SDK version is at least1.25.2.Older versions may trigger errors like “url error, please check url!”. Update using Install or upgrade SDK.
  • Synchronous call
  • Asynchronous call
Request example
This example supports three image input methods: public URL, Base64 encoding, and local file path.
import base64
import mimetypes
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath

import dashscope
import requests
from dashscope import ImageSynthesis
import os

# The following URL is for the Singapore region. Replace {WorkspaceId} with your actual workspace ID. URLs differ by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

# If you have not configured an environment variable, replace the next line with: api_key="sk-xxx"
# API keys differ between Singapore and Beijing. Get an API key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")

# --- Input image: Base64 encoding ---
# Base64 format: 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:

1. Public URL — best for publicly accessible images
2. Local file — best for local development and testing
3. Base64 encoding — best for private images or secure transmission
"""

# [Method 1] Public image URL
image_url_1 = "https://img.alicdn.com/imgextra/i3/O1CN0157XGE51l6iL9441yX_!!6000000004770-49-tps-1104-1472.webp"
image_url_2 = "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp"

# [Method 2] Local file (supports absolute and relative paths)
# Format: file:// + file path
# Example (absolute path):
# image_url_1 = "file://" + "/path/to/your/image_1.png"     # Linux/macOS
# image_url_2 = "file://" + "C:/path/to/your/image_2.png"  # Windows
# Example (relative path):
# image_url_1 = "file://" + "./image_1.png"                 # Adjust to your path
# image_url_2 = "file://" + "./image_2.png"                # Adjust to your path

# [Method 3] Base64-encoded image
# image_url_1 = encode_file("./image_1.png")               # Adjust to your path
# image_url_2 = encode_file("./image_2.png")              # Adjust to your path

print('----sync call, please wait a moment----')
rsp = ImageSynthesis.call(api_key=api_key,
                          model="wan2.5-i2i-preview",
                          prompt="Place the alarm clock from image 1 beside the vase on the dining table in image 2.",
                          images=[image_url_1, image_url_2],
                          negative_prompt="",
                          n=1,
                          # size="1280*1280",
                          prompt_extend=True,
                          watermark=False,
                          seed=12345)
print('response: %s' % rsp)
if rsp.status_code == HTTPStatus.OK:
    # Save images to current directory
    for result in rsp.output.results:
        file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
        with open('./%s' % file_name, 'wb+') as f:
            f.write(requests.get(result.url).content)
else:
    print('sync_call Failed, status_code: %s, code: %s, message: %s' %
          (rsp.status_code, rsp.code, rsp.message))
Response example
Image URLs expire after 24 hours. Download images promptly.
{
    "status_code": 200,
    "request_id": "8ad45834-4321-44ed-adf5-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "3aff9ebd-35fc-4339-98a3-xxxxxx",
        "task_status": "SUCCEEDED",
        "results": [
            {
                "url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx",
                "orig_prompt": "Place the alarm clock from image 1 beside the vase on the dining table in image 2.",
                "actual_prompt": "Place the blue alarm clock from image 1 to the right of the vase on the dining table in image 2, near the edge of the tablecloth. Keep the clock facing the camera and parallel to the tabletop, with natural shadow projection."
            }
        ],
        "submit_time": "2025-10-23 16:18:16.009",
        "scheduled_time": "2025-10-23 16:18:16.040",
        "end_time": "2025-10-23 16:19:09.591",
        "task_metrics": {
            "TOTAL": 1,
            "FAILED": 0,
            "SUCCEEDED": 1
        }
    },
    "usage": {
        "image_count": 1
    }
}

Java SDK call

Ensure your DashScope Java SDK version is at least2.22.2.Older versions may trigger errors like “url error, please check url!”. Update using Install or upgrade SDK.
  • Synchronous call
  • Asynchronous call
Request example
This example supports three image input methods: public URL, Base64 encoding, and local file path.
// 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.Constants;
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.*;

public class Image2Image {

    static {
        // The following URL is for the Singapore region. Replace {WorkspaceId} with your actual workspace ID. URLs differ by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
    }

    // If you have not configured an environment variable, replace the next line with: apiKey="sk-xxx"
    // API keys differ between Singapore and Beijing. Get an API key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    /**
     * Image input methods: choose one
     *
     * 1. Public URL — best for publicly accessible images
     * 2. Local file — best for local development and testing
     * 3. Base64 encoding — best for private images or secure transmission
     */

    // [Method 1] Public URL
    static String imageUrl_1 = "https://img.alicdn.com/imgextra/i3/O1CN0157XGE51l6iL9441yX_!!6000000004770-49-tps-1104-1472.webp";
    static String imageUrl_2 = "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp";

    // [Method 2] Local file path (file://+absolute path or file:///+absolute path)
    // static String imageUrl_1 = "file://" + "/your/path/to/image_1.png";    // Linux/macOS
    // static String imageUrl_2 = "file:///" + "C:/your/path/to/image_2.png";  // Windows

    // [Method 3] Base64 encoding
    // static String imageUrl_1 = encodeFile("/your/path/to/image_1.png");
    // static String imageUrl_2 = encodeFile("/your/path/to/image_2.png");

    // List of images to edit
    static List<String> imageUrls = new ArrayList<>();
    static {
        imageUrls.add(imageUrl_1);
        imageUrls.add(imageUrl_2);
    }

    public static void syncCall() {
        // Set parameters
        Map<String, Object> parameters = new HashMap<>();
        parameters.put("prompt_extend", true);
        parameters.put("watermark", false);
        parameters.put("seed", 12345);

        ImageSynthesisParam param =
                ImageSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.5-i2i-preview")
                        .prompt("Place the alarm clock from image 1 beside the vase on the dining table in image 2.")
                        .images(imageUrls)
                        .n(1)
                         //.size("1280*1280")
                        .negativePrompt("")
                        .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));
    }

    /**
     * Encode a file as a Base64 string
     * @param filePath File path
     * @return Base64 string in 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 not found: " + filePath);
        }
        // Detect 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 file and encode
        byte[] fileBytes = null;
        try{
            fileBytes = Files.readAllBytes(path);
        } catch (IOException e) {
            throw new IllegalArgumentException("Cannot read file: " + filePath);
        }

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

    public static void main(String[] args) {
        syncCall();
    }
}
Response example
Image URLs expire after 24 hours. Download images promptly.
{
    "request_id": "d362685b-757f-4eac-bab5-xxxxxx",
    "output": {
        "task_id": "bfa7fc39-3d87-4fa7-b1e6-xxxxxx",
        "task_status": "SUCCEEDED",
        "results": [
            {
                "orig_prompt": "Place the alarm clock from image 1 beside the vase on the dining table in image 2.",
                "actual_prompt": "Place the blue alarm clock from image 1 to the right of the vase on the dining table in image 2, near the edge of the tablecloth. Keep the clock facing the camera and parallel to the vase.",
                "url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx"
            }
        ],
        "task_metrics": {
            "TOTAL": 1,
            "SUCCEEDED": 1,
            "FAILED": 0
        }
    },
    "usage": {
        "image_count": 1
    }
}

Limits

  • Data retention: Both task IDs and image URLs expire after 24 hours. You cannot query or download them after expiration.
  • Content moderation: All prompts, input images, and output images undergo content moderation. Requests containing prohibited content return errors such as “IPInfringementSuspect” or “DataInspectionFailed”. See Error information for details.

Error codes

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

FAQ

Q: I used General Image Editing 2.1 before. Do I need to change my SDK calls to use wan2.5?
A: Yes — the parameter design differs between versions:
Q: How do I view model usage metrics?
A: One hour after a model call completes, go to the Model telemetry (Singapore)Model telemetry (Beijing) page to view metrics such as call count and success rate. For step-by-step guidance, see How to view model call history?.
Text Generation
Video Generation
Audio
Realtime API
Text Embedding
Model Production