Image editing - Wan2.5 to 2.7

Updated at:

Edit images with text instructions using Wan models. Supports multi-image input/output, image fusion, subject preservation, and object detection.

Getting started

Generate an edited image from two input images and a text prompt with wan2.7-image-pro.

Prompt: Spray the graffiti from image 2 onto the car in image 1

Input image 1

Input image 2

Output image (wan2.7-image-pro)

umbrella

input2

1774509357_902b1408-2026-03-30-16-12-31

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.

Synchronous call

ImportantEnsure that the DashScope Python SDK version is2.0.1or later, and the DashScope Java SDK version is2.22.13or later.

Python

Request example

import os
import base64
import mimetypes
import requests
import dashscope
from dashscope.aigc.image_generation import ImageGeneration, Message

# The following is the configuration for the China (Beijing) region. Replace {WorkspaceId} with your Bailian workspace ID when calling. The region value varies by region.
# If no environment variable is configured, replace the following line with your Model Studio API key: api_key="sk-xxx"
# The API key is region-specific. To obtain an API key: https://help.aliyun.com/en/model-studio/get-api-key
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# --- Base64 encoding function ---
# The 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:
The following are three image input methods. Choose one.
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 that require encrypted transmission.
"""
# [Method 1] Use a public image URL
image_1 = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/pjeqdf/car.webp"
image_2 = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/xsunlm/paint.webp"

# [Method 2] Use a local file (supports absolute and relative paths)
# image_1 = "file:///path/to/your/car.png"
# image_2 = "file:///path/to/your/paint.png"

# [Method 3] Use a Base64-encoded image
# image_1 = encode_file("/path/to/your/car.png")
# image_2 = encode_file("/path/to/your/paint.png")

print("----sync call, please wait a moment----")
# generate is a one-step call (submits the task and waits for completion) that returns the completed Job.
# The wan2.7-image series is not yet supported in SDK 2.0 (routing gap); keep the 1.x ImageGeneration call
message = Message(
    role="user",
    content=[
        {"text": "Spray-paint the graffiti from image 2 onto the car in image 1"},
        {"image": image_1},
        {"image": image_2},
    ],
)
print("----sync call, please wait a moment----")
rsp = ImageGeneration.call(
    model="wan2.7-image-pro",
    api_key=api_key,
    messages=[message],
    watermark=False,
    n=1,
    size="2K",  # wan2.7-image-pro supports 4K resolution only for text-to-image generation. Image editing and composite image generation support a maximum resolution of 2K.
)

# Fetch the URL of the generated image and save the image to a local file.
for i, image_url in enumerate(job.image_urls):
    file_name = f"output_{i}.png"
    # The URL of the generated image is valid for 24 hours. Download the image promptly.
    with open(file_name, "wb") as f:
        f.write(requests.get(image_url).content)
    print(f"Image saved to {file_name}")

Response example

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

{
    "request_id": "81d868c6-6ce1-92d8-a90d-d2ee71xxxxxx",
    "task_id": "127ec645-118f-4884-955d-0eba8dxxxxxx",
    "status": "SUCCEEDED",
    "results": [
        {
            "url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxxx.png?Expires=xxxxxx"
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 1,
        "FAILED": 0
    },
    "usage": {
        "image_count": 1,
        "size": "2985*1405"
    }
}

Java

Request example

import com.alibaba.dashscope.aigc.imagegeneration.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;

import java.io.IOException;
import java.io.InputStream;
import java.net.URL;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.nio.file.StandardCopyOption;
import java.util.Arrays;
import java.util.Base64;
import java.util.Collections;
import java.util.List;
import java.util.Map;

/**
 * wan2.7-image-pro Image Editing - Synchronous Call Example
 */
public class Main {

    static {
        // The following URL is for the China (Beijing) region. Replace {WorkspaceId} with your Bailian workspace ID. The base_url varies by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
    }

    // If you have not configured the environment variable, replace the following line with your Model Studio API key: apiKey="sk-xxx"
    // The API key varies by region. To obtain an API key, visit: https://help.aliyun.com/en/model-studio/get-api-key
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    // --- Base64 Encoding Function ---
    // The Base64 encoding format is data:{MIME_type};base64,{base64_data}
    public static String encodeFile(String filePath) throws IOException {
        byte[] fileContent = Files.readAllBytes(Paths.get(filePath));
        String base64String = Base64.getEncoder().encodeToString(fileContent);
        String mimeType = Files.probeContentType(Paths.get(filePath));
        return "data:" + mimeType + ";base64," + base64String;
    }

    public static void basicCall() throws ApiException, NoApiKeyException, UploadFileException, IOException {
        /*
         * Description of image input methods:
         * The following are three image input methods. You can choose one of them.
         * 1. Use a public URL - Suitable for images that are already publicly accessible.
         * 2. Use a local file - Suitable for local development and testing.
         * 3. Use Base64 encoding - Suitable for private images or scenarios that require encrypted transmission.
         */
        // [Method 1] Use a public image URL
        String image1 = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/pjeqdf/car.webp";
        String image2 = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/xsunlm/paint.webp";

        // [Method 2] Use a local file (supports absolute and relative paths)
        // Required format: file:// + file path
        // String image1 = "file:///path/to/your/car.png";
        // String image2 = "file:///path/to/your/paint.png";

        // [Method 3] Use a Base64-encoded image
        // String image1 = encodeFile("/path/to/your/car.png");
        // String image2 = encodeFile("/path/to/your/paint.png");

        // Build a multi-image input message
        ImageGenerationMessage message = ImageGenerationMessage.builder()
                .role("user")
                .content(Arrays.asList(
                        // Multi-image input is supported. You can provide multiple reference images.
                        Collections.singletonMap("text", "Spray-paint the graffiti from image 2 onto the car in image 1."),
                        Collections.singletonMap("image", image1),
                        Collections.singletonMap("image", image2)
                )).build();

        ImageGenerationParam param = ImageGenerationParam.builder()
                .apiKey(apiKey)
                .model("wan2.7-image-pro")
                .messages(Collections.singletonList(message))
                .n(1)
                .size("2K") // For wan2.7-image-pro, only text-to-image generation scenarios support 4K resolution. Image editing and composite image generation support a maximum resolution of 2K.
                .build();

        ImageGeneration imageGeneration = new ImageGeneration();
        ImageGenerationResult result = null;
        try {
            System.out.println("---sync call for image editing, please wait a moment----");
            result = imageGeneration.call(param);
        } catch (ApiException | NoApiKeyException | UploadFileException e) {
            throw new RuntimeException(e.getMessage());
        }
        // Extract the result image URL and save it to a local file.
        for (int i = 0; i < result.getOutput().getChoices().size(); i++) {
            List<Map<String, Object>> contents = result.getOutput().getChoices().get(i)
                    .getMessage().getContent();
            for (int j = 0; j < contents.size(); j++) {
                if ("image".equals(contents.get(j).get("type"))) {
                    String imageUrl = (String) contents.get(j).get("image");
                    String fileName = "output_" + i + "_" + j + ".png";
                    // The result URL is valid for 24 hours. Please download the image promptly.
                    try (InputStream in = new URL(imageUrl).openStream()) {
                        Files.copy(in, Paths.get(fileName), StandardCopyOption.REPLACE_EXISTING);
                    }
                    System.out.println("Image saved to " + fileName);
                }
            }
        }
    }

    public static void main(String[] args) throws ApiException, NoApiKeyException, UploadFileException, IOException {
        basicCall();
    }
}

Response example

The URL is valid for 24 hours. Save it promptly.

{
    "requestId": "1bf6173a-e8de-9f75-94d3-5e618f875xxx",
    "usage": {
        "input_tokens": 18790,
        "output_tokens": 2,
        "total_tokens": 18792,
        "image_count": 1,
        "size": "2985*1405"
    },
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxxx.png?Expires=xxxxxx",
                            "type": "image"
                        }
                    ]
                }
            }
        ],
        "finished": true
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

curl

Request example
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
    "model": "wan2.7-image-pro",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/pjeqdf/car.webp"},
                    {"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/xsunlm/paint.webp"},
                    {"text": "Spray-paint the graffiti from image 2 onto the car in image 1."}
                ]
            }
        ]
    },
    "parameters": {
        "size": "2K",
        "n": 1,
        "watermark": false
    }
}'
Response example
{
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "content": [
                        {
                            "image": "https://dashscope-xxx.oss-xxx.aliyuncs.com/xxx.png?Expires=xxx",
                            "type": "image"
                        }
                    ],
                    "role": "assistant"
                }
            }
        ],
        "finished": true
    },
    "usage": {
        "image_count": 1,
        "input_tokens": 10867,
        "output_tokens": 2,
        "size": "1488*704",
        "total_tokens": 10869
    },
    "request_id": "71dfc3c6-f796-9972-97e4-bc4efc4faxxx"
}

Asynchronous call

ImportantEnsure that the DashScope Python SDK version is2.0.1or later, and the DashScope Java SDK version is2.22.13or later.

Python

Request example

import os
import base64
import mimetypes
import requests
import dashscope

# The following is the configuration for the China (Beijing) region. Replace {WorkspaceId} with your Bailian workspace ID when calling. The region value varies by region.
# If no environment variable is configured, replace the following line with your Model Studio API key: api_key="sk-xxx"
# The API key is region-specific. To obtain an API key: https://help.aliyun.com/en/model-studio/get-api-key
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# --- Base64 encoding function ---
# The 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:
The following are three image input methods. Choose one.
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 that require encrypted transmission.
"""
# [Method 1] Use a public image URL
image_1 = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/pjeqdf/car.webp"
image_2 = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/xsunlm/paint.webp"

