From f126c506b2570794bedbce54bc39b0d79a9738f7 Mon Sep 17 00:00:00 2001
From: TanzJ <im.tanzj@live.com>
Date: Mon, 31 Aug 2026 23:22:22 +0800
Subject: [PATCH 1/6] feat: add dashscope_image_to_image tool to
 DashScopeMultiModalTool

---
 .../tool/DashScopeMultiModalTool.java         | 187 ++++++++++++++++++
 1 file changed, 187 insertions(+)

diff --git a/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/main/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalTool.java b/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/main/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalTool.java
index cf11bbdf86..ae8a76f49f 100644
--- a/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/main/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalTool.java
+++ b/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/main/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalTool.java
@@ -77,6 +77,7 @@
  * Support tools:
  * <ul>
  *     <li>dashscope_text_to_image: Generate image(s) based on the given text.</li>
+ *     <li>dashscope_image_to_image: Edit/transform an image based on a text prompt and the input image.</li>
  *     <li>dashscope_image_to_text: Generate text based on the given images.</li>
  *     <li>dashscope_text_to_audio: Convert the given text to audio.</li>
  *     <li>dashscope_audio_to_text: Convert the given audio to text.</li>
@@ -235,6 +236,192 @@ public Mono<ToolResultBlock> dashscopeTextToImage(
                         });
     }
 
+    /**
+     * Edit or transform an image based on a text prompt and an input image.
+     *
+     * @param imageUrl      The URL, local file path, or Base64 data URL of the input image to edit.
+     * @param prompt        The text prompt describing the desired edit or transformation.
+     * @param model         The model to use, e.g., 'qwen-image'.
+     * @param size          Size of the output image, e.g., '1024*1024'.
+     * @param useBase64     Whether to return image as base64 data instead of URL.
+     * @return A ToolResultBlock containing the generated image url/base64 or error message.
+     */
+    @Tool(
+            name = "dashscope_image_to_image",
+            description =
+                    "Edit or transform an image based on a text prompt and an input image."
+                            + " Returns the edited image as URL or base64.")
+    public Mono<ToolResultBlock> dashscopeImageToImage(
+            @ToolParam(
+                            name = "image_url",
+                            description =
+                                    "The URL, local file path or Base64 data URL (the format"
+                                        + " pattern is data:[MIME_type];base64,{base64_image},"
+                                        + " e.g., 'data:image/png;base64,iVBORw0KGgo...') of"
+                                        + " the input image to edit")
+                    String imageUrl,
+            @ToolParam(
+                            name = "prompt",
+                            description =
+                                    "The text prompt describing the desired edit or"
+                                            + " transformation")
+                    String prompt,
+            @ToolParam(
+                            name = "model",
+                            description = "The model to use, e.g., 'qwen-image'.",
+                            required = false)
+                    String model,
+            @ToolParam(
+                            name = "size",
+                            description =
+                                    "Size of the output image, e.g., '1024*1024', '1280*1280'.",
+                            required = false)
+                    String size,
+            @ToolParam(
+                            name = "use_base64",
+                            description = "Whether to return image as base64 data instead of URL",
+                            required = false)
+                    Boolean useBase64) {
+
+        String finalModel =
+                Optional.ofNullable(model).filter(s -> !s.trim().isEmpty()).orElse("qwen-image");
+        String finalSize =
+                Optional.ofNullable(size).filter(s -> !s.trim().isEmpty()).orElse("1024*1024");
+        Boolean finalUseBase64 = Optional.ofNullable(useBase64).orElse(false);
+
+        log.debug(
+                "dashscope_image_to_image called: imageUrl='{}', prompt='{}', model='{}',"
+                        + " size='{}', useBase64='{}'",
+                imageUrl,
+                prompt,
+                finalModel,
+                finalSize,
+                useBase64);
+
+        return Mono.fromCallable(
+                        () -> {
+                            List<MultiModalMessage> messages = new ArrayList<>();
+
+                            MultiModalMessage systemMessage =
+                                    MultiModalMessage.builder()
+                                            .role(Role.SYSTEM.getValue())
+                                            .content(
+                                                    List.of(
+                                                            Map.of(
+                                                                    "text",
+                                                                    "You are a helpful"
+                                                                            + " assistant.")))
+                                            .build();
+
+                            List<Map<String, Object>> content = new ArrayList<>();
+                            content.add(
+                                    Map.of("image", MediaUtils.urlToProtocolUrl(imageUrl)));
+                            content.add(Map.of("text", prompt));
+
+                            MultiModalMessage userMessage =
+                                    MultiModalMessage.builder()
+                                            .role(Role.USER.getValue())
+                                            .content(content)
+                                            .build();
+
+                            messages.add(systemMessage);
+                            messages.add(userMessage);
+
+                            MultiModalConversationParam param =
+                                    MultiModalConversationParam.builder()
+                                            .apiKey(this.apiKey)
+                                            .model(finalModel)
+                                            .messages(messages)
+                                            .header("user-agent", Version.getUserAgent())
+                                            .parameter("size", finalSize)
+                                            .build();
+
+                            MultiModalConversation conv = new MultiModalConversation();
+                            MultiModalConversationResult result = conv.call(param);
+
+                            // Extract image URL from response
+                            String resultImageUrl =
+                                    Optional.ofNullable(result)
+                                            .map(MultiModalConversationResult::getOutput)
+                                            .map(MultiModalConversationOutput::getChoices)
+                                            .flatMap(
+                                                    choices -> choices.stream().findFirst())
+                                            .map(MultiModalConversationOutput.Choice::getMessage)
+                                            .map(MultiModalMessage::getContent)
+                                            .flatMap(
+                                                    contents -> contents.stream().findFirst())
+                                            .map(m -> m.get("image"))
+                                            .map(Object::toString)
+                                            .orElse(null);
+
+                            if (resultImageUrl == null || resultImageUrl.isEmpty()) {
+                                // Fallback: check if text response (error message from model)
+                                String errorText =
+                                        Optional.ofNullable(result)
+                                                .map(MultiModalConversationResult::getOutput)
+                                                .map(MultiModalConversationOutput::getChoices)
+                                                .flatMap(c -> c.stream().findFirst())
+                                                .map(MultiModalConversationOutput.Choice::getMessage)
+                                                .map(MultiModalMessage::getContent)
+                                                .flatMap(c -> c.stream().findFirst())
+                                                .map(m -> m.get("text"))
+                                                .map(Object::toString)
+                                                .orElse(null);
+                                log.error(
+                                        "No image URL returned from image-to-image."
+                                                + " Response text: {}",
+                                        errorText);
+                                return ToolResultBlock.error(
+                                        "Failed to generate image: "
+                                                + (errorText != null
+                                                        ? errorText
+                                                        : "no image in response"));
+                            }
+
+                            List<ContentBlock> contentBlocks = new ArrayList<>();
+                            if (finalUseBase64) {
+                                String mediaType;
+                                String data;
+                                try {
+                                    mediaType = MediaUtils.determineMediaType(resultImageUrl);
+                                    data = MediaUtils.downloadUrlToBase64(resultImageUrl);
+                                } catch (IOException e) {
+                                    log.error("Failed to download generated image.");
+                                    return ToolResultBlock.error(e.getMessage());
+                                }
+                                if (data == null || data.trim().isEmpty()) {
+                                    return ToolResultBlock.error(
+                                            "Failed to convert image to base64.");
+                                }
+                                contentBlocks.add(
+                                        ImageBlock.builder()
+                                                .source(
+                                                        Base64Source.builder()
+                                                                .mediaType(mediaType)
+                                                                .data(data)
+                                                                .build())
+                                                .build());
+                            } else {
+                                contentBlocks.add(
+                                        ImageBlock.builder()
+                                                .source(
+                                                        URLSource.builder()
+                                                                .url(resultImageUrl)
+                                                                .build())
+                                                .build());
+                            }
+                            return ToolResultBlock.of(contentBlocks);
+                        })
+                .onErrorResume(
+                        e -> {
+                            log.error(
+                                    "Failed to generate image from image '{}'",
+                                    e.getMessage(),
+                                    e);
+                            return Mono.just(ToolResultBlock.error(e.getMessage()));
+                        });
+    }
+
     /**
      * Generate text based on the given images.
      *

From 2fbda7fd7851a9e40257c9d8eb1d08193d7f50b6 Mon Sep 17 00:00:00 2001
From: TanzJ <im.tanzj@live.com>
Date: Sat, 5 Sep 2026 14:32:44 +0800
Subject: [PATCH 2/6] feat(dashscope): refine image-edit model guards and input
 handling for dashscope_image_to_image

- default the edit model to qwen-image-edit instead of a text-to-image model

- reject models that cannot consume an input image on the multimodal-generation endpoint locally, with an actionable hint, so the agent does not silently fall back to text-to-image

- drop the size parameter for models that do not support an explicit output resolution (plus / max / 2.0 series only)

- inline an existing local file as a Base64 data URL, since this endpoint rejects file://

- keep the request to a single user message, which the endpoint requires, and surface the model-side text refusal as the error message
---
 .../tool/DashScopeMultiModalTool.java         | 174 +++++++++++++-----
 1 file changed, 131 insertions(+), 43 deletions(-)

diff --git a/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/main/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalTool.java b/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/main/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalTool.java
index ae8a76f49f..b3e356dbfa 100644
--- a/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/main/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalTool.java
+++ b/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/main/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalTool.java
@@ -93,6 +93,13 @@ public class DashScopeMultiModalTool {
 
     private static final Logger log = LoggerFactory.getLogger(DashScopeMultiModalTool.class);
 
+    /**
+     * Default model of {@code dashscope_image_to_image}. It has to be an edit model: the pure
+     * text-to-image models of the same family reject an {@code input.messages} payload carrying an
+     * image.
+     */
+    private static final String DEFAULT_IMAGE_EDIT_MODEL = "qwen-image-edit";
+
     /**
      * DashScope API key.
      */
