CtrlK

Community Documentation Log in Get started

tessl/maven-org-springframework-ai--spring-ai-starter-model-openai

Spring Boot Starter for OpenAI integration providing auto-configuration for chat completion, embeddings, image generation, audio speech synthesis, audio transcription, and content moderation models. Includes high-level ChatClient API and conversation memory support.

Overview

Eval results

Files

Image Model

Name: tessl/maven-org-springframework-ai--spring-ai-starter-model-openai
Author: tessl

The OpenAiImageModel generates images from text prompts using OpenAI's DALL-E models.

Import

import org.springframework.ai.openai.OpenAiImageModel;
import org.springframework.ai.openai.OpenAiImageOptions;
import org.springframework.ai.image.ImagePrompt;
import org.springframework.ai.image.ImageResponse;
import org.springframework.ai.image.ImageGeneration;
import org.springframework.ai.image.Image;
import org.springframework.ai.image.ImageMessage;

API

OpenAiImageModel

package org.springframework.ai.openai;

public class OpenAiImageModel implements ImageModel {
    // Constructors
    public OpenAiImageModel(OpenAiImageApi imageApi);
    public OpenAiImageModel(OpenAiImageApi imageApi, OpenAiImageOptions options);
    public OpenAiImageModel(OpenAiImageApi imageApi, OpenAiImageOptions options, RetryTemplate retryTemplate);

    // Generate image from prompt
    public ImageResponse call(ImagePrompt imagePrompt);

    // Set observation convention
    public void setObservationConvention(ImageModelObservationConvention observationConvention);
}

OpenAiImageOptions

package org.springframework.ai.openai;

public class OpenAiImageOptions implements ImageOptions {
    // Builder methods
    public static OpenAiImageOptions.Builder builder();

    // Utility methods
    public OpenAiImageOptions copy();
    public static OpenAiImageOptions fromOptions(ImageOptions options);
    public String getSize();
    public void setSize(String size);

    // Configuration - Getters
    public String getModel();
    public Integer getN();
    public String getQuality();
    public String getResponseFormat();
    public Integer getWidth();
    public Integer getHeight();
    public String getStyle();
    public String getUser();

    // Configuration - Setters
    public void setModel(String model);
    public void setN(Integer n);
    public void setQuality(String quality);
    public void setResponseFormat(String responseFormat);
    public void setWidth(Integer width);
    public void setHeight(Integer height);
    public void setStyle(String style);
    public void setUser(String user);
}

Usage Examples

Basic Image Generation

import org.springframework.ai.openai.OpenAiImageModel;
import org.springframework.ai.image.ImagePrompt;
import org.springframework.ai.image.ImageResponse;
import org.springframework.ai.image.ImageMessage;
import org.springframework.stereotype.Service;

@Service
public class ImageGenerationService {

    private final OpenAiImageModel imageModel;

    public ImageGenerationService(OpenAiImageModel imageModel) {
        this.imageModel = imageModel;
    }

    public String generateImage(String prompt) {
        ImagePrompt imagePrompt = new ImagePrompt(prompt);
        ImageResponse response = imageModel.call(imagePrompt);
        return response.getResult().getOutput().getUrl();
    }
}

Image Generation with Options

import org.springframework.ai.openai.OpenAiImageOptions;

public String generateImageWithOptions(String prompt) {
    OpenAiImageOptions options = OpenAiImageOptions.builder()
        .model("dall-e-3")
        .quality("hd")
        .width(1024)
        .height(1792)
        .style("vivid")
        .build();

    ImagePrompt imagePrompt = new ImagePrompt(prompt, options);
    ImageResponse response = imageModel.call(imagePrompt);
    return response.getResult().getOutput().getUrl();
}

Generate Multiple Images

public List<String> generateMultipleImages(String prompt, int count) {
    OpenAiImageOptions options = OpenAiImageOptions.builder()
        .model("dall-e-2") // Only dall-e-2 supports n > 1
        .N(count)
        .width(512)
        .height(512)
        .build();

    ImagePrompt imagePrompt = new ImagePrompt(prompt, options);
    ImageResponse response = imageModel.call(imagePrompt);

    return response.getResults().stream()
        .map(generation -> generation.getOutput().getUrl())
        .toList();
}

Base64 Response Format

public String generateImageAsBase64(String prompt) {
    OpenAiImageOptions options = OpenAiImageOptions.builder()
        .responseFormat("b64_json")
        .build();

    ImagePrompt imagePrompt = new ImagePrompt(prompt, options);
    ImageResponse response = imageModel.call(imagePrompt);

    return response.getResult().getOutput().getB64Json();
}

Natural vs Vivid Style

public String generateNaturalImage(String prompt) {
    OpenAiImageOptions options = OpenAiImageOptions.builder()
        .model("dall-e-3")
        .style("natural") // More natural, less hyper-real
        .build();

    ImagePrompt imagePrompt = new ImagePrompt(prompt, options);
    ImageResponse response = imageModel.call(imagePrompt);
    return response.getResult().getOutput().getUrl();
}