# [Method 2] Use a local file (supports absolute and relative paths)
# image_1 = "file:///path/to/your/car.png"
# image_2 = "file:///path/to/your/paint.png"

# [Method 3] Use a Base64-encoded image
# image_1 = encode_file("/path/to/your/car.png")
# image_2 = encode_file("/path/to/your/paint.png")

# Create an asynchronous task
def create_async_task():
    print("Creating async task...")
    job = client.images.jobs.create(
        model="wan2.7-image-pro",
        prompt="Spray the graffiti from image 2 onto the car in image 1",
        extra_input={'images': [image_1, image_2]},
        watermark=False,
        n=1,
        size="2K",  # wan2.7-image-pro supports 4K resolution only for text-to-image generation. Image editing and composite image generation support a maximum resolution of 2K.
    )

    print("Task created successfully:", job.task_id, job.status)
    return job

# Wait for the task to complete (exponential backoff polling, default total budget of 24 hours; a FAILED task raises DashScopeError)
def wait_for_completion(job):
    print("Waiting for task completion...")
    done = client.images.jobs.wait(job)

    print("Task succeeded!")
    # Fetch the URL of the generated image and save the image to a local file.
    for i, image_url in enumerate(done.image_urls):
        file_name = f"output_{i}.png"
        # The URL of the generated image is valid for 24 hours. Download the image promptly.
        with open(file_name, "wb") as f:
            f.write(requests.get(image_url).content)
        print(f"Image saved to {file_name}")

# Fetch asynchronous task information
def fetch_task_status(task_id):
    print("Fetching task status...")
    snapshot = client.images.jobs.fetch(task_id)

    print("Task status:", snapshot.status)

# Cancel the asynchronous task. Only tasks in the PENDING state can be canceled.
def cancel_task(task_id):
    print("Canceling task...")
    client.images.jobs.cancel(task_id)

# Main execution flow
if __name__ == "__main__":
    job = create_async_task()
    wait_for_completion(job)

Response example

  1. Response example for creating a task
{
    "request_id": "4fb3050f-de57-4a24-84ff-e37ee5xxxxxx",
    "task_id": "127ec645-118f-4884-955d-0eba8dxxxxxx",
    "status": "PENDING"
}
  1. Response example for querying a task result

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