@@ -239,26 +246,33 @@ public Mono<ToolResultBlock> dashscopeTextToImage(
     /**
      * Edit or transform an image based on a text prompt and an input image.
      *
-     * @param imageUrl      The URL, local file path, or Base64 data URL of the input image to edit.
+     * @param imageUrl      The public URL, oss:// URL, local file path, or Base64 data URL of the
+     *                      input image to edit.
      * @param prompt        The text prompt describing the desired edit or transformation.
-     * @param model         The model to use, e.g., 'qwen-image'.
-     * @param size          Size of the output image, e.g., '1024*1024'.
+     * @param model         The image-edit model to use, e.g., 'qwen-image-edit'.
+     * @param size          Size of the output image, e.g., '1024*1024'. Only the 'plus', 'max'
+     *                      and 'qwen-image-2.0' series support it.
      * @param useBase64     Whether to return image as base64 data instead of URL.
      * @return A ToolResultBlock containing the generated image url/base64 or error message.
      */
     @Tool(
             name = "dashscope_image_to_image",
             description =
-                    "Edit or transform an image based on a text prompt and an input image."
-                            + " Returns the edited image as URL or base64.")
+                    "Edit or transform an existing image based on a text prompt and an input"
+                            + " image. The input image must be reachable by the service: a public"
+                            + " http(s) URL (the address an uploaded attachment is served from),"
+                            + " an oss:// URL or a Base64 data URL. A path inside the sandbox"
+                            + " workspace is not readable by this tool, so never invent one - ask"
+                            + " for a link instead. Returns the edited image as URL or base64."
+                            + " Use dashscope_text_to_image when there is no input image.")
     public Mono<ToolResultBlock> dashscopeImageToImage(
             @ToolParam(
                             name = "image_url",
                             description =
                                     "The URL, local file path or Base64 data URL (the format"
-                                        + " pattern is data:[MIME_type];base64,{base64_image},"
-                                        + " e.g., 'data:image/png;base64,iVBORw0KGgo...') of"
-                                        + " the input image to edit")
+                                            + " pattern is data:[MIME_type];base64,{base64_image},"
+                                            + " e.g., 'data:image/png;base64,iVBORw0KGgo...') of"
+                                            + " the input image to edit")
                     String imageUrl,
             @ToolParam(
                             name = "prompt",
@@ -268,13 +282,21 @@ public Mono<ToolResultBlock> dashscopeImageToImage(
                     String prompt,
             @ToolParam(
                             name = "model",
-                            description = "The model to use, e.g., 'qwen-image'.",
+                            description =
+                                    "The image-edit model to use, e.g., 'qwen-image-edit',"
+                                            + " 'qwen-image-edit-plus', 'qwen-image-edit-max',"
+                                            + " 'qwen-image-2.0-pro'. Text-to-image models such as"
+                                            + " 'qwen-image' or 'wanx-v1' take no image input.",
                             required = false)
                     String model,
             @ToolParam(
                             name = "size",
                             description =
-                                    "Size of the output image, e.g., '1024*1024', '1280*1280'.",
+                                    "Size of the output image, e.g., '1024*1024', '1280*1280'. Only"
+                                            + " supported by 'qwen-image-edit-plus',"
+                                            + " 'qwen-image-edit-max' and the 'qwen-image-2.0'"
+                                            + " series; otherwise the resolution follows the input"
+                                            + " image.",
                             required = false)
                     String size,
             @ToolParam(
@@ -284,9 +306,10 @@ public Mono<ToolResultBlock> dashscopeImageToImage(
                     Boolean useBase64) {
 
         String finalModel =
-                Optional.ofNullable(model).filter(s -> !s.trim().isEmpty()).orElse("qwen-image");
-        String finalSize =
-                Optional.ofNullable(size).filter(s -> !s.trim().isEmpty()).orElse("1024*1024");
+                Optional.ofNullable(model)
+                        .filter(s -> !s.trim().isEmpty())
+                        .orElse(DEFAULT_IMAGE_EDIT_MODEL);
+        String finalSize = resolveOutputSize(finalModel, size);
         Boolean finalUseBase64 = Optional.ofNullable(useBase64).orElse(false);
 
         log.debug(
@@ -298,24 +321,21 @@ public Mono<ToolResultBlock> dashscopeImageToImage(
                 finalSize,
                 useBase64);
 
+        if (rejectsImageInput(finalModel)) {
+            log.error(
+                    "dashscope_image_to_image rejected model '{}': it takes no image input on this"
+                            + " endpoint",
+                    finalModel);
+            return Mono.just(ToolResultBlock.error(unsupportedEditModelMessage(finalModel)));
+        }
+
         return Mono.fromCallable(
                         () -> {
-                            List<MultiModalMessage> messages = new ArrayList<>();
-
-                            MultiModalMessage systemMessage =
-                                    MultiModalMessage.builder()
-                                            .role(Role.SYSTEM.getValue())
-                                            .content(
-                                                    List.of(
-                                                            Map.of(
-                                                                    "text",
-                                                                    "You are a helpful"
-                                                                            + " assistant.")))
-                                            .build();
-
+                            // This endpoint takes exactly one message and its role must be `user`.
+                            // A leading system message, or any second message, is rejected with
+                            // "Input should be 'user'" / "messages parameter length invalid".
                             List<Map<String, Object>> content = new ArrayList<>();
-                            content.add(
-                                    Map.of("image", MediaUtils.urlToProtocolUrl(imageUrl)));
+                            content.add(Map.of("image", toEditableImageRef(imageUrl)));
                             content.add(Map.of("text", prompt));
 
                             MultiModalMessage userMessage =
@@ -323,18 +343,20 @@ public Mono<ToolResultBlock> dashscopeImageToImage(
                                             .role(Role.USER.getValue())
                                             .content(content)
                                             .build();
+                            List<MultiModalMessage> messages = List.of(userMessage);
 
-                            messages.add(systemMessage);
-                            messages.add(userMessage);
-
-                            MultiModalConversationParam param =
+                            var builder =
                                     MultiModalConversationParam.builder()
                                             .apiKey(this.apiKey)
                                             .model(finalModel)
                                             .messages(messages)
-                                            .header("user-agent", Version.getUserAgent())
-                                            .parameter("size", finalSize)
-                                            .build();
+                                            .header("user-agent", Version.getUserAgent());
+                            // An unsupported or empty `size` fails the whole request, so the entry
+                            // is only added when the model accepts an explicit resolution.
+                            if (finalSize != null) {
+                                builder.parameter("size", finalSize);
+                            }
+                            MultiModalConversationParam param = builder.build();
 
                             MultiModalConversation conv = new MultiModalConversation();
                             MultiModalConversationResult result = conv.call(param);
@@ -344,12 +366,10 @@ public Mono<ToolResultBlock> dashscopeImageToImage(
                                     Optional.ofNullable(result)
                                             .map(MultiModalConversationResult::getOutput)
                                             .map(MultiModalConversationOutput::getChoices)
-                                            .flatMap(
-                                                    choices -> choices.stream().findFirst())
+                                            .flatMap(choices -> choices.stream().findFirst())
                                             .map(MultiModalConversationOutput.Choice::getMessage)
                                             .map(MultiModalMessage::getContent)
-                                            .flatMap(
-                                                    contents -> contents.stream().findFirst())
+                                            .flatMap(contents -> contents.stream().findFirst())
                                             .map(m -> m.get("image"))
                                             .map(Object::toString)
                                             .orElse(null);
@@ -361,7 +381,9 @@ public Mono<ToolResultBlock> dashscopeImageToImage(
                                                 .map(MultiModalConversationResult::getOutput)
                                                 .map(MultiModalConversationOutput::getChoices)
                                                 .flatMap(c -> c.stream().findFirst())
-                                                .map(MultiModalConversationOutput.Choice::getMessage)
+                                                .map(
+                                                        MultiModalConversationOutput.Choice
+                                                                ::getMessage)
                                                 .map(MultiModalMessage::getContent)
                                                 .flatMap(c -> c.stream().findFirst())
                                                 .map(m -> m.get("text"))
@@ -415,13 +437,79 @@ public Mono<ToolResultBlock> dashscopeImageToImage(
                 .onErrorResume(
                         e -> {
                             log.error(
-                                    "Failed to generate image from image '{}'",
-                                    e.getMessage(),
-                                    e);
+                                    "Failed to generate image from image '{}'", e.getMessage(), e);
                             return Mono.just(ToolResultBlock.error(e.getMessage()));
                         });
     }
 
+    /**
+     * Resolve the {@code size} parameter of an edit request. The base {@code qwen-image-edit} model
+     * has no configurable output resolution and rejects the parameter, so it is dropped with a
+     * warning instead of failing the whole call.
+     */
+    private static String resolveOutputSize(String model, String size) {
+        String requested = Optional.ofNullable(size).filter(s -> !s.trim().isEmpty()).orElse(null);
+        if (requested == null) {
+            return null;
+        }
+        if (!supportsOutputSize(model)) {
+            log.warn(
+                    "dashscope_image_to_image drops size='{}' for model '{}': the output"
+                            + " resolution follows the input image",
+                    requested,
+                    model);
+            return null;
+        }
+        return requested;
+    }
+
+    /** Whether the model accepts an explicit output resolution. */
+    private static boolean supportsOutputSize(String model) {
+        String name = model.toLowerCase();
+        return name.startsWith("qwen-image-edit-plus")
+                || name.startsWith("qwen-image-edit-max")
+                || name.startsWith("qwen-image-2.0");
+    }
+
+    /**
+     * Whether the model cannot consume an input image on this endpoint: the wan family, whose image
+     * editing runs on a different asynchronous task API, and the text-to-image members of the
+     * qwen-image family.
+     */
+    private static boolean rejectsImageInput(String model) {
+        String name = model.toLowerCase();
+        if (name.startsWith("wan")) {
+            return true;
+        }
+        return name.startsWith("qwen-image")
+                && !name.contains("edit")
+                && !name.startsWith("qwen-image-2.0");
+    }
+
+    /** Actionable hint returned instead of an opaque service-side parameter error. */
+    private static String unsupportedEditModelMessage(String model) {
+        return "Model '"
+                + model
+                + "' cannot edit an input image with this tool. Omit the model to"
+                + " use '"
+                + DEFAULT_IMAGE_EDIT_MODEL
+                + "', or pass an edit model:"
+                + " 'qwen-image-edit-plus', 'qwen-image-edit-max', 'qwen-image-2.0-pro'."
+                + " dashscope_text_to_image is the right tool when there is no input image.";
+    }
+
+    /**
+     * Normalize the input image reference. The documented formats are a public http(s) URL, an
+     * {@code oss://} URL returned by the upload API, or a Base64 data URL; an existing local file
+     * is inlined as Base64 rather than sent as a {@code file://} URL, which the endpoint rejects.
+     */
+    private static String toEditableImageRef(String imageUrl) throws IOException {
+        if (MediaUtils.isFileExists(imageUrl)) {
+            return MediaUtils.urlToBase64DataUrl(imageUrl);
+        }
+        return imageUrl;
+    }
+
     /**
      * Generate text based on the given images.
      *

From 4d07873343c0d9d7dd17e5509b558591fdb9ac4b Mon Sep 17 00:00:00 2001
From: TanzJ <im.tanzj@live.com>
Date: Sat, 5 Sep 2026 15:10:29 +0800
Subject: [PATCH 3/6] test(dashscope): cover dashscope_image_to_image request
 shape, guards and result blocks

Adds 11 unit tests plus a nested ImageEditGuardTests block that exercises the private model predicates by reflection. The request-shape tests assert the built MultiModalConversationParam (model fallback for a blank model, single user message, image then text content order), all four input forms (http URL, local path, oss URL, base64 data URL), the output-size capability gate, and the refusal / empty-response / error paths. The unsupported-model case asserts no conversation object is constructed at all.

Also adds two E2E cases: a real edit call and a zero-cost guard check that returns before the request is built.
---
 .../tool/DashScopeMultiModalToolTest.java     | 391 ++++++++++++++++++
 .../tool/DashScopeMultiModalToolE2ETest.java  |  45 ++
 2 files changed, 436 insertions(+)

diff --git a/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/test/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalToolTest.java b/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/test/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalToolTest.java
index 02d9bbd7c2..e9182fe28a 100644
--- a/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/test/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalToolTest.java
+++ b/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/test/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalToolTest.java
@@ -17,8 +17,10 @@
 
 import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertInstanceOf;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.anyInt;
@@ -55,6 +57,7 @@
 import com.alibaba.dashscope.audio.tts.SpeechSynthesizer;
 import com.alibaba.dashscope.common.MultiModalMessage;
 import com.alibaba.dashscope.common.ResultCallback;
+import com.alibaba.dashscope.common.Role;
 import io.agentscope.core.formatter.MediaUtils;
 import io.agentscope.core.message.AudioBlock;
 import io.agentscope.core.message.Base64Source;
@@ -74,6 +77,7 @@
 import java.nio.file.Path;
 import java.util.List;
 import java.util.Map;
+import java.util.concurrent.atomic.AtomicReference;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Nested;
@@ -347,6 +351,393 @@ void testTextToImageError() {
         mockCtor.close();
     }
 
+    /**
+     * Mocks the multimodal-generation client that {@code dashscope_image_to_image} talks to.
+     *
+     * @param captured        receives the request param so a test can assert on the outgoing call
+     * @param responseContent content map of the single choice; null leaves the output empty
+     */
+    private MockedConstruction<MultiModalConversation> mockImageEditConversation(
+            AtomicReference<MultiModalConversationParam> captured,
+            Map<String, Object> responseContent) {
+        return mockConstruction(
+                MultiModalConversation.class,
+                (mock, context) -> {
+                    MultiModalConversationResult mockResult =
+                            mock(MultiModalConversationResult.class);
+                    MultiModalConversationOutput mockOutput =
+                            mock(MultiModalConversationOutput.class);
+
+                    when(mockResult.getOutput()).thenReturn(mockOutput);
+                    if (responseContent != null) {
+                        MultiModalConversationOutput.Choice choice =
+                                new MultiModalConversationOutput.Choice();
+                        choice.setMessage(
+                                MultiModalMessage.builder()
+                                        .content(List.of(responseContent))
+                                        .build());
+                        choice.setFinishReason("stop");
+                        when(mockOutput.getChoices()).thenReturn(List.of(choice));
+                    }
+                    when(mock.call(any(MultiModalConversationParam.class)))
+                            .thenAnswer(
+                                    invocation -> {
+                                        captured.set(invocation.getArgument(0));
+                                        return mockResult;
+                                    });
+                });
+    }
+
+    @Test
+    @DisplayName("Image to image with web url")
+    void testImageToImageWithUrl() {
+        AtomicReference<MultiModalConversationParam> captured = new AtomicReference<>();
+        MockedConstruction<MultiModalConversation> mockConv =
+                mockImageEditConversation(
+                        captured, Map.of("image", TEST_IMAGE0_URL, "text", "unused"));
+
+        Mono<ToolResultBlock> result =
+                multiModalTool.dashscopeImageToImage(
+                        TEST_IMAGE0_URL, "Make it night-time", "qwen-image-edit", null, false);
+
+        StepVerifier.create(result)
+                .assertNext(
+                        toolResultBlock -> {
+                            assertNotNull(toolResultBlock);
+                            assertEquals(1, toolResultBlock.getOutput().size());
+                            assertInstanceOf(ImageBlock.class, toolResultBlock.getOutput().get(0));
+                            ImageBlock imageBlock = (ImageBlock) toolResultBlock.getOutput().get(0);
+                            assertInstanceOf(URLSource.class, imageBlock.getSource());
+                            assertEquals(
+                                    TEST_IMAGE0_URL, ((URLSource) imageBlock.getSource()).getUrl());
+                        })
+                .verifyComplete();
+
+        mockConv.close();
+
+        // The endpoint takes exactly one `user` message carrying the image then the prompt.
+        MultiModalConversationParam param = captured.get();
+        assertNotNull(param);
+        assertEquals("qwen-image-edit", param.getModel());
+        assertEquals(1, param.getMessages().size());
+        MultiModalMessage message =
+                assertInstanceOf(MultiModalMessage.class, param.getMessages().get(0));
+        assertEquals(Role.USER.getValue(), message.getRole());
+        assertEquals(TEST_IMAGE0_URL, message.getContent().get(0).get("image"));
+        assertEquals("Make it night-time", message.getContent().get(1).get("text"));
+    }
+
+    @Test
+    @DisplayName("Image to image defaults to the edit model when model is blank")
+    void testImageToImageDefaultModel() {
+        AtomicReference<MultiModalConversationParam> captured = new AtomicReference<>();
+        MockedConstruction<MultiModalConversation> mockConv =
+                mockImageEditConversation(captured, Map.of("image", TEST_IMAGE0_URL));
+
+        multiModalTool
+                .dashscopeImageToImage(TEST_IMAGE0_URL, "Colorize this sketch", "   ", null, null)
+                .block();
+        mockConv.close();
+
+        assertEquals("qwen-image-edit", captured.get().getModel());
+    }
+
+    @Test
+    @DisplayName("Image to image keeps size for models that support an output resolution")
+    void testImageToImageSizeIsSentForSupportedModel() {
+        AtomicReference<MultiModalConversationParam> captured = new AtomicReference<>();
+        MockedConstruction<MultiModalConversation> mockConv =
+                mockImageEditConversation(captured, Map.of("image", TEST_IMAGE0_URL));
+
+        StepVerifier.create(
+                        multiModalTool.dashscopeImageToImage(
+                                TEST_IMAGE0_URL,
+                                "Colorize",
+                                "qwen-image-edit-plus",
+                                "1280*1280",
+                                false))
+                .expectNextCount(1)
+                .verifyComplete();
+        mockConv.close();
+
+        assertEquals("1280*1280", captured.get().getParameters().get("size"));
+    }
+
+    @Test
+    @DisplayName("Image to image drops size for the base edit model instead of failing")
+    void testImageToImageSizeIsDroppedForBaseModel() {
+        AtomicReference<MultiModalConversationParam> captured = new AtomicReference<>();
+        MockedConstruction<MultiModalConversation> mockConv =
+                mockImageEditConversation(captured, Map.of("image", TEST_IMAGE0_URL));
+
+        Mono<ToolResultBlock> result =
+                multiModalTool.dashscopeImageToImage(
+                        TEST_IMAGE0_URL, "Colorize", "qwen-image-edit", "1280*1280", false);
+
+        StepVerifier.create(result)
+                .assertNext(
+                        toolResultBlock ->
+                                assertInstanceOf(
+                                        ImageBlock.class, toolResultBlock.getOutput().get(0)))
+                .verifyComplete();
+        mockConv.close();
+
+        // getParameters() also carries the typed fields, so only `size` is asserted on.
+        assertNull(captured.get().getParameters().get("size"));
+    }
+
+    @Test
+    @DisplayName("Image to image use Base64 mode")
+    void testImageToImageBase64Mode() throws IOException {
+        AtomicReference<MultiModalConversationParam> captured = new AtomicReference<>();
+        MockedConstruction<MultiModalConversation> mockConv =
+                mockImageEditConversation(captured, Map.of("image", TEST_IMAGE0_URL));
+
+        MockedStatic<MediaUtils> mockMediaUtils = mockStatic(MediaUtils.class);
+        when(MediaUtils.determineMediaType(anyString())).thenReturn("image/png");
+        when(MediaUtils.downloadUrlToBase64(anyString())).thenReturn(TEST_BASE64_DATA);
+
+        Mono<ToolResultBlock> result =
+                multiModalTool.dashscopeImageToImage(
+                        TEST_IMAGE0_URL, "Colorize", "qwen-image-edit", null, true);
+
+        StepVerifier.create(result)
+                .assertNext(
+                        toolResultBlock -> {
+                            ImageBlock imageBlock = (ImageBlock) toolResultBlock.getOutput().get(0);
+                            assertInstanceOf(Base64Source.class, imageBlock.getSource());
+                            assertEquals(
+                                    "image/png",
+                                    ((Base64Source) imageBlock.getSource()).getMediaType());
+                            assertEquals(
+                                    TEST_BASE64_DATA,
+                                    ((Base64Source) imageBlock.getSource()).getData());
+                        })
+                .verifyComplete();
+
+        mockMediaUtils.close();
+        mockConv.close();
+    }
+
+    @Test
+    @DisplayName("Image to image inlines a local file as a Base64 data URL")
+    void testImageToImageWithLocalFile() throws IOException {
+        AtomicReference<MultiModalConversationParam> captured = new AtomicReference<>();
+        MockedConstruction<MultiModalConversation> mockConv =
+                mockImageEditConversation(captured, Map.of("image", TEST_IMAGE0_URL));
+
+        // This endpoint rejects file:// URLs, unlike the vision models.
+        MockedStatic<MediaUtils> mockMediaUtils = mockStatic(MediaUtils.class);
+        when(MediaUtils.isFileExists(TEST_IMAGE_PATH)).thenReturn(true);
+        when(MediaUtils.urlToBase64DataUrl(TEST_IMAGE_PATH)).thenReturn(TEST_IMAGE_BASE64_DATA_URL);
+
+        StepVerifier.create(
+                        multiModalTool.dashscopeImageToImage(
+                                TEST_IMAGE_PATH, "Colorize", "qwen-image-edit", null, false))
+                .expectNextCount(1)
+                .verifyComplete();
+        mockMediaUtils.close();
+        mockConv.close();
+
+        MultiModalMessage message = (MultiModalMessage) captured.get().getMessages().get(0);
+        assertEquals(TEST_IMAGE_BASE64_DATA_URL, message.getContent().get(0).get("image"));
+    }
+
+    @Test
+    @DisplayName("Image to image with base64 data url input")
+    void testImageToImageWithBase64DataUrlInput() {
+        AtomicReference<MultiModalConversationParam> captured = new AtomicReference<>();
+        MockedConstruction<MultiModalConversation> mockConv =
+                mockImageEditConversation(captured, Map.of("image", TEST_IMAGE0_URL));
+
+        StepVerifier.create(
+                        multiModalTool.dashscopeImageToImage(
+                                TEST_IMAGE_BASE64_DATA_URL,
+                                "Colorize",
+                                "qwen-image-edit",
+                                null,
+                                false))
+                .expectNextCount(1)
+                .verifyComplete();
+        mockConv.close();
+
+        MultiModalMessage message = (MultiModalMessage) captured.get().getMessages().get(0);
+        assertEquals(TEST_IMAGE_BASE64_DATA_URL, message.getContent().get(0).get("image"));
+    }
+
+    @Test
+    @DisplayName(
+            "Should return an actionable hint and skip the call when the model takes no image"
+                    + " input")
+    void testImageToImageUnsupportedModel() {
+        AtomicReference<MultiModalConversationParam> captured = new AtomicReference<>();
+        MockedConstruction<MultiModalConversation> mockConv =
+                mockImageEditConversation(captured, Map.of("image", TEST_IMAGE0_URL));
+
+        Mono<ToolResultBlock> result =
+                multiModalTool.dashscopeImageToImage(
+                        TEST_IMAGE0_URL, "Colorize", "wanx2.1-t2i-turbo", null, false);
+
+        StepVerifier.create(result)
+                .assertNext(
+                        toolResultBlock -> {
+                            String text =
+                                    ((TextBlock) toolResultBlock.getOutput().get(0)).getText();
+                            assertTrue(text.contains("wanx2.1-t2i-turbo"));
+                            assertTrue(text.contains("qwen-image-edit"));
+                            assertTrue(text.contains("dashscope_text_to_image"));
+                        })
+                .verifyComplete();
+
+        // Guarded locally: no request must reach the service.
+        assertTrue(mockConv.constructed().isEmpty());
+
+        mockConv.close();
+    }
+
+    @Test
+    @DisplayName(
+            "Should surface the model-side refusal when the image to image response has no"
+                    + " image")
+    void testImageToImageResponseCarriesRefusalText() {
+        AtomicReference<MultiModalConversationParam> captured = new AtomicReference<>();
+        MockedConstruction<MultiModalConversation> mockConv =
+                mockImageEditConversation(captured, Map.of("text", "Image edited is not valid"));
+
+        Mono<ToolResultBlock> result =
+                multiModalTool.dashscopeImageToImage(
+                        TEST_IMAGE0_URL, "Colorize", "qwen-image-edit", null, false);
+
+        StepVerifier.create(result)
+                .assertNext(
+                        toolResultBlock -> {
+                            assertNotNull(toolResultBlock);
+                            assertEquals(1, toolResultBlock.getOutput().size());
+                            assertInstanceOf(TextBlock.class, toolResultBlock.getOutput().get(0));
+                            assertEquals(
+                                    String.format(
+                                            "Error: Failed to generate image: Image edited is not"
+                                                    + " valid"),
+                                    ((TextBlock) toolResultBlock.getOutput().get(0)).getText());
+                        })
+                .verifyComplete();
+
+        mockConv.close();
+    }
+
+    @Test
+    @DisplayName("Should return error TextBlock when image to image response has no content")
+    void testImageToImageResponseEmpty() {
+        AtomicReference<MultiModalConversationParam> captured = new AtomicReference<>();
+        MockedConstruction<MultiModalConversation> mockConv =
+                mockImageEditConversation(captured, null);
+
+        Mono<ToolResultBlock> result =
+                multiModalTool.dashscopeImageToImage(
+                        TEST_IMAGE0_URL, "Colorize", "qwen-image-edit", null, false);
+
+        StepVerifier.create(result)
+                .assertNext(
+                        toolResultBlock -> {
+                            assertNotNull(toolResultBlock);
+                            assertEquals(1, toolResultBlock.getOutput().size());
+                            assertInstanceOf(TextBlock.class, toolResultBlock.getOutput().get(0));
+                            assertEquals(
+                                    String.format(
+                                            "Error: Failed to generate image: no image in"
+                                                    + " response"),
+                                    ((TextBlock) toolResultBlock.getOutput().get(0)).getText());
+                        })
+                .verifyComplete();
+
+        mockConv.close();
+    }
+
+    @Test
+    @DisplayName("Should return error TextBlock when call image to image occurs error")
+    void testImageToImageError() {
+        MockedConstruction<MultiModalConversation> mockConv =
+                mockConstruction(
+                        MultiModalConversation.class,
+                        (mock, context) ->
+                                when(mock.call(any(MultiModalConversationParam.class)))
+                                        .thenThrow(TEST_ERROR));
+
+        Mono<ToolResultBlock> result =
+                multiModalTool.dashscopeImageToImage(
+                        TEST_IMAGE0_URL, "Colorize", "qwen-image-edit", null, false);
+
+        StepVerifier.create(result)
+                .assertNext(
+                        toolResultBlock -> {
+                            assertNotNull(toolResultBlock);
+                            assertEquals(1, toolResultBlock.getOutput().size());
+                            assertInstanceOf(TextBlock.class, toolResultBlock.getOutput().get(0));
+                            assertEquals(
+                                    String.format("Error: %s", TEST_ERROR.getMessage()),
+                                    ((TextBlock) toolResultBlock.getOutput().get(0)).getText());
+                        })
+                .verifyComplete();
+
+        mockConv.close();
+    }
+
+    @Nested
+    @DisplayName("Image edit model capability guards")
+    class ImageEditGuardTests {
+
+        /** Use reflection to call a private static predicate for unit testing. */
+        private boolean invokeStatic(String methodName, String model) throws Exception {
+            Method method =
+                    DashScopeMultiModalTool.class.getDeclaredMethod(methodName, String.class);
+            method.setAccessible(true);
+            return (boolean) method.invoke(null, model);
+        }
+
+        @Test
+        @DisplayName("Text-to-image and wan models cannot edit an input image")
+        void testRejectsImageInput() throws Exception {
+            assertTrue(invokeStatic("rejectsImageInput", "wanx-v1"));
+            assertTrue(invokeStatic("rejectsImageInput", "wan2.6-i2v-flash"));
+            assertTrue(invokeStatic("rejectsImageInput", "qwen-image"));
+            assertTrue(invokeStatic("rejectsImageInput", "qwen-image-plus"));
+            assertFalse(invokeStatic("rejectsImageInput", "qwen-image-edit"));
+            assertFalse(invokeStatic("rejectsImageInput", "Qwen-Image-Edit-Max"));
+            assertFalse(invokeStatic("rejectsImageInput", "qwen-image-2.0"));
+            assertFalse(invokeStatic("rejectsImageInput", "qwen-image-2.0-pro"));
+        }
+
+        @Test
+        @DisplayName("Only plus / max / 2.0 series accept an output resolution")
+        void testSupportsOutputSize() throws Exception {
+            assertFalse(invokeStatic("supportsOutputSize", "qwen-image-edit"));
+            assertTrue(invokeStatic("supportsOutputSize", "qwen-image-edit-plus"));
+            assertTrue(invokeStatic("supportsOutputSize", "qwen-image-edit-max"));
+            assertTrue(invokeStatic("supportsOutputSize", "qwen-image-2.0"));
+            assertTrue(invokeStatic("supportsOutputSize", "qwen-image-2.0-pro"));
+        }
+
+        @Test
+        @DisplayName("Blank or unsupported size is resolved to no parameter")
+        void testResolveOutputSize() throws Exception {
+            Method method =
+                    DashScopeMultiModalTool.class.getDeclaredMethod(
+                            "resolveOutputSize", String.class, String.class);
+            method.setAccessible(true);
+
+            assertNull(
+                    (String) method.invoke(null, "qwen-image-edit-plus", null),
+                    "absent size stays absent");
+            assertNull(
+                    (String) method.invoke(null, "qwen-image-edit-plus", "  "),
+                    "blank size is dropped");
+            assertNull(
+                    (String) method.invoke(null, "qwen-image-edit", "1024*1024"),
+                    "unsupported model drops the size");
+            assertEquals("1024*1024", method.invoke(null, "qwen-image-edit-max", "1024*1024"));
+        }
+    }
+
     @Test
     @DisplayName("Image to text with web url")
     void testImageToTextWithUrl() {
diff --git a/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-e2e-tests/src/test/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalToolE2ETest.java b/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-e2e-tests/src/test/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalToolE2ETest.java
index 01e0fa81a4..f0fac2d5c2 100644
--- a/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-e2e-tests/src/test/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalToolE2ETest.java
+++ b/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-e2e-tests/src/test/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalToolE2ETest.java
@@ -18,6 +18,7 @@
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertInstanceOf;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
 
 import io.agentscope.core.e2e.E2ETestCondition;
 import io.agentscope.core.formatter.MediaUtils;
@@ -150,6 +151,50 @@ void testTextToImageResponseMultiUrls() {
                 .verifyComplete();
     }
 
+    @Test
+    @DisplayName("Image to image with web url")
+    void testImageToImageWithUrl() {
+        Mono<ToolResultBlock> result =
+                multiModalTool.dashscopeImageToImage(
+                        TEST_IMAGE_URL,
+                        "Repaint the scene as a watercolour painting",
+                        null,
+                        null,
+                        false);
+
+        StepVerifier.create(result)
+                .assertNext(
+                        toolResultBlock -> {
+                            assertNotNull(toolResultBlock);
+                            assertEquals(1, toolResultBlock.getOutput().size());
+                            assertInstanceOf(ImageBlock.class, toolResultBlock.getOutput().get(0));
+                            ImageBlock imageBlock = (ImageBlock) toolResultBlock.getOutput().get(0);
+                            assertInstanceOf(URLSource.class, imageBlock.getSource());
+                            assertNotNull(((URLSource) imageBlock.getSource()).getUrl());
+                        })
+                .verifyComplete();
+    }
+
+    @Test
+    @DisplayName("Image to image rejects a model that takes no image input")
+    void testImageToImageUnsupportedModel() {
+        // Guarded before the request is built, so this case costs nothing.
+        Mono<ToolResultBlock> result =
+                multiModalTool.dashscopeImageToImage(
+                        TEST_IMAGE_URL, "Repaint the scene", "wanx-v1", null, false);
+
+        StepVerifier.create(result)
+                .assertNext(
+                        toolResultBlock -> {
+                            assertInstanceOf(TextBlock.class, toolResultBlock.getOutput().get(0));
+                            String text =
+                                    ((TextBlock) toolResultBlock.getOutput().get(0)).getText();
+                            assertTrue(text.contains("wanx-v1"), text);
+                            assertTrue(text.contains("qwen-image-edit"), text);
+                        })
+                .verifyComplete();
+    }
+
     @Test
     @DisplayName("Image to text with web url")
     void testImageToTextWithUrl() {

From 8ed206e9e66170c307e3974e34ef00fbcb48d146 Mon Sep 17 00:00:00 2001
From: TanzJ <im.tanzj@live.com>
Date: Sat, 5 Sep 2026 16:49:31 +0800
Subject: [PATCH 4/6] fix(dashscope): keep dashscope_image_to_image open to
 future image generations

The edit family changed naming with its second generation: qwen-image-2.0 and -pro drop the -edit token, so the guards listed that version as a literal. A later generation therefore matched neither branch and was refused as text-to-image only - a hard outage for a working model, attributed to a reason the message states incorrectly.

Detect the generation by its leading digit instead, so an unreleased model needs no code change, and keep refusing the versionless text-to-image members and the wan family, whose image editing runs on a different task API.

The output-size gate stays an explicit list on purpose, in the opposite direction: an unexpected size fails the whole request, while a dropped one only degrades the resolution to that of the input image.

Also move the model guard ahead of resolveOutputSize, which logged a warning about dropping a size for a request that was about to be rejected without being sent.
---
 .../tool/DashScopeMultiModalTool.java         | 78 +++++++++++++------
 .../tool/DashScopeMultiModalToolTest.java     | 53 ++++++++++++-
 2 files changed, 108 insertions(+), 23 deletions(-)

diff --git a/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/main/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalTool.java b/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/main/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalTool.java
index b3e356dbfa..be89f5c153 100644
--- a/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/main/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalTool.java
+++ b/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/main/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalTool.java
@@ -100,6 +100,15 @@ public class DashScopeMultiModalTool {
      */
     private static final String DEFAULT_IMAGE_EDIT_MODEL = "qwen-image-edit";
 
+    /**
+     * Prefix of the qwen-image family. The first generation names its edit models with an
+     * {@code -edit} token ({@code qwen-image-edit}, {@code -plus}, {@code -max}); every numbered
+     * generation from 2.0 on drops that token and carries the generation instead
+     * ({@code qwen-image-2.0}, {@code qwen-image-2.0-pro}). Both spellings edit an input image,
+     * whereas the versionless {@code qwen-image} / {@code qwen-image-plus} are text-to-image only.
+     */
+    private static final String QWEN_IMAGE_PREFIX = "qwen-image-";
+
     /**
      * DashScope API key.
      */
@@ -250,8 +259,9 @@ public Mono<ToolResultBlock> dashscopeTextToImage(
      *                      input image to edit.
      * @param prompt        The text prompt describing the desired edit or transformation.
      * @param model         The image-edit model to use, e.g., 'qwen-image-edit'.
-     * @param size          Size of the output image, e.g., '1024*1024'. Only the 'plus', 'max'
-     *                      and 'qwen-image-2.0' series support it.
+     * @param size          Size of the output image, e.g., '1024*1024'. Supported by the numbered
+     *                      generations (2.0 and later) and by the first-generation 'plus' and
+     *                      'max' tiers.
      * @param useBase64     Whether to return image as base64 data instead of URL.
      * @return A ToolResultBlock containing the generated image url/base64 or error message.
      */
@@ -285,18 +295,20 @@ public Mono<ToolResultBlock> dashscopeImageToImage(
                             description =
                                     "The image-edit model to use, e.g., 'qwen-image-edit',"
                                             + " 'qwen-image-edit-plus', 'qwen-image-edit-max',"
-                                            + " 'qwen-image-2.0-pro'. Text-to-image models such as"
-                                            + " 'qwen-image' or 'wanx-v1' take no image input.",
+                                            + " 'qwen-image-2.0-pro'. Every numbered generation"
+                                            + " (2.0 and later) edits an input image too."
+                                            + " Text-to-image models such as 'qwen-image' or"
+                                            + " 'wanx-v1' take no image input.",
                             required = false)
                     String model,
             @ToolParam(
                             name = "size",
                             description =
-                                    "Size of the output image, e.g., '1024*1024', '1280*1280'. Only"
-                                            + " supported by 'qwen-image-edit-plus',"
-                                            + " 'qwen-image-edit-max' and the 'qwen-image-2.0'"
-                                            + " series; otherwise the resolution follows the input"
-                                            + " image.",
+                                    "Size of the output image, e.g., '1024*1024', '1280*1280'."
+                                            + " Only supported by 'qwen-image-edit-plus',"
+                                            + " 'qwen-image-edit-max' and the numbered generations"
+                                            + " ('qwen-image-2.0' and later); otherwise the"
+                                            + " resolution follows the input image.",
                             required = false)
                     String size,
             @ToolParam(
@@ -309,9 +321,21 @@ public Mono<ToolResultBlock> dashscopeImageToImage(
                 Optional.ofNullable(model)
                         .filter(s -> !s.trim().isEmpty())
                         .orElse(DEFAULT_IMAGE_EDIT_MODEL);
-        String finalSize = resolveOutputSize(finalModel, size);
         Boolean finalUseBase64 = Optional.ofNullable(useBase64).orElse(false);
 
+        // Rejected before the request is built, so an unusable model costs no call. This also has
+        // to come first: resolving the size of a request that is about to be refused logs a
+        // warning about a parameter that is never sent.
+        if (rejectsImageInput(finalModel)) {
+            log.error(
+                    "dashscope_image_to_image rejected model '{}': it takes no image input on this"
+                            + " endpoint",
+                    finalModel);
+            return Mono.just(ToolResultBlock.error(unsupportedEditModelMessage(finalModel)));
+        }
+
+        String finalSize = resolveOutputSize(finalModel, size);
+
         log.debug(
                 "dashscope_image_to_image called: imageUrl='{}', prompt='{}', model='{}',"
                         + " size='{}', useBase64='{}'",
@@ -321,14 +345,6 @@ public Mono<ToolResultBlock> dashscopeImageToImage(
                 finalSize,
                 useBase64);
 
-        if (rejectsImageInput(finalModel)) {
-            log.error(
-                    "dashscope_image_to_image rejected model '{}': it takes no image input on this"
-                            + " endpoint",
-                    finalModel);
-            return Mono.just(ToolResultBlock.error(unsupportedEditModelMessage(finalModel)));
-        }
-
         return Mono.fromCallable(
                         () -> {
                             // This endpoint takes exactly one message and its role must be `user`.
@@ -466,15 +482,33 @@ private static String resolveOutputSize(String model, String size) {
     /** Whether the model accepts an explicit output resolution. */
     private static boolean supportsOutputSize(String model) {
         String name = model.toLowerCase();
-        return name.startsWith("qwen-image-edit-plus")
-                || name.startsWith("qwen-image-edit-max")
-                || name.startsWith("qwen-image-2.0");
+        // Sending a resolution the model does not accept fails the whole request, so the
+        // first-generation names stay on an explicit list. Numbered generations are covered by
+        // pattern: 2.0 accepts a resolution and there is no evidence a later one drops it.
+        return isNumberedEditGeneration(name)
+                || name.startsWith("qwen-image-edit-plus")
+                || name.startsWith("qwen-image-edit-max");
+    }
+
+    /**
+     * Whether the model belongs to a numbered generation of the image family, e.g.
+     * {@code qwen-image-2.0}, {@code qwen-image-3.0-pro}. Matching the leading digit rather than a
+     * concrete version keeps a model that has not been released yet working.
+     */
+    private static boolean isNumberedEditGeneration(String name) {
+        return name.length() > QWEN_IMAGE_PREFIX.length()
+                && name.startsWith(QWEN_IMAGE_PREFIX)
+                && Character.isDigit(name.charAt(QWEN_IMAGE_PREFIX.length()));
     }
 
     /**
      * Whether the model cannot consume an input image on this endpoint: the wan family, whose image
      * editing runs on a different asynchronous task API, and the text-to-image members of the
      * qwen-image family.
+     *
+     * <p>Anything unrecognized is passed through to the service, which reports the real reason. A
+     * false rejection here would silently remove a capability and attribute it to a cause the
+     * message states incorrectly.
      */
     private static boolean rejectsImageInput(String model) {
         String name = model.toLowerCase();
@@ -483,7 +517,7 @@ private static boolean rejectsImageInput(String model) {
         }
         return name.startsWith("qwen-image")
                 && !name.contains("edit")
-                && !name.startsWith("qwen-image-2.0");
+                && !isNumberedEditGeneration(name);
     }
 
     /** Actionable hint returned instead of an opaque service-side parameter error. */
diff --git a/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/test/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalToolTest.java b/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/test/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalToolTest.java
index e9182fe28a..072ffc6130 100644
--- a/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/test/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalToolTest.java
+++ b/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/test/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalToolTest.java
@@ -463,6 +463,33 @@ void testImageToImageSizeIsSentForSupportedModel() {
         assertEquals("1280*1280", captured.get().getParameters().get("size"));
     }
 
+    @Test
+    @DisplayName("A generation newer than the ones released today is neither blocked nor degraded")
+    void testImageToImageSupportsFutureGenerations() {
+        // The vendor keeps releasing numbered generations of this family. Detecting the generation
+        // by its leading digit rather than by a concrete version has to keep such a model usable,
+        // including an explicit output resolution.
+        AtomicReference<MultiModalConversationParam> captured = new AtomicReference<>();
+        MockedConstruction<MultiModalConversation> mockConv =
+                mockImageEditConversation(captured, Map.of("image", TEST_IMAGE0_URL));
+
+        StepVerifier.create(
+                        multiModalTool.dashscopeImageToImage(
+                                TEST_IMAGE0_URL,
+                                "Colorize",
+                                "qwen-image-3.0-pro",
+                                "1280*1280",
+                                false))
+                .expectNextCount(1)
+                .verifyComplete();
+        mockConv.close();
+
+        MultiModalConversationParam param = captured.get();
+        assertNotNull(param);
+        assertEquals("qwen-image-3.0-pro", param.getModel());
+        assertEquals("1280*1280", param.getParameters().get("size"));
+    }
+
     @Test
     @DisplayName("Image to image drops size for the base edit model instead of failing")
     void testImageToImageSizeIsDroppedForBaseModel() {
@@ -705,16 +732,40 @@ void testRejectsImageInput() throws Exception {
             assertFalse(invokeStatic("rejectsImageInput", "Qwen-Image-Edit-Max"));
             assertFalse(invokeStatic("rejectsImageInput", "qwen-image-2.0"));
             assertFalse(invokeStatic("rejectsImageInput", "qwen-image-2.0-pro"));
+            // Same naming scheme, not released yet: must not be refused by a wrong reason.
+            assertFalse(invokeStatic("rejectsImageInput", "qwen-image-3.0"));
+            assertFalse(invokeStatic("rejectsImageInput", "qwen-image-4.5-max"));
+            // Unrecognized families reach the service, which reports the actual cause.
+            assertFalse(invokeStatic("rejectsImageInput", "some-future-editor"));
         }
 
         @Test
-        @DisplayName("Only plus / max / 2.0 series accept an output resolution")
+        @DisplayName("Plus / max tiers and every numbered generation accept a resolution")
         void testSupportsOutputSize() throws Exception {
             assertFalse(invokeStatic("supportsOutputSize", "qwen-image-edit"));
             assertTrue(invokeStatic("supportsOutputSize", "qwen-image-edit-plus"));
             assertTrue(invokeStatic("supportsOutputSize", "qwen-image-edit-max"));
             assertTrue(invokeStatic("supportsOutputSize", "qwen-image-2.0"));
             assertTrue(invokeStatic("supportsOutputSize", "qwen-image-2.0-pro"));
+            assertTrue(invokeStatic("supportsOutputSize", "qwen-image-3.0"));
+            // An unexpected `size` fails the whole request, so a snapshot of the base model stays
+            // off the list: dropping the parameter only degrades the output resolution.
+            assertFalse(
+                    invokeStatic("supportsOutputSize", "qwen-image-edit-2026-05-22"),
+                    "a dated snapshot of the base model must not send a size");
+        }
+
+        @Test
+        @DisplayName("Only a digit after the family prefix marks a numbered generation")
+        void testNumberedEditGenerationBoundary() throws Exception {
+            assertTrue(invokeStatic("isNumberedEditGeneration", "qwen-image-2.0"));
+            assertTrue(invokeStatic("isNumberedEditGeneration", "qwen-image-3.0-pro"));
+            assertTrue(invokeStatic("isNumberedEditGeneration", "qwen-image-10.0"));
+            assertFalse(invokeStatic("isNumberedEditGeneration", "qwen-image-edit"));
+            assertFalse(invokeStatic("isNumberedEditGeneration", "qwen-image-edit-plus"));
+            // Nothing after the separator, and the family name itself, carry no generation.
+            assertFalse(invokeStatic("isNumberedEditGeneration", "qwen-image-"));
+            assertFalse(invokeStatic("isNumberedEditGeneration", "qwen-image"));
         }
 
         @Test

From 5fa0afdcd306a5d65d96b488f1af6e73cd90ffbf Mon Sep 17 00:00:00 2001
From: TanzJ <im.tanzj@live.com>
Date: Sat, 5 Sep 2026 20:05:36 +0800
Subject: [PATCH 5/6] fix(dashscope): keep user payloads out of the
 dashscope_image_to_image debug log

image_url is an advertised input form as a Base64 data URL, so the previous line wrote the entire encoded image into the log - megabytes per call, and in the clear for anything that ships logs elsewhere. The prompt is user content and has no better claim to being logged; a signed object URL also carries credentials in its query string.

The call site now renders only the reference kind, the reference length and the prompt length, with no prefix of either value, and the method documents that as its logging contract.

Covered by two tests. Note the summarizer is asserted directly rather than through a captured LoggingEvent: the module test classpath has slf4j-api with no binding, so the logger is a NOP and nothing can be captured without adding a logging backend as a test dependency.
---
 .../tool/DashScopeMultiModalTool.java         | 41 ++++++++++++++--
 .../tool/DashScopeMultiModalToolTest.java     | 48 +++++++++++++++++++
 2 files changed, 85 insertions(+), 4 deletions(-)

diff --git a/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/main/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalTool.java b/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/main/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalTool.java
index be89f5c153..fb0084b773 100644
--- a/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/main/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalTool.java
+++ b/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/main/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalTool.java
@@ -255,6 +255,10 @@ public Mono<ToolResultBlock> dashscopeTextToImage(
     /**
      * Edit or transform an image based on a text prompt and an input image.
      *
+     * <p>Logging contract: only the kind and length of {@code image_url} and the length of
+     * {@code prompt} are logged. Neither the reference itself nor the prompt text reaches the log,
+     * because the reference may be a Base64 data URL carrying the whole image.
+     *
      * @param imageUrl      The public URL, oss:// URL, local file path, or Base64 data URL of the
      *                      input image to edit.
      * @param prompt        The text prompt describing the desired edit or transformation.
@@ -337,10 +341,8 @@ public Mono<ToolResultBlock> dashscopeImageToImage(
         String finalSize = resolveOutputSize(finalModel, size);
 
         log.debug(
-                "dashscope_image_to_image called: imageUrl='{}', prompt='{}', model='{}',"
-                        + " size='{}', useBase64='{}'",
-                imageUrl,
-                prompt,
+                "dashscope_image_to_image called: {}, model='{}', size='{}', useBase64='{}'",
+                describeEditRequest(imageUrl, prompt),
                 finalModel,
                 finalSize,
                 useBase64);
@@ -520,6 +522,37 @@ private static boolean rejectsImageInput(String model) {
                 && !isNumberedEditGeneration(name);
     }
 
+    /**
+     * Summarize an edit request for logging without carrying any user payload.
+     *
+     * <p>{@code image_url} is allowed to be a Base64 data URL, so a single call can hand over the
+     * entire encoded image. Writing it to an INFO/DEBUG line puts those bytes in the application
+     * log - typically megabytes per line, and in the clear for anything that collects logs - and
+     * the prompt is user content with no better claim to being logged. Both are therefore reduced
+     * to a kind and a length here; not even a prefix of either value is rendered.
+     */
+    private static String describeEditRequest(String imageUrl, String prompt) {
+        String ref = imageUrl == null ? "" : imageUrl.trim().toLowerCase();
+        String kind;
+        if (ref.isEmpty()) {
+            kind = "absent";
+        } else if (ref.startsWith("data:")) {
+            kind = "base64-data-url";
+        } else if (ref.startsWith("oss://")) {
+            kind = "oss-url";
+        } else if (ref.startsWith("http://") || ref.startsWith("https://")) {
+            kind = "http-url";
+        } else {
+            kind = "local-path";
+        }
+        return "imageRef="
+                + kind
+                + "(len="
+                + ref.length()
+                + "), promptLength="
+                + (prompt == null ? 0 : prompt.length());
+    }
+
     /** Actionable hint returned instead of an opaque service-side parameter error. */
     private static String unsupportedEditModelMessage(String model) {
         return "Model '"
diff --git a/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/test/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalToolTest.java b/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/test/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalToolTest.java
index 072ffc6130..2f6be63d89 100644
--- a/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/test/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalToolTest.java
+++ b/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/test/java/io/agentscope/extensions/model/dashscope/tool/DashScopeMultiModalToolTest.java
@@ -789,6 +789,54 @@ void testResolveOutputSize() throws Exception {
         }
     }
 
+    @Nested
+    @DisplayName("Image edit logging contract")
+    class ImageEditLoggingContractTests {
+
+        /** Use reflection to call the private summarizer used by the debug log. */
+        private String summarize(String imageUrl, String prompt) throws Exception {
+            Method method =
+                    DashScopeMultiModalTool.class.getDeclaredMethod(
+                            "describeEditRequest", String.class, String.class);
+            method.setAccessible(true);
+            return (String) method.invoke(null, imageUrl, prompt);
+        }
+
+        @Test
+        @DisplayName("A Base64 data URL is reduced to kind and length, never to its bytes")
+        void testInlineDataUrlIsNotRendered() throws Exception {
+            String imageUrl = TEST_IMAGE_BASE64_DATA_URL + TEST_BASE64_DATA + TEST_BASE64_DATA;
+            String prompt = "Repaint the sketch of my house at 4 Oak Street";
+
+            String summary = summarize(imageUrl, prompt);
+
+            assertTrue(summary.contains("base64-data-url"), summary);
+            assertTrue(summary.contains("len=" + imageUrl.length()), summary);
+            assertTrue(summary.contains("promptLength=" + prompt.length()), summary);
+            // The encoded image must not appear, not even as a prefix of it.
+            assertFalse(summary.contains(TEST_BASE64_DATA), summary);
+            assertFalse(summary.contains("iVBORw0KGgo"), summary);
+            // Nor may the prompt, which is user content.
+            assertFalse(summary.contains(prompt), summary);
+            assertFalse(summary.contains("Oak Street"), summary);
+        }
+
+        @Test
+        @DisplayName("Every accepted input form is classified by shape, without its address")
+        void testReferenceKindsCarryNoAddress() throws Exception {
+            assertTrue(summarize(TEST_IMAGE0_URL, "x").contains("imageRef=http-url("));
+            assertTrue(summarize("oss://bucket/key.png", "x").contains("imageRef=oss-url("));
+            assertTrue(summarize(TEST_IMAGE_PATH, "x").contains("imageRef=local-path("));
+            assertTrue(summarize("DATA:IMAGE/PNG;BASE64,AAAA", "x").contains("base64-data-url"));
+            // A signed object URL carries credentials in its query string, so the host and path
+            // are not part of the contract either.
+            assertFalse(summarize(TEST_IMAGE0_URL, "x").contains("example.com"));
+            assertFalse(summarize("oss://bucket/key.png", "x").contains("key.png"));
+            assertEquals("imageRef=absent(len=0), promptLength=0", summarize(null, null));
+            assertEquals("imageRef=absent(len=0), promptLength=0", summarize("   ", null));
+        }
+    }
+
     @Test
     @DisplayName("Image to text with web url")
     void testImageToTextWithUrl() {

From 64734b173ab7cd37330728c3a2b4a2e9e2c3bc16 Mon Sep 17 00:00:00 2001
From: TanzJ <im.tanzj@live.com>
Date: Sat, 5 Sep 2026 20:29:27 +0800
Subject: [PATCH 6/6] docs(examples): list dashscope_image_to_image in the
 multimodal tool example

This example is the only place in the repository that names each multimodal tool and pairs it with a copy-paste prompt, and it had drifted behind the class it documents. The doc tree has no equivalent per-tool surface to extend: docs/v1 enumerates capabilities per tool class and its import path no longer resolves after the 2.x layout, while the v2 DashScope page covers model wiring only.
---
 .../documentation2/multimodal/MultiModalToolExample.java       | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/agentscope-examples/documentation/src/main/java/io/agentscope/examples/documentation2/multimodal/MultiModalToolExample.java b/agentscope-examples/documentation/src/main/java/io/agentscope/examples/documentation2/multimodal/MultiModalToolExample.java
index f0d37bed96..9b1a8601ac 100644
--- a/agentscope-examples/documentation/src/main/java/io/agentscope/examples/documentation2/multimodal/MultiModalToolExample.java
+++ b/agentscope-examples/documentation/src/main/java/io/agentscope/examples/documentation2/multimodal/MultiModalToolExample.java
@@ -128,6 +128,7 @@ private static void printRegisteredTools() {
                 """
                 Registered tools:
                 - dashscope_text_to_image: Generate image(s) based on the given text.
+                - dashscope_image_to_image: Edit or transform an existing image based on a text prompt and an input image.
                 - dashscope_image_to_text: Generate text based on the given images.
                 - dashscope_text_to_audio: Convert the given text to audio.
                 - dashscope_audio_to_text: Convert the given audio to text.
@@ -146,6 +147,8 @@ private static void printExamplePrompts() {
                 Example Prompts:
                 [dashscope_text_to_image]:
                 Generate a black dog image url.
+                [dashscope_image_to_image]:
+                Repaint the tiger image url of 'https://dashscope.oss-cn-beijing.aliyuncs.com/images/tiger.png' as a watercolor painting.
                 [dashscope_image_to_text]:
                 Describe the image url of 'https://dashscope.oss-cn-beijing.aliyuncs.com/images/tiger.png'.
                 [dashscope_text_to_audio]: