The Wanxiang General Image Editing wan2.5 model edits and fuses images from text instructions alone, maintaining subject consistency across edits.
Model overview
Model capabilities | Input example | Output image |
|---|---|---|
Single-image editing | ![]() | ![]() Replace the floral dress with a vintage-style lace gown featuring delicate embroidery on the collar and cuffs. |
Multi-image fusion | ![]() | ![]() 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:
|
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.
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_idto query the result. Thetask_idis 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 parametersRequest headersContent-Typestring (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.Request bodymodelstring (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.
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.object (optional)Controls resolution, prompt rewriting, and watermarking.
Properties size string (optional)Set output image resolution in width×height format. Default: 1280×1280.
Recommended resolutions and aspect ratios
size is omitted, defaults to 1280×1280 pixels with approximate aspect ratio:
integer (optional)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.
boolean (optional)Enables LLM-based prompt rewriting to improve image quality. Adds latency.
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. |
Response parametersoutputobjectTask output information.
Properties task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.
Enumeration values
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. |
Save the task_id to query the task status and result. |
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 parametersRequest headersAuthorizationstring (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.URL path parametertask_idstring (Required)The ID of the task. |
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 |
Response parametersoutputobjectTask output information.
Properties task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.
Enumeration values
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.objectStatistics for the task result.
Properties TOTAL integerThe total number of tasks.SUCCEEDED integerThe number of successful tasks.FAILED integerThe number of failed tasks.stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.objectUsage statistics. Counts only successful results.
Properties image_count integerNumber of images successfully generated. Billing: Cost = Number of images × Unit price.stringUnique request identifier for tracing and troubleshooting. |
Image URLs are valid for only 24 hours and then automatically purged. Save generated images promptly. |
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
- Synchronous call
- Asynchronous call
Request example
This example supports three image input methods: public URL, Base64 encoding, and local file path.Response example
Image URLs expire after 24 hours. Download images promptly.
Java SDK call
- Synchronous call
- Asynchronous call
Request example
This example supports three image input methods: public URL, Base64 encoding, and local file path.Response example
Image URLs expire after 24 hours. Download images promptly.
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:- General Image Editing 2.1: Requires both
promptandfunctionparameters. - General Image Editing 2.5: Only requires
prompt. Describe all edits in text. Thefunctionparameter is no longer supported or needed.