{
    "request_id": "3b99aae5-d26f-9059-8dd0-ee9ca4804xxx",
    "task_id": "127ec645-118f-4884-955d-0eba8dxxxxxx",
    "status": "SUCCEEDED",
    "results": [
        {
            "url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxxx.png?Expires=xxxxxx"
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 1,
        "FAILED": 0
    },
    "usage": {
        "image_count": 1,
        "size": "2985*1405"
    }
}

Java

Request example

import com.alibaba.dashscope.aigc.imagegeneration.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;

import java.io.IOException;
import java.io.InputStream;
import java.net.URL;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.nio.file.StandardCopyOption;
import java.util.Arrays;
import java.util.Base64;
import java.util.Collections;
import java.util.List;
import java.util.Map;

/**
 * wan2.7-image-pro image editing - Asynchronous invocation example
 */
public class Main {

    static {
        // The following URL is for the China (Beijing) region. Replace {WorkspaceId} with your Bailian workspace ID. The base_url varies by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
    }

    // If you have not configured environment variables, replace the following line with your Model Studio API key: apiKey="sk-xxx"
    // API keys are region-specific. To obtain an API key, visit: https://help.aliyun.com/en/model-studio/get-api-key
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    // --- Base64 encoding function ---
    // The Base64 encoding format is data:{MIME_type};base64,{base64_data}
    public static String encodeFile(String filePath) throws IOException {
        byte[] fileContent = Files.readAllBytes(Paths.get(filePath));
        String base64String = Base64.getEncoder().encodeToString(fileContent);
        String mimeType = Files.probeContentType(Paths.get(filePath));
        return "data:" + mimeType + ";base64," + base64String;
    }

    public static void asyncCall() throws ApiException, NoApiKeyException, UploadFileException, IOException {
        /*
         * Description of image input methods:
         * Three image input methods are provided below. Choose one.
         * 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 that require encrypted transmission.
         */
        // [Method 1] Use a public image URL
        String image1 = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/pjeqdf/car.webp";
        String image2 = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/xsunlm/paint.webp";

        // [Method 2] Use a local file (supports absolute and relative paths)
        // Required format: file:// + file path
        // String image1 = "file:///path/to/your/car.png";
        // String image2 = "file:///path/to/your/paint.png";

        // [Method 3] Use a Base64-encoded image
        // String image1 = encodeFile("/path/to/your/car.png");
        // String image2 = encodeFile("/path/to/your/paint.png");

        // Build a multi-image input message
        ImageGenerationMessage message = ImageGenerationMessage.builder()
                .role("user")
                .content(Arrays.asList(
                        // Multi-image input is supported. You can provide multiple reference images.
                        Collections.singletonMap("text", "Spray the graffiti from image 2 onto the car in image 1"),
                        Collections.singletonMap("image", image1),
                        Collections.singletonMap("image", image2)
                )).build();

        ImageGenerationParam param = ImageGenerationParam.builder()
                .apiKey(apiKey)
                .model("wan2.7-image-pro")
                .n(1)
                .size("2K") // The wan2.7-image-pro model supports 4K resolution only for text-to-image generation. For image editing and composition, the maximum supported resolution is 2K.
                .messages(Arrays.asList(message))
                .build();

        ImageGeneration imageGeneration = new ImageGeneration();
        ImageGenerationResult result = null;
        try {
            System.out.println("---async call for image editing, creating task----");
            result = imageGeneration.asyncCall(param);
        } catch (ApiException | NoApiKeyException | UploadFileException e) {
            throw new RuntimeException(e.getMessage());
        }
        System.out.println("Task creation result:");
        System.out.println(JsonUtils.toJson(result));

        String taskId = result.getOutput().getTaskId();
        // Wait for the task to complete.
        waitTask(taskId);
    }

    public static void waitTask(String taskId) throws ApiException, NoApiKeyException, IOException {
        ImageGeneration imageGeneration = new ImageGeneration();
        System.out.println("\n---waiting for task completion----");
        ImageGenerationResult result = imageGeneration.wait(taskId, apiKey);
        // Extract the URL of the result image and save it locally.
        for (int i = 0; i < result.getOutput().getChoices().size(); i++) {
            List<Map<String, Object>> contents = result.getOutput().getChoices().get(i)
                    .getMessage().getContent();
            for (int j = 0; j < contents.size(); j++) {
                if ("image".equals(contents.get(j).get("type"))) {
                    String imageUrl = (String) contents.get(j).get("image");
                    String fileName = "output_" + i + "_" + j + ".png";
                    // The result URL is valid for 24 hours. Download the image in a timely manner.
                    try (InputStream in = new URL(imageUrl).openStream()) {
                        Files.copy(in, Paths.get(fileName), StandardCopyOption.REPLACE_EXISTING);
                    }
                    System.out.println("Image saved to " + fileName);
                }
            }
        }
    }

    public static void main(String[] args) throws ApiException, NoApiKeyException, UploadFileException, IOException {
        asyncCall();
    }
}

Response example

  1. Response example for creating a task
{
    "requestId": "ccf4b2f4-bf30-9e13-9461-3a28c6a7bxxx",
    "output": {
        "task_id": "8811b4a4-00ac-4aa2-a2fd-017d3b90cxxx",
        "task_status": "PENDING"
    },
    "status_code": 200,
    "code": "",
    "message": ""
}
  1. Response example for querying a task result

    The URL is valid for 24 hours. Save it promptly.

{
    "requestId": "60a08540-f1c1-9e76-8cd3-d5949db8cxxx",
    "usage": {
        "input_tokens": 18711,
        "output_tokens": 2,
        "total_tokens": 18713,
        "image_count": 1,
        "size": "2985*1405"
    },
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxxx.png?Expires=xxxxxx",
                            "type": "image"
                        }
                    ]
                }
            }
        ],
        "task_id": "8811b4a4-00ac-4aa2-a2fd-017d3b90cxxx",
        "task_status": "SUCCEEDED",
        "finished": true,
        "submit_time": "2026-03-31 19:57:58.840",
        "scheduled_time": "2026-03-31 19:57:58.877",
        "end_time": "2026-03-31 19:58:11.563"
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

curl

Step 1: Create a task to get the task ID

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header "X-DashScope-Async: enable" \
--data '{
    "model": "wan2.7-image-pro",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/pjeqdf/car.webp"},
                    {"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/xsunlm/paint.webp"},
                    {"text": "Spray-paint the graffiti from image 2 onto the car in image 1"}
                ]
            }
        ]
    },
    "parameters": {
        "size": "2K",
        "n": 1,
        "watermark": false
    }
}'
Response example
{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Step2: Query the result by task ID

Use the task_id obtained in the previous step to poll the task status through the API until the task_status becomes SUCCEEDED or FAILED.

Replace {task_id} with the task_id value returned by the previous API call. The task_id is valid for queries for 24 hours, Replace {WorkspaceId} with your actual workspace ID.

curl -X GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
Response example

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

{
    "request_id": "810fa5f5-334c-91f3-aaa4-ed89cf0caxxx",
    "output": {
        "task_id": "a81ee7cb-014c-473d-b842-76e98311cxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-26 17:16:01.663",
        "scheduled_time": "2026-03-26 17:16:01.716",
        "end_time": "2026-03-26 17:16:22.961",
        "finished": true,
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://dashscope-xxx.oss-xxx.aliyuncs.com/xxx.png?Expires=xxx",
                            "type": "image"
                        }
                    ]
                }
            }
        ]
    },
    "usage": {
        "size": "2976*1408",
        "total_tokens": 11017,
        "image_count": 1,
        "output_tokens": 2,
        "input_tokens": 11015
    }
}

wan2.5-i2i-preview uses different API endpoints and parameter passing methods. Its call examples are as follows:

Click to view call examples for wan2.5-i2i-preview

Synchronous call

ImportantEnsure that the DashScope Python SDK version is at least2.0.1and the DashScope Java SDK version is at least2.22.2.

Outdated SDK versions may trigger "url error, please check url!" errors. Install or upgrade the SDK.

Python

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

Request example
import base64
import mimetypes
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import dashscope
import requests
import os

# The following is the configuration for the China (Beijing) region. Replace {WorkspaceId} with your Bailian workspace ID. The region value varies by region.
# If no environment variable is configured, replace the following line with your Model Studio API key: api_key="sk-xxx"
# The API keys for the Singapore and Beijing regions are different. To obtain an API key: https://help.aliyun.com/model-studio/get-api-key
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# --- 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_1.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----')
# generate is a one-step call (submits the task and waits for completion) that returns the completed Job.
job = client.images.generate(model="wan2.5-i2i-preview",
                             prompt="Place the alarm clock from image 1 beside the vase on the dining table in image 2.",
                             extra_input={'images': [image_url_1, image_url_2]},
                             negative_prompt="",
                             n=1,
                             # size="1280*1280",
                             prompt_extend=True,
                             watermark=False,
                             seed=12345)
print('response: %s' % job)
# Save images to current directory
for result in job.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)
Response example

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

{
    "request_id": "8ad45834-4321-44ed-adf5-xxxxxx",
    "task_id": "3aff9ebd-35fc-4339-98a3-xxxxxx",
    "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."
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "FAILED": 0,
        "SUCCEEDED": 1
    },
    "usage": {
        "image_count": 1
    }
}

Java

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

Request example
// Copyright (c) Alibaba, Inc. and its affiliates.
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
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 Beijing region. Replace {WorkspaceId} with your Bailian workspace ID. URLs differ by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.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://help.aliyun.com/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

The image URL is valid for 24 hours. Download the image 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
    }
}

Asynchronous call

ImportantEnsure that the DashScope Python SDK version is at least2.0.1and the DashScope Java SDK version is at least2.22.2.

Outdated SDK versions may trigger "url error, please check url!" errors. Install or upgrade the SDK.

Python

This example uses a public URL to pass the image.

Request example

import os
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import dashscope
import requests

# The following is the configuration for the China (Beijing) region. Replace {WorkspaceId} with your Bailian workspace ID. The region value varies by region.
# If no environment variable is configured, replace the following line with your Model Studio API key: api_key="sk-xxx"
# The API keys for the Singapore and Beijing regions are different. To obtain an API key: https://help.aliyun.com/model-studio/get-api-key
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# Use public image URLs
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"

def async_call():
    print('----create task----')
    task_info = create_async_task()
    print('----wait task----')
    wait_async_task(task_info)

# Create an asynchronous task
def create_async_task():
    job = client.images.jobs.create(model="wan2.5-i2i-preview",
                                    prompt="Place the alarm clock from image 1 beside the vase on the dining table in image 2.",
                                    extra_input={'images': [image_url_1, image_url_2]},
                                    negative_prompt="",
                                    n=1,
                                    # size="1280*1280",
                                    prompt_extend=True,
                                    watermark=False,
                                    seed=12345)
    print(job)
    print(job.task_id, job.status)
    return job

# Wait for the asynchronous task to finish (exponential backoff polling, default total budget of 24 hours; a FAILED task raises DashScopeError)
def wait_async_task(task):
    done = client.images.jobs.wait(task)
    print(done)
    print(done.status)
    # save file to current directory
    for result in done.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)

# Fetch asynchronous task information
def fetch_task_status(task):
    snapshot = client.images.jobs.fetch(task)
    print(snapshot)
    print(snapshot.status)

# Cancel the asynchronous task. Only tasks in the PENDING state can be canceled.
def cancel_task(task):
    job = client.images.jobs.cancel(task)
    print(job)

if __name__ == '__main__':
    async_call()

Response example

  1. Response example for creating a task
{
    "request_id": "31b04171-011c-96bd-ac00-f0383b669cc7",
    "task_id": "4f90cf14-a34e-4eae-xxxxxxxx",
    "status": "PENDING"
}
  1. Response example for querying a task result

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

{
    "request_id": "8ad45834-4321-44ed-adf5-xxxxxx",
    "task_id": "3aff9ebd-35fc-4339-98a3-xxxxxx",
    "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."
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "FAILED": 0,
        "SUCCEEDED": 1
    },
    "usage": {
        "image_count": 1
    }
}

Java

This example uses a public URL to pass the image by default.

Request example

// 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.Constants;
import com.alibaba.dashscope.utils.JsonUtils;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class Image2Image {
    static {
        // The following URL is for the Beijing region. Replace {WorkspaceId} with your Bailian workspace ID. URLs differ by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.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://help.aliyun.com/model-studio/get-api-key
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    // Public URLs
    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";

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

    public static void asyncCall() {
        // 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("---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

  1. Response when creating a task
{
	"request_id": "5dbf9dc5-4f4c-9605-85ea-542f97709ba8",
	"output": {
		"task_id": "7277e20e-aa01-4709-xxxxxxxx",
		"task_status": "PENDING"
	}
}
  1. Response when querying task results

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
    }
}

curl

This is a two-step process: create a task, then retrieve the result.

Note

  • For asynchronous calls, set the header parameter X-DashScope-Async to enable.
  • The task_id for an asynchronous task is valid for 24 hours. After it expires, the task status becomes UNKNOWN.
  • Beginners should use Call APIs with Postman or cURL to call the API.

Step 1: Send a request to create a task

This request returns a task ID (task_id).

Request example
 curl --location 'https://{WorkspaceId}.cn-beijing.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": "Place the alarm clock from image 1 beside the vase on the dining table in image 2.",
        "images": [
            "https://img.alicdn.com/imgextra/i3/O1CN0157XGE51l6iL9441yX_!!6000000004770-49-tps-1104-1472.webp",
            "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp"
        ]
    },
    "parameters": {
        "n": 1
    }
}'
Response example
{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Step 2: Query the result by task ID

Use the task_id obtained in the previous step to poll the task status through the API until the task_status becomes SUCCEEDED or FAILED.

Request example

Replace {task_id} with the task_id value returned by the previous API call. The task_id is valid for queries for 24 hours, Replace {WorkspaceId} with your actual workspace ID.

curl -X GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
Response example

The image URL is valid for 24 hours. Download the image 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": "Place the alarm clock from image 1 next to the vase on the dining table in image 2",
                "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
    }
}

Model selection

  • wan2.7-image-pro, wan2.7-image (recommended): Best for scenarios that require high editing precision, or for generating multiple content-coherent images.

    • Precise local editing: Select a specific area to move, replace, or add elements. Ideal for e-commerce retouching and design adjustments.
    • Multi-panel continuous image generation: Output multiple images with a consistent style in one call. Ideal for comic storyboards, product series, and sequential story images.
  • wan2.6-image: Stylized editing with mixed text/images or multiple references. Generates text in images and accepts up to four reference images.

  • wan2.5-i2i-preview: Suitable for simple image editing and multi-image fusion.

For the input and output specifications of each model, see Input image specifications and Output image resolution.

Image-to-image set

Input image

Output image

East Asian male portrait, 20 years old, curly medium-length hair, artistic temperament

output

wan_image_reqid_57d7a71c-1932-4de8-8c32-be0f3fd5696f_n1-2026-03-31-19-32-44

output

Click to view prompts

Case 1: Photoshoot

