Image Models

public interface ImageModel extends Model<ImagePrompt, ImageResponse> {
    /**
     * Generate images based on the given prompt.
     *
     * @param request the image generation prompt
     * @return the image response with generated images
     */
    ImageResponse call(ImagePrompt request);
}

public class ImagePrompt implements ModelRequest<List<ImageMessage>> {
    /**
     * Construct an ImagePrompt from a simple string instruction.
     *
     * @param instructions the text prompt for image generation
     */
    public ImagePrompt(String instructions);

    /**
     * Construct an ImagePrompt from an ImageMessage.
     *
     * @param imageMessage the image message
     */
    public ImagePrompt(ImageMessage imageMessage);

    /**
     * Construct an ImagePrompt from a list of ImageMessages.
     *
     * @param messages the list of image messages
     */
    public ImagePrompt(List<ImageMessage> messages);

    /**
     * Construct an ImagePrompt with messages and options.
     *
     * @param messages the list of image messages
     * @param imageOptions the image generation options
     */
    public ImagePrompt(List<ImageMessage> messages, ImageOptions imageOptions);

    /**
     * Get the image messages containing prompts.
     *
     * @return list of image messages
     */
    List<ImageMessage> getInstructions();

    /**
     * Get the image generation options.
     *
     * @return the image options
     */
    ImageOptions getOptions();
}

public class ImageResponse implements ModelResponse<ImageGeneration> {
    /**
     * Construct an ImageResponse with generations.
     *
     * @param generations the list of image generations
     */
    public ImageResponse(List<ImageGeneration> generations);

    /**
     * Construct an ImageResponse with generations and metadata.
     *
     * @param generations the list of image generations
     * @param metadata the response metadata
     */
    public ImageResponse(List<ImageGeneration> generations, ImageResponseMetadata metadata);

    /**
     * Get all image generations.
     *
     * @return list of image generations
     */
    List<ImageGeneration> getResults();

    /**
     * Get the first image generation.
     *
     * @return the first image generation
     */
    ImageGeneration getResult();

    /**
     * Get response metadata.
     *
     * @return the image response metadata
     */
    ImageResponseMetadata getMetadata();
}

public class ImageGeneration implements ModelResult<Image> {
    /**
     * Construct an ImageGeneration with an image.
     *
     * @param image the generated image
     */
    public ImageGeneration(Image image);

    /**
     * Construct an ImageGeneration with an image and metadata.
     *
     * @param image the generated image
     * @param metadata the generation metadata
     */
    public ImageGeneration(Image image, ImageGenerationMetadata metadata);

    /**
     * Get the generated image.
     *
     * @return the image
     */
    Image getOutput();

    /**
     * Get generation metadata.
     *
     * @return the image generation metadata
     */
    ImageGenerationMetadata getMetadata();
}

public class Image {
    /**
     * Construct an Image with URL and/or base64 data.
     *
     * @param url the URL where the image can be accessed
     * @param b64Json the base64-encoded image data
     */
    public Image(String url, String b64Json);

    /**
     * Get the URL of the generated image.
     *
     * @return the image URL, or null if only base64 is available
     */
    String getUrl();

    /**
     * Get the base64-encoded image data.
     *
     * @return the base64 JSON string, or null if only URL is available
     */
    String getB64Json();
}

public class ImageMessage {
    /**
     * Construct an ImageMessage with text.
     *
     * @param text the text prompt describing the desired image
     */
    public ImageMessage(String text);

    /**
     * Construct an ImageMessage with text and weight.
     *
     * @param text the text prompt
     * @param weight the weight/importance of this prompt (0.0 to 1.0)
     */
    public ImageMessage(String text, double weight);

    /**
     * Get the prompt text.
     *
     * @return the text prompt
     */
    String getText();

    /**
     * Get the weight of this prompt.
     *
     * @return the weight value
     */
    double getWeight();
}