public String generateVividImage(String prompt) {
    OpenAiImageOptions options = OpenAiImageOptions.builder()
        .model("dall-e-3")
        .style("vivid") // Hyper-real, dramatic (default)
        .build();

    ImagePrompt imagePrompt = new ImagePrompt(prompt, options);
    ImageResponse response = imageModel.call(imagePrompt);
    return response.getResult().getOutput().getUrl();
}

HD Quality Images

public String generateHDImage(String prompt) {
    OpenAiImageOptions options = OpenAiImageOptions.builder()
        .model("dall-e-3") // Only dall-e-3 supports HD
        .quality("hd")
        .width(1024)
        .height(1024)
        .build();

    ImagePrompt imagePrompt = new ImagePrompt(prompt, options);
    ImageResponse response = imageModel.call(imagePrompt);
    return response.getResult().getOutput().getUrl();
}

Access Response Metadata

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

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

    String url = image.getUrl();
    String revisedPrompt = generation.getMetadata().getRevisedPrompt();

    System.out.println("URL: " + url);
    System.out.println("Revised Prompt: " + revisedPrompt);
}

Configuration

Configure via application.properties:

# API Connection
spring.ai.openai.image.api-key=sk-...
spring.ai.openai.image.base-url=https://api.openai.com
spring.ai.openai.image.project-id=proj_...
spring.ai.openai.image.organization-id=org-...
spring.ai.openai.image.images-path=/v1/images/generations

# Model Configuration
spring.ai.openai.image.options.model=dall-e-3
spring.ai.openai.image.options.quality=standard
spring.ai.openai.image.options.size=1024x1024
spring.ai.openai.image.options.style=vivid
spring.ai.openai.image.options.response-format=url
spring.ai.openai.image.options.n=1
spring.ai.openai.image.options.width=1024
spring.ai.openai.image.options.height=1024

Model Options

Available Models

dall-e-3 - Latest, highest quality (default)
dall-e-2 - Previous generation, supports multiple images

Size Options

DALL-E 3 sizes:

1024x1024 (square, default)
1024x1792 (portrait)
1792x1024 (landscape)

DALL-E 2 sizes:

256x256
512x512
1024x1024

Quality Options (DALL-E 3 only)

standard - Standard quality (default)
hd - High definition, more detail

Style Options (DALL-E 3 only)

vivid - Hyper-real and dramatic (default)
natural - More natural, less hyper-real

Response Format

url - Returns publicly accessible URL (default, expires after 1 hour)
b64_json - Returns base64-encoded JSON

Number of Images

DALL-E 3: Only supports n=1
DALL-E 2: Supports n=1 to n=10

Response Structure

ImageResponse

package org.springframework.ai.image;

public class ImageResponse {
    public List<ImageGeneration> getResults();
    public ImageResponseMetadata getMetadata();
    public ImageGeneration getResult(); // Convenience method for first result
}

ImageGeneration

package org.springframework.ai.image;

public class ImageGeneration {
    public Image getOutput();
    public ImageGenerationMetadata getMetadata();
}

Image

package org.springframework.ai.image;

public class Image {
    public String getUrl();
    public String getB64Json();
}

ImageGenerationMetadata

package org.springframework.ai.image;

public class ImageGenerationMetadata {
    public String getRevisedPrompt();
}

Note: DALL-E 3 may revise prompts to improve safety and image quality. The revised prompt is available in metadata.

Error Handling

import org.springframework.ai.openai.api.OpenAiApiException;

public String safeGenerateImage(String prompt) {
    try {
        ImagePrompt imagePrompt = new ImagePrompt(prompt);
        ImageResponse response = imageModel.call(imagePrompt);
        return response.getResult().getOutput().getUrl();
    } catch (OpenAiApiException e) {
        // Handle API errors (content policy violations, rate limits, etc.)
        throw new RuntimeException("Image generation failed: " + e.getMessage(), e);
    }
}

Types

Builder

package org.springframework.ai.openai;

public static class Builder {
    public Builder model(String model);
    public Builder N(Integer n);
    public Builder quality(String quality);
    public Builder responseFormat(String responseFormat);
    public Builder width(Integer width);
    public Builder height(Integer height);
    public Builder style(String style);
    public Builder user(String user);
    public OpenAiImageOptions build();
}

ImagePrompt

package org.springframework.ai.image;

public class ImagePrompt {
    public ImagePrompt(String instructions);
    public ImagePrompt(String instructions, ImageOptions options);
    public ImagePrompt(ImageMessage message);
    public ImagePrompt(ImageMessage message, ImageOptions options);

    public List<ImageMessage> getInstructions();
    public ImageOptions getOptions();
}

ImageMessage

package org.springframework.ai.image;

public class ImageMessage {
    public ImageMessage(String text);
    public ImageMessage(String text, Float weight);

    public String getText();
    public Float getWeight();
}

Content Policy

OpenAI's content policy applies to image generation:

No violence, adult content, or hateful imagery
No celebrities or public figures
No copyrighted material
DALL-E 3 may automatically revise prompts for safety

Content policy violations will result in an error response.

tessl i tessl/maven-org-springframework-ai--spring-ai-starter-model-openai@1.1.1

docs

examples

guides

reference

audio-speech-model.md

audio-transcription-model.md