Base character setting: A 20-year-old East Asian male with curly, medium-length hair, an artistic temperament, defined features, and delicate eyes. He is wearing a simple white T-shirt or a light blue shirt, exuding a youthful and natural vibe.
1. Republic Era Scholar Style
Prompt:
[Base facial description] The character's appearance is based on reference image 1, wearing a dark cyan long gown and round, gold-rimmed glasses, holding a folding fan. The background is an old Shanghai study with wooden bookshelves, a warm yellow tone, a retro film texture, soft side lighting, and dust dancing in the light beams, creating a cultural and serene atmosphere. Hasselblad medium format, 85mm lens, high resolution, cinematic color grading, Wong Kar-wai style.
Props: Folding fan / Thread-bound book / Round-frame glasses
Color tone: Warm yellow / Dark cyan / Sepia
2. British Gentleman Style
Prompt:
[Base facial description] The character's appearance is based on reference image 1, wearing a dark gray tweed three-piece suit and a vintage mechanical watch, holding a glass of red wine and looking at it. The background is a classic library or private club with dark leather sofas, Rembrandt lighting, and a dark, elegant, and noble atmosphere. He has a cool gaze, with rich details and clear textures, exuding a British aristocratic temperament. 8k resolution, fashion magazine-style shot.
Props: Wine glass / Pipe / Mechanical watch
Color tone: Dark gray / Burgundy / Dark gold
3. 90s HK Retro Style
Prompt:
[Base facial description] The character's appearance is based on reference image 1, wearing a washed denim jacket or a floral shirt, with slightly messy hair and arms crossed. The background is a street with neon signs at night, with blurry light spots, high grain, and rich colors, featuring a red and blue color clash. Wong Kar-wai style, emotional, with a dreamy gaze, direct flash effect, and a nostalgic atmosphere. [Full-body shot].
Color tone: Neon red / Dark blue / Film green
4. New Chinese Zen Style
Prompt:
[Base facial description] The character's appearance is based on reference image 1, with a slight smile showing teeth, wearing a modified white Chinese stand-up collar shirt, holding a branch of plum blossoms. The background is a minimalist blank wall or a bamboo forest, with sunlight casting mottled shadows on the wall. The color tone is cool and serene, embodying Eastern aesthetics. The skin is translucent, with high grain and a matte finish. The composition is simple, with rich layers of light and shadow. High-end photography, Zen atmosphere.
Props: Plum blossom branch
Color tone: White / Dark green / Light gray
5. Vintage Artist Style
Prompt:
[Base facial description] The character's appearance is based on reference image 1, wearing a white shirt stained with paint and a brown leather apron, holding a paintbrush or a palette. The background is a clean studio with bright light and colorful light and shadow. He has a focused expression, looking at the paint in his hand, not at the camera. His hair is slightly messy, with an artistic flair, an impressionist color tone, and a strong texture.
Props: Paintbrush / Palette / Sketchbook
Color tone: Warm light / Colorful paint / Brown
6. Classic Noir B&W Style
Prompt:
[Base facial description] The character's appearance is based on reference image 1, wearing a black turtleneck sweater, holding a cigarette, and wearing a black fedora. The background is a staircase or hallway with intersecting shadows. High-contrast black and white photography, hard lighting, strong shadows, a sense of mystery, and a hard-boiled detective style. The facial contours are sharp, with extremely clear skin texture. A classic movie still, timeless feel, side-profile close-up, artistic photography.
Props: Cane / Fedora / Sunglasses
Color tone: Black and white / High contrast

Case 2: Visual design

Image 1: A commercial-grade product photography main visual cover image, front-view panoramic composition. A pair of retro-futuristic wireless over-ear headphones floats above a geometric plaster form, showcasing perfect symmetrical aesthetics. The materials are champagne gold metal and a cream-white shell. The background is a deeply blurred warm indoor light and shadow, with soft light outlining the product's silhouette. The white space in the image creates a strong sense of breathability, suggesting a quiet auditory experience. 8k ultra-high resolution, minimalist and premium feel.
Image 2: A 100mm macro shot of the product's material details, focusing closely on the connection of the headphone's telescopic arm. It clearly shows the texture of the champagne gold brushed aluminum alloy and the CNC precision-cut chamfers. A sharp backlight creates a starburst highlight on the metal edge. The background is dark to emphasize the industrial precision of the metal. The image quality is extremely sharp with no noise.
Image 3: An extreme close-up macro shot of the material, focusing on the surface of the mocha-colored protein leather earcups. Side lighting reveals the fine pore texture of the leather, the soft wrinkles from pressing, and the ventilation hole details, conveying ultimate skin-friendly comfort and resilience. The light and shadow are rich in layers, and the color tone is warm and moist. Ultra-high-definition macro photography.
Image 4: An artistic exploded view of the product, showing the internal sound units, noise-canceling chips, battery modules, and external walnut wood decorative panels and metal frame of the retro-futuristic headphones in a suspended, disassembled state. The background is a deep tech blue, and the internal components have a semi-transparent holographic technological texture, emphasizing the combination of internal precision craftsmanship and modern technology. High-tech commercial poster style.
Image 5: A 35mm humanistic shot of the wearing scenario, with a close-up on the model's jawline and neck, showing the perfect fit of the champagne gold headphones. Natural warm sunset light from the side-rear creates a rim light, with the edges of the hair glowing gold. The model's skin tone has a healthy and natural texture, creating a relaxed, immersive music-listening lifestyle feel. The background is a blurry home environment.
Image 6: A still life photograph paying homage to architectural light and shadow. The headphones are placed on a minimalist gray concrete table. Afternoon sunlight streams through blinds, casting striped hard shadows that cut across the matte cream-white body and champagne gold frame, creating a strong geometric composition of light and dark. This highlights the three-dimensional shape of the body and the contrast of materials. A clash of cool and warm color tones, minimalist composition.
Image 7: A top-down flat-lay composition showing the color options. Three headphones from the series in different color schemes—silver-white, black-gold, and blue-copper—are arranged side by side. The background is a highly textured gray wool felt cloth. Soft top lighting emphasizes the diversity of the CMF design and the delicate touch of the materials. The image is clean and orderly, in a design magazine style.
Image 8: A brand lifestyle family portrait still life photograph. The retro-futuristic headphones are placed next to their matching exquisite leather case. On the table are a vinyl record player, a spinning vinyl record, and a cup of steaming coffee. The background is rendered with warm ambient lighting, dominated by a deep walnut wood tone, conveying a brand philosophy that combines a slow-paced lifestyle with high-fidelity sound quality. Cinematic narrative lighting.

Interactive editing

Input image

Output image

5eecdaf48460cde5f7fd58249809b192a118accde85283f275b8339e1c4c24831b75b38faadcd24bec177c308ebd5304463ca8e345548eb5f551b6ba01cd2c8d2d9b5606fa569ff7ba4077816ac9b801464f65aedbcf494f4fb4c8ed7016461c-combine

5eecdaf48460cde5f7fd58249809b192a118accde85283f275b8339e1c4c24831b75b38faadcd24bec177c308ebd530460436714d0283cee289325430893028097a53a8e5d630fb1c2d4c85d8cbb68a4387575c4b03700344fb4c8ed7016461c-2026-03-31-19-13-38

Place the selected pattern from image 1 into the selected area in image 2.

Multi-image fusion

Input image

Output image

5eecdaf48460cde5544f9fac410016bc2fe4c1b4d23666c075b8339e1c4c24831b75b38faadcd24bec177c308ebd5304e9d05d028a65a9ac270ee730e44b8c75c6634a9b9a7a70240d438b02b2f2153dc68966b442378d1d4fb4c8ed7016461c-combine

5eecdaf48460cde5544f9fac410016bc2fe4c1b4d23666c075b8339e1c4c24831b75b38faadcd24bec177c308ebd53044b9a1d72dee2f8507ee704b9cef3832907ff1182f52507c9bc4737520762d46a722e658f57cda6524fb4c8ed7016461c-2025-12-29-19-11-31

Take a portrait of the boy from image 1 and the dog from image 2. The boy is hugging the dog, and both are very happy. Studio soft lighting, blue textured background.

5eecdaf48460cde5544f9fac410016bc2fe4c1b4d23666c075b8339e1c4c24831b75b38faadcd24bec177c308ebd5304f060ec7a363e318af9bfaaa5e07be972cfc1ea4e21b47637fcdb2dfc53130c40a8efed5defc408a04fb4c8ed7016461c-combine