public interface ImageOptions extends ModelOptions {
    /**
     * Get the number of images to generate.
     *
     * @return the number of images
     */
    Integer getN();

    /**
     * Get the model name to use.
     *
     * @return the model name
     */
    String getModel();

    /**
     * Get the width of generated images.
     *
     * @return the width in pixels
     */
    Integer getWidth();

    /**
     * Get the height of generated images.
     *
     * @return the height in pixels
     */
    Integer getHeight();

    /**
     * Get the response format (url or b64_json).
     *
     * @return the response format
     */
    String getResponseFormat();

    /**
     * Get the style for image generation.
     * Provider-specific (e.g., "vivid", "natural" for OpenAI).
     *
     * @return the style
     */
    String getStyle();

    /**
     * Create a new options builder.
     *
     * @return a new builder
     */
    static ImageOptionsBuilder builder();
}

public interface ImageOptionsBuilder {
    ImageOptionsBuilder n(Integer n);
    ImageOptionsBuilder model(String model);
    ImageOptionsBuilder width(Integer width);
    ImageOptionsBuilder height(Integer height);
    ImageOptionsBuilder responseFormat(String responseFormat);
    ImageOptionsBuilder style(String style);
    ImageOptions build();
}

public interface ImageGenerationMetadata extends ResultMetadata {
    // Empty interface for image generation metadata
    // Provider-specific implementations may add additional methods
}

public class ImageResponseMetadata extends MutableResponseMetadata {
    // Response-level metadata for image generation
}

import org.springframework.ai.image.ImageModel;
import org.springframework.ai.image.ImagePrompt;
import org.springframework.ai.image.ImageResponse;
import org.springframework.ai.image.Image;
import org.springframework.beans.factory.annotation.Autowired;

@Service
public class ImageService {
    @Autowired
    private ImageModel imageModel;

    public String generateImage(String prompt) {
        // Create simple prompt
        ImagePrompt imagePrompt = new ImagePrompt(prompt);

        // Generate image
        ImageResponse response = imageModel.call(imagePrompt);

        // Get image URL
        Image image = response.getResult().getOutput();
        return image.getUrl();
    }
}

import org.springframework.ai.image.ImageOptions;

// Configure options for multiple images
ImageOptions options = ImageOptions.builder()
    .n(4)  // Generate 4 images
    .width(512)
    .height(512)
    .build();

ImagePrompt prompt = new ImagePrompt("A serene mountain landscape", options);
ImageResponse response = imageModel.call(prompt);

// Get all generated images
for (ImageGeneration generation : response.getResults()) {
    Image image = generation.getOutput();
    System.out.println("Image URL: " + image.getUrl());
}

// Generate high-resolution image
ImageOptions options = ImageOptions.builder()
    .width(1024)
    .height(1024)
    .model("dall-e-3")
    .build();

ImagePrompt prompt = new ImagePrompt(
    "A futuristic city at sunset",
    options
);

ImageResponse response = imageModel.call(prompt);
Image image = response.getResult().getOutput();

import java.util.Base64;
import java.io.FileOutputStream;

// Request base64 format
ImageOptions options = ImageOptions.builder()
    .responseFormat("b64_json")
    .build();

ImagePrompt prompt = new ImagePrompt("A beautiful sunset", options);
ImageResponse response = imageModel.call(prompt);

// Get base64 data
Image image = response.getResult().getOutput();
String b64Json = image.getB64Json();

// Decode and save
byte[] imageBytes = Base64.getDecoder().decode(b64Json);
try (FileOutputStream fos = new FileOutputStream("image.png")) {
    fos.write(imageBytes);
}

// Generate with specific style
ImageOptions vividStyle = ImageOptions.builder()
    .style("vivid")  // More dramatic, hyper-real
    .model("dall-e-3")
    .build();

ImageOptions naturalStyle = ImageOptions.builder()
    .style("natural")  // More natural, less hyper-real
    .model("dall-e-3")
    .build();

// Use vivid style
ImagePrompt prompt = new ImagePrompt("A tropical beach", vividStyle);
ImageResponse response = imageModel.call(prompt);

import org.springframework.ai.image.ImageMessage;

// Create messages with different weights
List<ImageMessage> messages = List.of(
    new ImageMessage("sunset", 0.8),
    new ImageMessage("mountains", 0.5),
    new ImageMessage("lake", 0.3)
);

ImagePrompt prompt = new ImagePrompt(messages);
ImageResponse response = imageModel.call(prompt);

ImagePrompt prompt = new ImagePrompt("Abstract art");
ImageResponse response = imageModel.call(prompt);

// Access response metadata
ImageResponseMetadata responseMeta = response.getMetadata();

// Access generation metadata
ImageGenerationMetadata genMeta = response.getResult().getMetadata();

// Check if prompt was revised
String revisedPrompt = genMeta.getRevisedPrompt();
if (revisedPrompt != null) {
    System.out.println("Original: " + prompt.getInstructions().get(0).getText());
    System.out.println("Revised: " + revisedPrompt);
}

import java.net.URL;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.io.InputStream;

public void downloadImage(String prompt, String outputPath) throws Exception {
    ImagePrompt imagePrompt = new ImagePrompt(prompt);
    ImageResponse response = imageModel.call(imagePrompt);

    String imageUrl = response.getResult().getOutput().getUrl();

    // Download image
    try (InputStream in = new URL(imageUrl).openStream()) {
        Files.copy(in, Paths.get(outputPath));
    }

    System.out.println("Image saved to: " + outputPath);
}

@Service
public class BatchImageService {
    private final ImageModel imageModel;

    public List<String> generateImages(List<String> prompts) {
        List<String> imageUrls = new ArrayList<>();

        for (String prompt : prompts) {
            ImagePrompt imagePrompt = new ImagePrompt(prompt);
            ImageResponse response = imageModel.call(imagePrompt);

            String url = response.getResult().getOutput().getUrl();
            imageUrls.add(url);
        }

        return imageUrls;
    }
}

public String safeGenerateImage(String prompt) {
    try {
        ImagePrompt imagePrompt = new ImagePrompt(prompt);
        ImageResponse response = imageModel.call(imagePrompt);

        Image image = response.getResult().getOutput();

        // Prefer URL, fall back to base64
        if (image.getUrl() != null) {
            return image.getUrl();
        } else if (image.getB64Json() != null) {
            return "data:image/png;base64," + image.getB64Json();
        } else {
            throw new RuntimeException("No image data available");
        }
    } catch (Exception e) {
        System.err.println("Image generation failed: " + e.getMessage());
        return null;
    }
}

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class ImageConfig {

    @Bean
    public ImageOptions defaultImageOptions() {
        return ImageOptions.builder()
            .n(1)
            .width(512)
            .height(512)
            .model("dall-e-2")
            .responseFormat("url")
            .build();
    }
}

@RestController
@RequestMapping("/api/images")
public class ImageController {
    private final ImageModel imageModel;

    public ImageController(ImageModel imageModel) {
        this.imageModel = imageModel;
    }

    @PostMapping("/generate")
    public ImageResult generateImage(@RequestBody ImageRequest request) {
        // Build options
        ImageOptions options = ImageOptions.builder()
            .width(request.getWidth())
            .height(request.getHeight())
            .n(request.getCount())
            .style(request.getStyle())
            .build();

        // Create prompt
        ImagePrompt prompt = new ImagePrompt(request.getPrompt(), options);

        // Generate images
        ImageResponse response = imageModel.call(prompt);

        // Extract URLs
        List<String> urls = response.getResults().stream()
            .map(gen -> gen.getOutput().getUrl())
            .toList();

        return new ImageResult(urls);
    }

    record ImageRequest(
        String prompt,
        Integer width,
        Integer height,
        Integer count,
        String style
    ) {}

    record ImageResult(List<String> imageUrls) {}
}