feat: add new parameters for image generation and multimodal conversation

Author: kevin

.dev_tools/run_ci.sh

@@ -26,7 +26,7 @@ mvn package
 
 if [ $? -ne 0 ]; then
   echo "mvn package failed, please check if any unittest is failed!"
-  exit -1
+  exit 1
 fi
 
-echo "CI passed."
+echo "CI passed."

README.md

@@ -173,4 +173,3 @@ public class Main {
 ```
 
 The `call` method accepts a `GenerationParam`, and returns a `GenerationResult`, you can also catch the exception with a try-catch block.
-

lint.sh

@@ -1 +1 @@
-java -jar .dev_tools/google-java-format-1.7-all-deps.jar -i $(find . -type f -name "*.java" | grep "./*/src/.*java")
+java -jar .dev_tools/google-java-format-1.7-all-deps.jar -i $(find . -type f -name "*.java" | grep "./*/src/.*java")

src/main/java/com/alibaba/dashscope/aigc/completion/ChatCompletionParam.java

@@ -80,6 +80,45 @@ public class ChatCompletionParam extends FlattenHalfDuplexParamBase {
   @SerializedName("parallel_tool_calls")
   private Boolean parallelToolCalls;
 
+  /**
+   * Whether to preserve thinking/reasoning content in the response. When enabled, the model will
+   * include reasoning process in the output.
+   */
+  @SerializedName("preserve_thinking")
+  private Boolean preserveThinking;
+
+  /**
+   * Controls the reasoning effort level for models that support it. Possible values: "low",
+   * "medium", "high"
+   */
+  @SerializedName("reasoning_effort")
+  private String reasoningEffort;
+
+  /**
+   * The maximum number of tokens to generate for completion. This is an alternative to max_tokens
+   * following OpenAI's newer API convention.
+   */
+  @SerializedName("max_completion_tokens")
+  private Integer maxCompletionTokens;
+
+  /**
+   * Whether to stream tool calls as they are generated. When true, tool calls will be sent
+   * incrementally rather than all at once.
+   */
+  @SerializedName("tool_stream")
+  private Boolean toolStream;
+
+  /**
+   * Enable high resolution image processing for vision-language models. Improves image
+   * understanding quality at the cost of more tokens.
+   */
+  @SerializedName("vl_high_resolution_images")
+  private Boolean vlHighResolutionImages;
+
+  /** Enable hardware-accelerated image output for vision-language models. */
+  @SerializedName("vl_enable_image_hw_output")
+  private Boolean vlEnableImageHwOutput;
+
   private String user;
 
   @Override
@@ -142,6 +181,24 @@ public JsonObject getHttpBody() {
     if (parallelToolCalls != null) {
       requestObject.addProperty("parallel_tool_calls", parallelToolCalls);
     }
+    if (preserveThinking != null) {
+      requestObject.addProperty("preserve_thinking", preserveThinking);
+    }
+    if (reasoningEffort != null) {
+      requestObject.addProperty("reasoning_effort", reasoningEffort);
+    }
+    if (maxCompletionTokens != null) {
+      requestObject.addProperty("max_completion_tokens", maxCompletionTokens);
+    }
+    if (toolStream != null) {
+      requestObject.addProperty("tool_stream", toolStream);
+    }
+    if (vlHighResolutionImages != null) {
+      requestObject.addProperty("vl_high_resolution_images", vlHighResolutionImages);
+    }
+    if (vlEnableImageHwOutput != null) {
+      requestObject.addProperty("vl_enable_image_hw_output", vlEnableImageHwOutput);
+    }
     if (user != null) {
       requestObject.addProperty("user", user);
     }

src/main/java/com/alibaba/dashscope/aigc/imagegeneration/ColorPalette.java

@@ -0,0 +1,20 @@
+package com.alibaba.dashscope.aigc.imagegeneration;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/** Color palette configuration for image generation. */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class ColorPalette {
+
+  /** Hex color code, e.g., "#FF5733" */
+  private String hex;
+
+  /** Ratio of the color in the palette, value range: [0.0, 1.0] */
+  private Double ratio;
+}

src/main/java/com/alibaba/dashscope/aigc/imagegeneration/ImageGenerationParam.java

@@ -83,6 +83,15 @@ public class ImageGenerationParam extends HalfDuplexServiceParam {
    */
   @Builder.Default private List<List<List<Integer>>> bboxList = null;
 
+  /**
+   * Thinking mode for image generation. Controls the level of reasoning and planning in the
+   * generation process.
+   */
+  private String thinkingMode;
+
+  /** Color palette configuration for controlling color distribution in generated images. */
+  private List<ColorPalette> colorPalette;
+
   @Override
   public JsonObject getHttpBody() {
     JsonObject requestObject = new JsonObject();
@@ -167,6 +176,14 @@ public Map<String, Object> getParameters() {
       params.put("bbox_list", bboxList);
     }
 
+    if (thinkingMode != null) {
+      params.put("thinking_mode", thinkingMode);
+    }
+
+    if (colorPalette != null) {
+      params.put("color_palette", colorPalette);
+    }
+
     params.putAll(parameters);
     return params;
   }

src/main/java/com/alibaba/dashscope/aigc/imagesynthesis/ImageSynthesisParam.java

@@ -12,6 +12,7 @@
 import com.alibaba.dashscope.utils.JsonUtils;
 import com.alibaba.dashscope.utils.PreprocessInputImage;
 import com.google.gson.JsonObject;
+import com.google.gson.annotations.SerializedName;
 import java.nio.ByteBuffer;
 import java.util.ArrayList;
 import java.util.HashMap;
@@ -58,6 +59,27 @@ public class ImageSynthesisParam extends HalfDuplexServiceParam {
 
   @Builder.Default private Boolean watermark = null;
 
+  /**
+   * Controls the similarity between the output image and the reference image (垫图). Value range:
+   * [0.0, 1.0]. Higher values mean the generated image is more similar to the reference image.
+   */
+  @Builder.Default private Float refStrength = null;
+
+  /**
+   * The mode for generating images based on the reference image (垫图). Supported modes: - "repaint"
+   * (default): Generate image based on the content of the reference image. - "refonly": Generate
+   * image based on the style of the reference image.
+   */
+  @Builder.Default private String refMode = null;
+
+  /**
+   * The color used to fill the masked area before inpainting. Format: hex color code, e.g.,
+   * "#FFFFFF" or "white", "black", etc.
+   */
+  @SerializedName("mask_color")
+  @Builder.Default
+  private String maskColor = null;
+
   @Override
   public JsonObject getInput() {
     JsonObject jsonObject = new JsonObject();
@@ -124,6 +146,18 @@ public Map<String, Object> getParameters() {
       params.put(WATERMARK, watermark);
     }
 
+    if (refStrength != null) {
+      params.put("ref_strength", refStrength);
+    }
+
+    if (refMode != null) {
+      params.put("ref_mode", refMode);
+    }
+
+    if (maskColor != null) {
+      params.put("mask_color", maskColor);
+    }
+
     params.putAll(super.getParameters());
     return params;
   }

src/main/java/com/alibaba/dashscope/aigc/imagesynthesis/SketchImageSynthesisParam.java

@@ -36,6 +36,18 @@ public class SketchImageSynthesisParam extends HalfDuplexServiceParam {
   @lombok.NonNull
   private String sketchImageUrl;
 
+  @SerializedName("style")
+  @Builder.Default
+  private String style = null;
+
+  @SerializedName("sketch_extraction")
+  @Builder.Default
+  private Boolean sketchExtraction = null;
+
+  @SerializedName("sketch_color")
+  @Builder.Default
+  private String sketchColor = null;
+
   @lombok.NonNull private String prompt;
 
   @Override
@@ -61,6 +73,15 @@ public Map<String, Object> getParameters() {
     if (realisticness != null) {
       params.put(REALISTICNESS, realisticness);
     }
+    if (style != null) {
+      params.put("style", style);
+    }
+    if (sketchExtraction != null) {
+      params.put("sketch_extraction", sketchExtraction);
+    }
+    if (sketchColor != null) {
+      params.put("sketch_color", sketchColor);
+    }
     params.putAll(super.getParameters());
     return params;
   }

src/main/java/com/alibaba/dashscope/aigc/multimodalconversation/MultiModalConversationParam.java

@@ -103,7 +103,7 @@ public class MultiModalConversationParam extends HalfDuplexServiceParam {
    * apple
    * </pre>
    */
-  @Builder.Default private Boolean incrementalOutput;
+  @Builder.Default private Boolean incrementalOutput = false;
 
   /** Output format of the model including "text" and "audio". Default value: ["text"] */
   private List<String> modalities;
@@ -162,6 +162,24 @@ public class MultiModalConversationParam extends HalfDuplexServiceParam {
   /** thinking budget */
   private Integer thinkingBudget;
 
+  /** stop words or token ids to stop generation */
+  @Singular("stopString")
+  private List<String> stopStrings;
+
+  @Singular private List<List<Integer>> stopTokens;
+
+  /**
+   * whether to return log probabilities of output tokens, supported for qwen-vl-ocr-2025-04-13 and
+   * later
+   */
+  private Boolean logprobs;
+
+  /**
+   * number of top candidate tokens to return log probabilities for, range [0,5], only effective
+   * when logprobs is true
+   */
+  private Integer topLogprobs;
+
   @Override
   public JsonObject getHttpBody() {
     JsonObject requestObject = new JsonObject();
@@ -318,6 +336,20 @@ public Map<String, Object> getParameters() {
       params.put("thinking_budget", thinkingBudget);
     }
 
+    if (stopStrings != null && !stopStrings.isEmpty()) {
+      params.put(ApiKeywords.STOP, stopStrings);
+    } else if (stopTokens != null && !stopTokens.isEmpty()) {
+      params.put(ApiKeywords.STOP, stopTokens);
+    }
+
+    if (logprobs != null) {
+      params.put("logprobs", logprobs);
+    }
+
+    if (topLogprobs != null) {
+      params.put("top_logprobs", topLogprobs);
+    }
+
     params.putAll(parameters);
     return params;
   }

src/test/java/com/alibaba/dashscope/TestImageSynthesis.java

@@ -109,4 +109,96 @@ public void testImageSynthesisUsageMore()
     String requestBody = request.getBody().readUtf8();
     assertEquals(expectRequestBody, requestBody);
   }
+
+  @Test
+  public void testImageSynthesisWithRefStrengthAndRefMode()
+      throws ApiException, NoApiKeyException, IOException, InterruptedException,
+          InputRequiredException {
+    String responseBody =
+        "{\"request_id\":\"40\",\"output\":{\"task_id\":\"e5\",\"task_status\":\"SUCCEEDED\",\"results\":[{\"url\":\"https://ref1\"}],\"task_metrics\":{\"TOTAL\":1,\"SUCCEEDED\":1,\"FAILED\":0}},\"usage\":{\"image_count\":1}}";
+    server.enqueue(
+        new MockResponse()
+            .setBody(responseBody)
+            .setHeader("content-type", MEDIA_TYPE_APPLICATION_JSON));
+    int port = server.getPort();
+    ImageSynthesis is = new ImageSynthesis();
+    ImageSynthesisParam param =
+        ImageSynthesisParam.builder()
+            .model(ImageSynthesis.Models.WANX_2_1_IMAGEEDIT)
+            .n(1)
+            .prompt("参考图像生成")
+            .refStrength(0.8f)
+            .refMode("repaint")
+            .images(java.util.Arrays.asList("https://example.com/ref.png"))
+            .build();
+    Constants.baseHttpApiUrl = String.format("http://127.0.0.1:%s", port);
+    ImageSynthesisResult result = is.asyncCall(param);
+    RecordedRequest request = server.takeRequest();
+    String requestBody = request.getBody().readUtf8();
+    log.info("Request body with ref params: {}", requestBody);
+    // 验证 ref_strength 和 ref_mode 参数被正确序列化
+    assertEquals(true, requestBody.contains("\"ref_strength\":0.8"));
+    assertEquals(true, requestBody.contains("\"ref_mode\":\"repaint\""));
+  }
+
+  @Test
+  public void testImageSynthesisWithMaskColor()
+      throws ApiException, NoApiKeyException, IOException, InterruptedException,
+          InputRequiredException {
+    String responseBody =
+        "{\"request_id\":\"41\",\"output\":{\"task_id\":\"e6\",\"task_status\":\"SUCCEEDED\",\"results\":[{\"url\":\"https://mask1\"}],\"task_metrics\":{\"TOTAL\":1,\"SUCCEEDED\":1,\"FAILED\":0}},\"usage\":{\"image_count\":1}}";
+    server.enqueue(
+        new MockResponse()
+            .setBody(responseBody)
+            .setHeader("content-type", MEDIA_TYPE_APPLICATION_JSON));
+    int port = server.getPort();
+    ImageSynthesis is = new ImageSynthesis();
+    ImageSynthesisParam param =
+        ImageSynthesisParam.builder()
+            .model(ImageSynthesis.Models.WANX_2_1_IMAGEEDIT)
+            .n(1)
+            .prompt("局部重绘")
+            .function("description_edit_with_mask")
+            .baseImageUrl("https://www.xxx.cn/base.png")
+            .maskImageUrl("https://www.xxx.cn/mask.png")
+            .maskColor("#FFFFFF")
+            .build();
+    Constants.baseHttpApiUrl = String.format("http://127.0.0.1:%s", port);
+    ImageSynthesisResult result = is.asyncCall(param);
+    RecordedRequest request = server.takeRequest();
+    String requestBody = request.getBody().readUtf8();
+    log.info("Request body with mask_color: {}", requestBody);
+    // 验证 mask_color 参数被正确序列化
+    assertEquals(true, requestBody.contains("\"mask_color\":\"#FFFFFF\""));
+  }
+
+  @Test
+  public void testImageSynthesisWithPromptExtendAndWatermark()
+      throws ApiException, NoApiKeyException, IOException, InterruptedException,
+          InputRequiredException {
+    String responseBody =
+        "{\"request_id\":\"42\",\"output\":{\"task_id\":\"e7\",\"task_status\":\"SUCCEEDED\",\"results\":[{\"url\":\"https://extend1\"}],\"task_metrics\":{\"TOTAL\":1,\"SUCCEEDED\":1,\"FAILED\":0}},\"usage\":{\"image_count\":1}}";
+    server.enqueue(
+        new MockResponse()
+            .setBody(responseBody)
+            .setHeader("content-type", MEDIA_TYPE_APPLICATION_JSON));
+    int port = server.getPort();
+    ImageSynthesis is = new ImageSynthesis();
+    ImageSynthesisParam param =
+        ImageSynthesisParam.builder()
+            .model(ImageSynthesis.Models.WANX_2_1_IMAGEEDIT)
+            .n(1)
+            .prompt("简单提示词")
+            .promptExtend(true)
+            .watermark(false)
+            .build();
+    Constants.baseHttpApiUrl = String.format("http://127.0.0.1:%s", port);
+    ImageSynthesisResult result = is.asyncCall(param);
+    RecordedRequest request = server.takeRequest();
+    String requestBody = request.getBody().readUtf8();
+    log.info("Request body with prompt_extend and watermark: {}", requestBody);
+    // 验证 prompt_extend 和 watermark 参数被正确序列化
+    assertEquals(true, requestBody.contains("\"prompt_extend\":true"));
+    assertEquals(true, requestBody.contains("\"watermark\":false"));
+  }
 }