5eecdaf48460cde5544f9fac410016bc2fe4c1b4d23666c075b8339e1c4c24831b75b38faadcd24bec177c308ebd5304922cbdef3e3c42f83239de6d0f35a8b76f0e38934cc5170f7a908ec12140fb0af6590c72bcf1ba6f4fb4c8ed7016461c-2025-12-29-19-15-53

Recolor the dress from image 1 using the colors of the bird in image 2. Make it artistic, but keep the style of the dress and the model unchanged.

Subject feature preservation

Input image

Output image

5eecdaf48460cde5544f9fac410016bc2fe4c1b4d23666c075b8339e1c4c24831b75b38faadcd24bec177c308ebd5304448a972b9f2ee7a7aadcc61495f4975a049f009e7721cbc833dc3a8005b1b026a54eaaec109d73484fb4c8ed7016461c-2025-12-29-20-00-21

5eecdaf48460cde5544f9fac410016bc2fe4c1b4d23666c075b8339e1c4c24831b75b38faadcd24bec177c308ebd5304cc1b4a509823c5fb5e60999898811f8b51d7419220a118c9ff82110bc9525725a9ad7338f75985794fb4c8ed7016461c-2025-12-29-20-00-21

Please generate a set of four Polaroid photos with the theme "Seasonal Changes". Each photo is taken at the same location, under a tree in a park, but shows the scenes of spring, summer, autumn, and winter respectively. The person's attire should also match the season: a light jacket in spring, a short-sleeved shirt in summer, a trench coat in autumn, and a scarf and thick coat in winter. Place this set of photos on a dining table.

Detection and segmentation

Input image

Output image

5eecdaf48460cde5544f9fac410016bc2fe4c1b4d23666c075b8339e1c4c24831b75b38faadcd24bec177c308ebd5304b025e74206dc2cec5c2e587c3fe6fb135293836c9479220355470da15476dc934b26018061e9db0b4fb4c8ed7016461c-2025-12-29-19-54-33

5eecdaf48460cde5544f9fac410016bc2fe4c1b4d23666c075b8339e1c4c24831b75b38faadcd24bec177c308ebd530451385eb561b49b0fe1f2169526b6a7e15bd78940def3c640c801511c349f6df35dceb72f4d3755f94fb4c8ed7016461c-2025-12-29-19-54-33

Detect the laptop and alarm clock in the image, draw bounding boxes, and label them "laptop" and "clock".

5eecdaf48460cde5544f9fac410016bc2fe4c1b4d23666c075b8339e1c4c24831b75b38faadcd24bec177c308ebd530440256f9add4113787af5d4f3a55469b38ef2422f018076640eb7cb552584c02ee729fcb23fec3bca4fb4c8ed7016461c-2025-12-29-19-54-33

5eecdaf48460cde5544f9fac410016bc2fe4c1b4d23666c075b8339e1c4c24831b75b38faadcd24bec177c308ebd5304f0612d67f5c810ebef958385624ebd17323047aa5d00465d0e35257de5a2ea49d4b375d2e57693fa4fb4c8ed7016461c-2025-12-29-19-54-32

Segment the glass cup in the image.

Extract elements

Input image

Output image

5eecdaf48460cde5544f9fac410016bc2fe4c1b4d23666c075b8339e1c4c24831b75b38faadcd24bec177c308ebd53046b83761f1ab18c40e144f5db2b388e5f865ba9a5961d98b2710ce177c6a0f4baff63fe52259c44364fb4c8ed7016461c-2025-12-29-19-48-27

5eecdaf48460cde5544f9fac410016bc2fe4c1b4d23666c075b8339e1c4c24831b75b38faadcd24bec177c308ebd53048e2a0d1d2805d92ba8d45a3bd1368528dd76f517b21ad1f545eb4097610838497cbdb5196da94ff54fb4c8ed7016461c-2025-12-29-19-48-27

Extract the clothing items from the uploaded photo and arrange them in a flat-lay display on a pure white background. Maintain realistic details and material textures. Fashion e-commerce style, suitable for clothing display.

Text editing

Input image

Output image

5eecdaf48460cde5544f9fac410016bc2fe4c1b4d23666c075b8339e1c4c24831b75b38faadcd24bec177c308ebd530490f493eca22f34f0197173ddfdef17a04b34cb94813178b9d4eee36d246d3530a3e2fc6258cca0694fb4c8ed7016461c-2025-12-29-19-28-35

5eecdaf48460cde5544f9fac410016bc2fe4c1b4d23666c075b8339e1c4c24831b75b38faadcd24bec177c308ebd5304fe77776567f4ef79cb621289a6fdaa981f3364fe4c7c56265403b5d9d5ac43eaf5931f62db14952f4fb4c8ed7016461c-2025-12-29-19-28-35

Remove all watermarks from the image.

5eecdaf48460cde5544f9fac410016bc2fe4c1b4d23666c075b8339e1c4c24831b75b38faadcd24bec177c308ebd530476e971380812b1b9dbeac68272a27057175499fe84f0781c7b6fa6535f438c67f3556acc8c7324394fb4c8ed7016461c-2025-12-29-19-28-35

5eecdaf48460cde5544f9fac410016bc2fe4c1b4d23666c075b8339e1c4c24831b75b38faadcd24bec177c308ebd53047be52c6f41edecdefa77f0d93335d1492f1821b47dff7a1b08f60e99bdafcc84c31e3658fc593c904fb4c8ed7016461c-2025-12-29-19-28-35

Casually write "Time for Holiday?" on the sand with a hand.

5eecdaf48460cde5544f9fac410016bc2fe4c1b4d23666c075b8339e1c4c24831b75b38faadcd24bec177c308ebd5304fdb284f8d5c8ead814d11890da1a49411a6d9d41ad1bb2a4bf0b93d0bee5d792e8f5b419a3da9d534fb4c8ed7016461c-2025-12-29-19-28-34

5eecdaf48460cde5544f9fac410016bc2fe4c1b4d23666c075b8339e1c4c24831b75b38faadcd24bec177c308ebd5304df1c8787530497f4cc3bee0b84d3ba51d0353fceb8d0518ded6a25e8c0ddfec714f719154ac1c9354fb4c8ed7016461c-2025-12-29-19-28-34

Change 18 to 29 and JUNE to SEPTEMBER.

Camera and perspective editing

Input image

Output image

image (2)-2025-12-29-19-42-44

image (3)-2025-12-29-19-42-44

Keep the person's features unchanged and generate front, side, and back views.

5eecdaf48460cde5544f9fac410016bc2fe4c1b4d23666c075b8339e1c4c24831b75b38faadcd24bec177c308ebd5304a53988b2efdd2fb6b95cb3b1b02701e6ff2c4902170b1ee230a9b4e3726a891c93646d68b821de294fb4c8ed7016461c-2025-12-29-19-42-43

