Review API design of org.springframework.ai.image (#326)

models/spring-ai-azure-openai/src/main/java/org/springframework/ai/azure/openai/AzureOpenAiImageOptions.java

@@ -22,6 +22,7 @@
 import com.fasterxml.jackson.annotation.JsonProperty;
 
 import org.springframework.ai.image.ImageOptions;
+import org.springframework.ai.image.ImageResponseFormat;
 
 /**
  * The configuration information for a image generation request.
@@ -81,7 +82,7 @@ public class AzureOpenAiImageOptions implements ImageOptions {
 	 * b64_json.
 	 */
 	@JsonProperty("response_format")
-	private String responseFormat;
+	private ImageResponseFormat responseFormat;
 
 	/**
 	 * The size of the generated images. Must be one of 256x256, 512x512, or 1024x1024 for
@@ -150,13 +151,21 @@ public void setHeight(Integer height) {
 
 	@Override
 	public String getResponseFormat() {
+		return (this.responseFormat != null) ? this.responseFormat.getValue() : null;
+	}
+
+	public ImageResponseFormat getResponseFormatEnum() {
 		return this.responseFormat;
 	}
 
-	public void setResponseFormat(String responseFormat) {
+	public void setResponseFormat(ImageResponseFormat responseFormat) {
 		this.responseFormat = responseFormat;
 	}
 
+	public void setResponseFormat(String responseFormat) {
+		this.responseFormat = ImageResponseFormat.fromValue(responseFormat);
+	}
+
 	public String getSize() {
 		if (this.size != null) {
 			return this.size;
@@ -279,6 +288,11 @@ public Builder deploymentName(String deploymentName) {
 			return this;
 		}
 
+		public Builder responseFormat(ImageResponseFormat responseFormat) {
+			this.options.setResponseFormat(responseFormat);
+			return this;
+		}
+
 		public Builder responseFormat(String responseFormat) {
 			this.options.setResponseFormat(responseFormat);
 			return this;

models/spring-ai-openai/src/main/java/org/springframework/ai/openai/OpenAiImageOptions.java

@@ -22,6 +22,7 @@
 import com.fasterxml.jackson.annotation.JsonProperty;
 
 import org.springframework.ai.image.ImageOptions;
+import org.springframework.ai.image.ImageResponseFormat;
 
 /**
  * OpenAI Image API options. OpenAiImageOptions.java
@@ -79,7 +80,7 @@ public class OpenAiImageOptions implements ImageOptions {
 	 * b64_json.
 	 */
 	@JsonProperty("response_format")
-	private String responseFormat;
+	private ImageResponseFormat responseFormat;
 
 	/**
 	 * The size of the generated images. Must be one of 256x256, 512x512, or 1024x1024 for
@@ -159,13 +160,21 @@ public void setQuality(String quality) {
 
 	@Override
 	public String getResponseFormat() {
+		return (this.responseFormat != null) ? this.responseFormat.getValue() : null;
+	}
+
+	public ImageResponseFormat getResponseFormatEnum() {
 		return this.responseFormat;
 	}
 
-	public void setResponseFormat(String responseFormat) {
+	public void setResponseFormat(ImageResponseFormat responseFormat) {
 		this.responseFormat = responseFormat;
 	}
 
+	public void setResponseFormat(String responseFormat) {
+		this.responseFormat = ImageResponseFormat.fromValue(responseFormat);
+	}
+
 	@Override
 	public Integer getWidth() {
 		if (this.width != null) {
@@ -326,6 +335,11 @@ public Builder quality(String quality) {
 			return this;
 		}
 
+		public Builder responseFormat(ImageResponseFormat responseFormat) {
+			this.options.setResponseFormat(responseFormat);
+			return this;
+		}
+
 		public Builder responseFormat(String responseFormat) {
 			this.options.setResponseFormat(responseFormat);
 			return this;

models/spring-ai-openai/src/test/java/org/springframework/ai/openai/OpenAiImageOptionsTests.java

@@ -18,6 +18,8 @@
 
 import org.junit.jupiter.api.Test;
 
+import org.springframework.ai.image.ImageResponseFormat;
+
 import static org.assertj.core.api.Assertions.assertThat;
 
 /**
@@ -34,7 +36,7 @@ void testBuilderWithAllFields() {
 			.N(2)
 			.model("dall-e-3")
 			.quality("hd")
-			.responseFormat("url")
+			.responseFormat(ImageResponseFormat.URL)
 			.width(1024)
 			.height(1024)
 			.style("vivid")
@@ -45,6 +47,7 @@ void testBuilderWithAllFields() {
 		assertThat(options.getModel()).isEqualTo("dall-e-3");
 		assertThat(options.getQuality()).isEqualTo("hd");
 		assertThat(options.getResponseFormat()).isEqualTo("url");
+		assertThat(options.getResponseFormatAsEnum()).isEqualTo(ImageResponseFormat.URL);
 		assertThat(options.getWidth()).isEqualTo(1024);
 		assertThat(options.getHeight()).isEqualTo(1024);
 		assertThat(options.getSize()).isEqualTo("1024x1024");
@@ -58,7 +61,7 @@ void testCopy() {
 			.N(3)
 			.model("dall-e-3")
 			.quality("standard")
-			.responseFormat("b64_json")
+			.responseFormat(ImageResponseFormat.B64_JSON)
 			.width(1792)
 			.height(1024)
 			.style("natural")
@@ -72,6 +75,7 @@ void testCopy() {
 		assertThat(copied.getModel()).isEqualTo(original.getModel());
 		assertThat(copied.getQuality()).isEqualTo(original.getQuality());
 		assertThat(copied.getResponseFormat()).isEqualTo(original.getResponseFormat());
+		assertThat(copied.getResponseFormatAsEnum()).isEqualTo(original.getResponseFormatAsEnum());
 		assertThat(copied.getWidth()).isEqualTo(original.getWidth());
 		assertThat(copied.getHeight()).isEqualTo(original.getHeight());
 		assertThat(copied.getSize()).isEqualTo(original.getSize());
@@ -85,6 +89,7 @@ void testCopy() {
 		assertThat(copiedViaMethod.getModel()).isEqualTo(original.getModel());
 		assertThat(copiedViaMethod.getQuality()).isEqualTo(original.getQuality());
 		assertThat(copiedViaMethod.getResponseFormat()).isEqualTo(original.getResponseFormat());
+		assertThat(copiedViaMethod.getResponseFormatAsEnum()).isEqualTo(original.getResponseFormatAsEnum());
 		assertThat(copiedViaMethod.getWidth()).isEqualTo(original.getWidth());
 		assertThat(copiedViaMethod.getHeight()).isEqualTo(original.getHeight());
 		assertThat(copiedViaMethod.getSize()).isEqualTo(original.getSize());
@@ -99,7 +104,7 @@ void testSetters() {
 		options.setN(4);
 		options.setModel("dall-e-2");
 		options.setQuality("standard");
-		options.setResponseFormat("url");
+		options.setResponseFormat(ImageResponseFormat.URL);
 		options.setWidth(512);
 		options.setHeight(512);
 		options.setStyle("vivid");
@@ -109,6 +114,7 @@ void testSetters() {
 		assertThat(options.getModel()).isEqualTo("dall-e-2");
 		assertThat(options.getQuality()).isEqualTo("standard");
 		assertThat(options.getResponseFormat()).isEqualTo("url");
+		assertThat(options.getResponseFormatAsEnum()).isEqualTo(ImageResponseFormat.URL);
 		assertThat(options.getWidth()).isEqualTo(512);
 		assertThat(options.getHeight()).isEqualTo(512);
 		assertThat(options.getSize()).isEqualTo("512x512");
@@ -212,7 +218,7 @@ void testFluentApiPattern() {
 			.N(1)
 			.model("dall-e-3")
 			.quality("hd")
-			.responseFormat("url")
+			.responseFormat(ImageResponseFormat.URL)
 			.width(1024)
 			.height(1024)
 			.style("vivid")
@@ -223,6 +229,7 @@ void testFluentApiPattern() {
 		assertThat(options.getModel()).isEqualTo("dall-e-3");
 		assertThat(options.getQuality()).isEqualTo("hd");
 		assertThat(options.getResponseFormat()).isEqualTo("url");
+		assertThat(options.getResponseFormatAsEnum()).isEqualTo(ImageResponseFormat.URL);
 		assertThat(options.getWidth()).isEqualTo(1024);
 		assertThat(options.getHeight()).isEqualTo(1024);
 		assertThat(options.getSize()).isEqualTo("1024x1024");

models/spring-ai-openai/src/test/java/org/springframework/ai/openai/image/OpenAiImageModelObservationIT.java

@@ -23,6 +23,7 @@
 
 import org.springframework.ai.image.ImagePrompt;
 import org.springframework.ai.image.ImageResponse;
+import org.springframework.ai.image.ImageResponseFormat;
 import org.springframework.ai.image.observation.DefaultImageModelObservationConvention;
 import org.springframework.ai.model.SimpleApiKey;
 import org.springframework.ai.observation.conventions.AiOperationType;
@@ -61,7 +62,7 @@ void observationForImageOperation() {
 			.model(OpenAiImageApi.ImageModel.DALL_E_3.getValue())
 			.height(1024)
 			.width(1024)
-			.responseFormat("url")
+			.responseFormat(ImageResponseFormat.URL)
 			.style("natural")
 			.build();
 

models/spring-ai-stability-ai/src/main/java/org/springframework/ai/stabilityai/api/StabilityAiImageOptions.java

@@ -23,6 +23,7 @@
 import com.fasterxml.jackson.annotation.JsonProperty;
 
 import org.springframework.ai.image.ImageOptions;
+import org.springframework.ai.image.ImageResponseFormat;
 import org.springframework.ai.stabilityai.StyleEnum;
 
 /**
@@ -122,7 +123,7 @@ public class StabilityAiImageOptions implements ImageOptions {
 	 * accept header. Must be "application/json" or "image/png"
 	 */
 	@JsonProperty("response_format")
-	private String responseFormat;
+	private ImageResponseFormat responseFormat;
 
 	/**
 	 * The strictness level of the diffusion process adherence to the prompt text.
@@ -329,13 +330,21 @@ public void setHeight(Integer height) {
 
 	@Override
 	public String getResponseFormat() {
+		return (this.responseFormat != null) ? this.responseFormat.getValue() : null;
+	}
+
+	public ImageResponseFormat getResponseFormatEnum() {
 		return this.responseFormat;
 	}
 
-	public void setResponseFormat(String responseFormat) {
+	public void setResponseFormat(ImageResponseFormat responseFormat) {
 		this.responseFormat = responseFormat;
 	}
 
+	public void setResponseFormat(String responseFormat) {
+		this.responseFormat = ImageResponseFormat.fromValue(responseFormat);
+	}
+
 	public Float getCfgScale() {
 		return this.cfgScale;
 	}
@@ -455,6 +464,11 @@ public Builder height(Integer height) {
 			return this;
 		}
 
+		public Builder responseFormat(ImageResponseFormat responseFormat) {
+			this.options.setResponseFormat(responseFormat);
+			return this;
+		}
+
 		public Builder responseFormat(String responseFormat) {
 			this.options.setResponseFormat(responseFormat);
 			return this;

models/spring-ai-stability-ai/src/test/java/org/springframework/ai/stabilityai/StabilityAiImageOptionsTests.java

@@ -19,6 +19,7 @@
 import org.junit.jupiter.api.Test;
 
 import org.springframework.ai.image.ImageOptions;
+import org.springframework.ai.image.ImageResponseFormat;
 import org.springframework.ai.stabilityai.api.StabilityAiApi;
 import org.springframework.ai.stabilityai.api.StabilityAiImageOptions;
 
@@ -37,7 +38,7 @@ void shouldPreferRuntimeOptionsOverDefaultOptions() {
 			.model("default-model")
 			.width(512)
 			.height(512)
-			.responseFormat("image/png")
+			.responseFormat(ImageResponseFormat.IMAGE_PNG)
 			.cfgScale(7.0f)
 			.clipGuidancePreset("FAST_BLUE")
 			.sampler("DDIM")
@@ -52,7 +53,7 @@ void shouldPreferRuntimeOptionsOverDefaultOptions() {
 			.model("runtime-model")
 			.width(1024)
 			.height(768)
-			.responseFormat("application/json")
+			.responseFormat(ImageResponseFormat.APPLICATION_JSON)
 			.cfgScale(14.0f)
 			.clipGuidancePreset("FAST_GREEN")
 			.sampler("DDPM")
@@ -72,6 +73,7 @@ void shouldPreferRuntimeOptionsOverDefaultOptions() {
 			assertThat(options.getWidth()).isEqualTo(1024);
 			assertThat(options.getHeight()).isEqualTo(768);
 			assertThat(options.getResponseFormat()).isEqualTo("application/json");
+			assertThat(options.getResponseFormatAsEnum()).isEqualTo(ImageResponseFormat.APPLICATION_JSON);
 			assertThat(options.getCfgScale()).isEqualTo(14.0f);
 			assertThat(options.getClipGuidancePreset()).isEqualTo("FAST_GREEN");
 			assertThat(options.getSampler()).isEqualTo("DDPM");

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/imageclient.adoc

@@ -91,6 +91,8 @@ public interface ImageOptions extends ModelOptions {
 
 	String getResponseFormat(); // openai - url or base64 : stability ai byte[] or base64
 
+	default ImageResponseFormat getResponseFormatAsEnum(); // convenience conversion helper
+
 }
 ----
 
@@ -112,6 +114,10 @@ public class ImageResponse implements ModelResponse<ImageGeneration> {
 
 	private final List<ImageGeneration> imageGenerations;
 
+	Optional<byte[]> getResultAsBytes();
+
+	List<byte[]> getResultsAsBytes();
+
 	@Override
 	public ImageGeneration getResult() {
 		// get the first result

spring-ai-model/src/main/java/org/springframework/ai/image/Image.java

@@ -16,7 +16,13 @@
 
 package org.springframework.ai.image;
 
+import java.io.ByteArrayInputStream;
+import java.io.InputStream;
+import java.util.Base64;
 import java.util.Objects;
+import java.util.Optional;
+
+import org.springframework.util.StringUtils;
 
 public class Image {
 
@@ -72,4 +78,15 @@ public int hashCode() {
 		return Objects.hash(this.url, this.b64Json);
 	}
 
+	public Optional<byte[]> getB64JsonAsBytes() {
+		if (!StringUtils.hasText(this.b64Json)) {
+			return Optional.empty();
+		}
+		return Optional.of(Base64.getDecoder().decode(this.b64Json));
+	}
+
+	public Optional<InputStream> getB64JsonAsInputStream() {
+		return getB64JsonAsBytes().map(ByteArrayInputStream::new);
+	}
+
 }

spring-ai-model/src/main/java/org/springframework/ai/image/ImageOptions.java

@@ -18,6 +18,7 @@
 
 import org.springframework.ai.model.ModelOptions;
 import org.springframework.lang.Nullable;
+import org.springframework.util.StringUtils;
 
 /**
  * ImageOptions represent the common options, portable across different image generation
@@ -40,6 +41,14 @@ public interface ImageOptions extends ModelOptions {
 	@Nullable
 	String getResponseFormat();
 
+	default @Nullable ImageResponseFormat getResponseFormatAsEnum() {
+		String responseFormat = getResponseFormat();
+		if (!StringUtils.hasText(responseFormat)) {
+			return null;
+		}
+		return ImageResponseFormat.fromValue(responseFormat);
+	}
+
 	@Nullable
 	String getStyle();