5eecdaf48460cde5544f9fac410016bc2fe4c1b4d23666c075b8339e1c4c24831b75b38faadcd24bec177c308ebd530428783dee341e41eb06234dfb75bd149d774f4850000123559a98bcd7ece97dc4a6c3cefa983ae8ac4fb4c8ed7016461c-2025-12-29-19-42-43

Reshoot this photo with a fisheye lens.

Input specifications

Input image specifications

Specification

wan2.7-image-pro, wan2.7-image

wan2.6-image

wan2.5-i2i-preview

Number of input images

0 to 9 (0 corresponds to text-to-image mode)

Image editing: 1 to 4 / Mixed text and image: 0 to 1

1 to 3

Image format

JPEG, JPG, PNG (alpha channel not supported), BMP, WEBP

JPEG, JPG, PNG (alpha channel not supported), BMP, WEBP

JPEG, JPG, PNG (alpha channel not supported), BMP, WEBP

Image width and height range

[240, 8000] pixels

[240, 8000] pixels

[384, 5000] pixels

File size

≤ 20 MB

≤ 10 MB

≤ 10 MB

Aspect ratio

[1:8, 8:1]

Unlimited

[1:4, 4:1]

Image input order

For multi-image input, the image order is defined by the order in the array. Therefore, the image numbers referenced in the prompt must correspond one-to-one with the order in the image array. For example, the first image in the array is "image 1" and the second is "image 2". You can also use marker forms such as "[image 1]" and "[image 2]".

{
    "content": [
        {"text": "Editing instruction, for example: Place the alarm clock from image 1 next to the vase on the dining table in image 2"},
        {"image": "https://example.com/image1.png"},
        {"image": "https://example.com/image2.png"}
    ]
}

Input image

Output image

image (19)-转换自-png

Image 1

image (20)-转换自-png

Image 2

04e0fc39-7ad6-41e0-9df9-1f69ac3ce825-转换自-png

Prompt: Move image 1 onto image 2

36ed450d-bd54-4169-b13f-3d0f26d9d360-转换自-png

Prompt: Move image 2 onto image 1

Image input methods

Pass images using any of these methods:

Method 1: Public URL

  • Provide a publicly accessible HTTP or HTTPS image URL.
  • Example value: https://xxxx/img.png.
  • Use when images are hosted on OSS or a public image hosting service.

Method 2: Base64 encoding

Convert the image file to a Base64-encoded string and format it as: data:{MIME_type};base64,{base64_data}.

  • Example value: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAABDg...... (This is a snippet due to length limitations). When making a call, pass the complete string.

  • {base64_data}: The Base64-encoded string of the image file.

  • {MIME_type}: 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

  • Use for local images, private images, or scenarios that require encrypted transmission.

Code example: Base64 encoding for an image

import os
import base64
import mimetypes

# The format is data:{mime_type};base64,{base64_data}
def encode_file(file_path):
    mime_type, _ = mimetypes.guess_type(file_path)
    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}"

# Call the encoding function. Replace "/path/to/your/image.png" with the path to your local image file, otherwise the code will not run.
image = encode_file("/path/to/your/image.png")

Method 3: Local file path (SDK only)

  • Python SDK: Supports both absolute and relative paths. The file path rules are as follows:

    System

    Input file path

    Example (absolute path)

    Example (relative path)

    Linux or macOS

    file://{absolute or relative path of the file}

    file:///home/images/test.png

    file://./images/test.png

    Windows

    file://D:/images/test.png

    file://./images/test.png

  • Java SDK: Supports only the absolute path. The file path rules are as follows:

    System

    Input file path

    Example (absolute path)

    Linux or macOS

    file://{absolute path of the file}

    file:///home/images/test.png

    Windows

    file:///{absolute path of the file}

    file:///D:/images/test.png

  • Use for quick testing in local development.

Key features

1. Instruction following (prompts)

Parameters: messages.content.text or input.prompt (required), negative_prompt (optional).

  • text or prompt (Positive prompt): Describe content, subjects, scenes, styles, lighting, and composition for the output image.
  • negative_prompt (Negative prompt): Describe content that you do not want to appear in the image, such as "blurry" or "extra fingers". It is only used to help optimize generation quality.

Parameter

wan2.7-image-pro, wan2.7-image

wan2.6-image

wan2.5-i2i-preview

text

Required, up to 5,000 characters

Required, up to 2,000 characters

Not supported

prompt

Not supported

Not supported

Required, up to 2,000 characters

negative_prompt

Not supported

Supported, up to 500 characters

Supported, up to 500 characters

2. Enable intelligent prompt rewriting

Parameter: parameters.prompt_extend (bool, defaults to true).

This feature automatically expands and optimizes short prompts to improve the output image quality. Enabling this feature adds extra processing time.

Best practices:

  • Recommended to enable: When the input prompt is concise or broad, this feature can improve the image quality.
  • Recommended to disable: If you need to control the image details, have already provided a detailed description, or are sensitive to response latency. Explicitly set the parameter prompt_extend to false.

Parameter

wan2.7-image-pro, wan2.7-image

wan2.6-image

wan2.5-i2i-preview

prompt_extend

Not supported

Supported (image editing mode only)

Supported

3. Set the output image resolution

Parameter: parameters.size (string), in the format "width*height".

ImportantThe 1K tier of the same name is defined differently across models: the wan2.7 series outputs a total pixel count close to 10241024, while wan2.6-image is close to 12801280. Pay attention to the output resolution differences when switching models.

Parameterwan2.7-image-pro, wan2.7-imagewan2.6-imagewan2.5-i2i-preview

size

Method 1: Specify the output image resolution (recommended)

In editing mode (with at least one image passed), the optional output resolution tiers are: 1K, 2K (default).

  • 1K: The output total pixels are close to 1024*1024, with the aspect ratio matching the last input image.
  • 2K: The output total pixels are close to 2048*2048, with the aspect ratio matching the last input image.
Method 2: Specify the width and height pixel values of the generated image
  • The total pixels are between 768768 and 20482048, with an aspect ratio range of [1:8, 8:1].

Only wan2.7-image-pro in text-to-image scenarios supports 4K resolution.

Method 1: Reference the input image ratio (recommended)

In editing mode (enable_interleave=false), the optional output resolution tiers are: 1K (default), 2K.

  • 1K: The output total pixels are close to 1280*1280, with the aspect ratio matching the last input image.
  • 2K: The output total pixels are close to 2048*2048, with the aspect ratio matching the last input image.
Method 2: Specify the width and height pixel values of the generated image
  • The total pixels are between 768768 and 20482048, with an aspect ratio range of [1:4, 4:1].

The actual output image pixel values will be the closest multiple of 16 to the specified value.

Only supports specifying the width and height pixel values of the generated image
  • The total pixels are between 768768 and 12801280, with an aspect ratio range of [1:4, 4:1].
  • If size is not specified, the system will default to generating an image with a total pixel count of 1280*1280, with the aspect ratio matching the last input image.

4. Interactive precise editing

Use the parameter parameters.bbox_list to box-select the objects or locations in the image to edit, achieving more accurate editing results. Only supported by wan2.7-image-pro and wan2.7-image.

  • List length: Must match the number of input images. Use an empty list [] for images that don't require editing.
  • Coordinate format: [x1, y1, x2, y2] (top-left x, top-left y, bottom-right x, bottom-right y). Use absolute pixel coordinates of the original image, with the top-left corner as (0, 0), the x-axis pointing right, and the y-axis pointing down. If you use a vision model (such as qwen3.6-plus) to locate the target region, it returns normalized coordinates [0, 999]. Convert them to absolute pixel coordinates with the auxiliary code below before passing them in.
  • Quantity limit: A maximum of 2 bounding boxes per image.

Example: Input 3 images, where image 2 has no selection box and image 1 has two:

[
  [[0, 0, 12, 12], [25, 25, 100, 100]],
  [],
  [[10, 10, 50, 50]]
]

Click to view call examples

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
    "model": "wan2.7-image-pro",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {"image": "https://img.alicdn.com/imgextra/i3/O1CN0157XGE51l6iL9441yX_!!6000000004770-49-tps-1104-1472.webp"},
                    {"image": "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp"},
                    {"text": "Place the alarm clock from image 1 into the selected area of image 2, and ensure the scene and lighting blend naturally."}
                ]
            }
        ]
    },
    "parameters": {
        "bbox_list": [[],[[989, 515, 1138, 681]]],
        "size": "2K",
        "n": 1,
        "watermark": false
    }
}'

How to determine editing region coordinates

Method 1: Draw bounding boxes with OpenCV

Draw bounding boxes by dragging the mouse on the image for precise and intuitive selection:

# Install dependencies: pip install opencv-python
import cv2
import urllib.request

# Download a sample image (replace with your own image URL or local path)
image_url = "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp"
urllib.request.urlretrieve(image_url, "example.webp")

# Read the image and open an interactive window
img = cv2.imread("example.webp")
# Drag the mouse in the pop-up window to draw a box. Press Enter to confirm, press Esc to cancel
x, y, w, h = cv2.selectROI("Draw bounding box (Enter=confirm, Esc=cancel)", img)
cv2.destroyAllWindows()

# Convert the (x, y, w, h) returned by OpenCV to the [x1, y1, x2, y2] format required by bbox_list
# Coordinate system: origin at the top-left corner, x-axis points right, y-axis points down, unit is pixels
bbox = [x, y, x + w, y + h]
print(f"Bounding box coordinates: {bbox}")  # Pass these coordinates to parameters.bbox_list
Method 2: Visual understanding model

Use qwen3.6-plus to automatically identify target region coordinates by describing the target in natural language:

# Install dependencies: pip install dashscope pillow
import os
import json
import dashscope
from PIL import Image
import urllib.request

client = dashscope.Client(
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

def get_bbox_list(image, prompt):
    """
    Identify target regions in an image using qwen3.6-plus and return absolute pixel coordinates.

    Args:
        image: Image URL or local path (local path format: "file:///absolute/path.png")
        prompt: Natural language description, e.g., "coffee cup", "all fruits on the plate", "the fruit in the center of the plate"

    Returns:
        [[x1, y1, x2, y2], ...] Absolute pixel coordinates that can be passed directly to bbox_list
    """
    # Concatenate user description with return format instructions
    full_prompt = (
        prompt + "\n"
        "Based on the description above, return the coordinates of the corresponding region.\n"
        "Return a maximum of 2 regions, prioritizing the most matching target.\n"
        "Strictly follow the JSON 2D list format: [[x1, y1, x2, y2], ...]\n"
        "Each set of coordinates: [top-left x, top-left y, bottom-right x, bottom-right y]\n"
        "Use absolute pixel coordinates of the original image, with (0,0) at the top-left corner, x-axis pointing right, y-axis pointing down.\n"
        "If there is only one region, you must still use a 2D list: [[x1, y1, x2, y2]]\n"
        "Only return the JSON list, do not return any other content."
    )

    messages = [
        {'role': 'user',
         'content': [
             {'image': image},
             {'text': full_prompt}
         ]}
    ]

    response = client.multimodal.chat.create(
        model='qwen3.6-plus',
        messages=messages,
    )

    text = response.output_text
    text = text.replace("```json", "").replace("```", "").strip()
    coords = json.loads(text)

    # Handle the case where the model returns a 1D list [x1,y1,x2,y2]
    if coords and not isinstance(coords[0], list):
        coords = [coords]

    # Get image dimensions for coordinate conversion
    if image.startswith("file://"):
        local_path = image[len("file://"):]
        img = Image.open(local_path)
    else:
        tmp_path = "temp_bbox_image"
        urllib.request.urlretrieve(image, tmp_path)
        img = Image.open(tmp_path)
    width, height = img.size

    # Convert model's normalized coordinates [0, 999] to absolute pixel coordinates
    bbox_list = []
    for box in coords:
        bbox_list.append([
            int(box[0] / 1000 * width),
            int(box[1] / 1000 * height),
            int(box[2] / 1000 * width),
            int(box[3] / 1000 * height)
        ])

    return bbox_list

# === Usage examples ===
image_url = "https://img.alicdn.com/imgextra/i3/O1CN01ewUWhg1eS3VqJ3wap_!!6000000003869-49-tps-2048-2048.webp"

# Select target by name
bbox = get_bbox_list(image_url, "coffee cup")           # [[x1, y1, x2, y2]]

# Select target by position description
bbox = get_bbox_list(image_url, "the fruit in the center of the plate")  # [[x1, y1, x2, y2]]

# Describe a region
bbox = get_bbox_list(image_url, "lavender potted plant")

# Results can be used as elements in the bbox_list array
# Note: A maximum of 2 bounding boxes per image

Billing and rate limits

  • Free quota and pricing: Model list and pricing.

  • For rate limits, see Wanxiang.

  • Billing:

    • Billing is based on the number of images successfully generated. You are charged only after the API returns a task_status of SUCCEEDED and the image is successfully generated.
    • Failed model calls or processing errors do not incur any fees or consume the free quota.

API reference

Each model uses a different endpoint and request structure:

Model

Endpoint(Example for the China (Beijing) region)

wan2.7-image, wan2.7-image-pro, wan2.6-image

Sync API: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

Async API: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation

wan2.5-i2i-preview

Async API: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis

  • wan2.7 / wan2.6: Use the messages format. In the messages[].content array, pass the image in the image parameter and the prompt in the text parameter.
  • wan2.5: Pass the image in the input.images array and the prompt in the input.prompt parameter.
"input": {
    "messages": [
        {
            "role": "user",
            "content": [
                {"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/pjeqdf/car.webp"},
                {"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/xsunlm/paint.webp"},
                {"text": "Spray the graffiti from image 2 onto the car in image 1"}
            ]
        }
    ]
}
"input": {
    "prompt": "Place the alarm clock from image 1 next to the vase on the dining table in image 2",
    "images": [
        "https://img.alicdn.com/imgextra/i3/O1CN0157XGE51l6iL9441yX_!!6000000004770-49-tps-1104-1472.webp",
        "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp"
    ]
}

For input and output parameters, see Wan2.7 - image generation and editing, Wan2.6 - image generation and editing, Wanxiang – General Image Editing 2.5