Image Generation and Vision in Spring AI: ImageModel, Prompt Options and Safe Storage

Versions, and an honest limit. Spring Boot 4.1.2 and Spring AI 2.0.2 (both on Maven Central since 2026-10-22), AWS SDK for Java 2.57.5, Testcontainers 2.0.5 and Java 25. The code is the image-gen module of asmhatre/spring-ai, and every console block below is quoted from a file under its output/ directory. I did not call any image provider. There are no API keys in my build environment, so the tests use a hand-written ImageModel that returns what it is told to, a hand-written ModerationModel, and, for the wire tests, the real OpenAiImageModel talking to a local mock that returns a fixed 64×64 picture whatever the prompt says. Nothing here measures image quality, speed, or whether a real model would refuse a prompt. The storage is real: the bucket tests run against a MinIO server in Docker through Testcontainers. Prices were read from the providers’ pages on 2026-10-28 and are copied, not tested.

An image model is a function from a prompt to bytes

interface            : org.springframework.ai.image.ImageModel
single method        : [call]
request              : org.springframework.ai.image.ImagePrompt
OpenAI               : org.springframework.ai.openai.OpenAiImageModel
Stability AI         : org.springframework.ai.stabilityai.StabilityAiImageModel
moderation interface : org.springframework.ai.moderation.ModerationModel
moderation OpenAI    : org.springframework.ai.openai.OpenAiModerationModel

  <dependencies>
    <dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-model</artifactId></dependency>
    <dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-client-chat</artifactId></dependency>
    <dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-openai</artifactId></dependency>
    <dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-stability-ai</artifactId></dependency>
    <dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-google-genai-image</artifactId></dependency>
    <dependency><groupId>software.amazon.awssdk</groupId><artifactId>s3</artifactId></dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-test</artifactId>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.testcontainers</groupId>
      <artifactId>testcontainers-junit-jupiter</artifactId>
      <scope>test</scope>
    </dependency>
  </dependencies>

Writing the test first: an ImageModel you can script

    @Override
    public ImageResponse call(ImagePrompt prompt) {
        seen.add(prompt);
        if (script.isEmpty()) {
            throw new IllegalStateException("ScriptedImageModel has no response left for call #" + seen.size());
        }
        ImageResponse next = script.poll();
        if (next == null) {
            throw throwables.poll();
        }
        return next;
    }

What the real OpenAiImageModel puts on the wire

    private static OpenAiImageModel model(String defaultModel) {
        return OpenAiImageModel.builder().options(OpenAiImageOptions.builder()
                .baseUrl(server.baseUrl()).apiKey("test-key-not-real").model(defaultModel).maxRetries(0).build()).build();
    }

1. ImagePrompt("a red bicycle"), model default only
   POST /v1/images/generations
   {"prompt":"a red bicycle","model":"gpt-image-test"}

2. OpenAiImageOptions size=1536x1024 quality=high n=2
   {"prompt":"a red bicycle","model":"gpt-image-1-mini","n":2,"quality":"high","size":"1536x1024"}

3. portable ImageOptionsBuilder width=1024 height=1536
   {"prompt":"a red bicycle","model":"gpt-image-test","size":"1024x1536"}

4. OpenAiImageOptions user=user-8f2c
   {"prompt":"a red bicycle","model":"gpt-image-1-mini","user":"user-8f2c"}

5. OpenAiImageOptions responseFormat=b64_json
   {"prompt":"a red bicycle","model":"gpt-image-1-mini","response_format":"b64_json"}

Set the model on every per-call options object. In 2.0.2 an OpenAiImageOptions passed to ImagePrompt does not inherit the model configured on the OpenAiImageModel; it replaces it with OpenAiImageOptions.DEFAULT_IMAGE_MODEL. If you configured a more expensive or more capable model for quality, a bare .size(...) call quietly downgrades it. The code in this module sets the model in one place (shown below) so it cannot be forgotten. I observed this on the wire; I did not read the merge code to find which line causes it. The earlier providers article found the same kind of reset for chat options.

6a. ImagePrompt(List<ImageMessage>) with no options: IllegalArgumentException: image options cannot be null
6b. same two messages (weights 1.0 and -1.0) with empty OpenAiImageOptions
   {"prompt":"a red bicycle","model":"gpt-image-1-mini"}

portable ImageOptions getters : [getHeight, getModel, getN, getResponseFormat, getStyle, getWidth]
OpenAiImageOptions getters    : [getApiKey, getBaseUrl, getCredential, getCustomHeaders, getDeploymentName, getHeight, getMaxRetries, getMicrosoftDeploymentName, getMicrosoftFoundryServiceVersion, getModel, getN, getOrganizationId, getProxy, getQuality, getResponseFormat, getSize, getStyle, getTimeout, getUser, getWidth, isGitHubModels, isMicrosoftFoundry]
StabilityAiImageOptions       : [getCfgScale, getClipGuidancePreset, getHeight, getModel, getN, getResponseFormat, getSampler, getSeed, getSteps, getStyle, getStylePreset, getWidth]
GoogleGenAiImageOptions       : [getAspectRatio, getHeight, getImageSize, getLabels, getMaxOutputTokens, getModel, getN, getOutputCompressionQuality, getOutputMimeType, getPersonGeneration, getResponseFormat, getSafetyFilterLevel, getSeed, getStyle, getTemperature, getTopK, getTopP, getWidth]

Sizes and quality: ask for what the provider can actually do

    @Override
    public ImageOptions apply(ImageRequest r) {
        String size = r.size() == null ? "1024x1024" : r.size();
        String quality = r.quality() == null ? "medium" : r.quality();
        if (!SIZES.contains(size)) {
            throw new RejectedException("bad-size", size + " not in " + new java.util.TreeSet<>(SIZES));
        }
        if (!QUALITIES.contains(quality)) {
            throw new RejectedException("bad-quality", quality + " not in " + new java.util.TreeSet<>(QUALITIES));
        }
        if (r.n() < 1 || r.n() > 4) {
            throw new RejectedException("bad-n", "n must be 1..4");
        }
        return OpenAiImageOptions.builder().model(model).size(size).quality(quality).n(r.n()).build();
    }

size not in list         -> bad-size: 9999x9999 not in [1024x1024, 1024x1536, 1536x1024]
quality not in list      -> bad-quality: ultra not in [high, low, medium]

results                 : 1
Image.getUrl()          : null
Image.getB64Json() len  : 10500 chars
metadata type           : OpenAiImageGenerationMetadata
revised prompt          : a rewritten prompt
response created        : 1760000000
response usage          : EmptyUsage, total tokens 0 (the mock body carried usage.total_tokens=1068)

URL mode: Image.getUrl() = http://127.0.0.1:43039/files/ok.png
URL mode: Image.getB64Json() = null

Moderation: what Spring AI gives you, and what it does not

• It is not connected to ImageModel. ImageModel has a single call method; no moderation happens inside it. If you do not call ModerationModel, nothing does it for you at the library level.
• It is text only. ModerationMessage has one getter, getText (printed in 01-api-shape.txt). OpenAI’s moderation guide says omni-moderation-latest accepts images (files up to 20 MB) and that the endpoint is free to use. Spring AI’s wrapper has nowhere to put the image. Checking a generated picture means calling the OpenAI SDK or an HTTP client yourself. I did not build or run that.
• The provider’s own filter is not exposed as an option. OpenAI’s guide says all prompts and generated images are filtered, and that GPT Image models have a moderation request parameter (auto or low). OpenAiImageOptions in 2.0.2 has no such getter or builder method; the test prints false for it. You get the default strictness.
• Google’s equivalents are exposed. GoogleGenAiImageOptions has safetyFilterLevel and personGeneration, with the enum values printed in the same file. Google’s image documentation also says every generated image carries a SynthID watermark; that is the provider’s doing, and I did not inspect an image to confirm it.
• A provider refusal arrives as an exception, not a flag. Below.

exception class   : com.openai.errors.BadRequestException
message (first 200): 400: Your request was rejected as a result of our safety system.
requests received : 1 (maxRetries=0)

    public void check(String prompt) {
        if (prompt == null || prompt.isBlank()) {
            throw new RejectedException("empty-prompt", "prompt is blank");
        }
        if (prompt.length() > policy.maxPromptChars()) {
            throw new RejectedException("prompt-too-long", prompt.length() + " > " + policy.maxPromptChars());
        }
        if (prompt.chars().anyMatch(c -> Character.isISOControl(c) && c != '\n' && c != '\t')) {
            throw new RejectedException("control-characters", "prompt contains control characters");
        }
        List<String> flagged = new ArrayList<>();
        try {
            for (ModerationResult r : moderation.call(new ModerationPrompt(prompt)).getResult().getOutput().getResults()) {
                if (r.isFlagged()) {
                    flagged.addAll(flaggedCategories(r.getCategories()));
                }
            }
        } catch (RuntimeException e) {
            throw new RejectedException("moderation-unavailable", e.getClass().getSimpleName());
        }
        if (!flagged.isEmpty()) {
            throw new RejectedException("prompt-flagged", String.join(",", flagged));
        }
    }

flagged by moderation    -> prompt-flagged: violence
blank prompt             -> empty-prompt: prompt is blank

moderation endpoint down -> moderation-unavailable: IllegalStateException
ImageModel calls : 0
objects stored   : 0

Failing closed is a product decision. If the moderation endpoint is down and you refuse every prompt, your image feature is down too. If you let prompts through when moderation is down, your policy is only as available as a third-party endpoint. I chose to fail closed because the cost of a wrong image is higher than the cost of an error page; yours may differ. The fake here says nothing about how good a real moderation model is at your categories. Measure that with your own examples.

Safe storage: the bytes are untrusted input

input                                         verdict   detail
real PNG 64x48                                ACCEPT    image/png 64x48
real JPEG 64x48                               ACCEPT    image/jpeg 64x48
WebP header only (sniffed, not decoded)       ACCEPT    image/webp
SVG with a script                             REJECT    not-an-image: no known image signature in the first bytes
HTML page                                     REJECT    not-an-image: no known image signature in the first bytes
PDF                                           REJECT    not-an-image: no known image signature in the first bytes
PNG signature + garbage                       REJECT    undecodable: IIOException
valid PNG + 40 bytes of HTML appended         ACCEPT    image/png 16x16
PNG header claiming 40000x40000               REJECT    too-many-pixels: 40000x40000 = 1600000000 > cap 16000000
GIF (sniffed but not on the allow list)       REJECT    type-not-allowed: image/gif
empty                                         REJECT    not-an-image: no known image signature in the first bytes
9 MB of PNG-looking zeros                     REJECT    too-large: 9437184 bytes > cap 8388608

    public Sniffed verify(byte[] bytes) {
        if (bytes.length > policy.maxBytes()) {
            throw new RejectedException("too-large", bytes.length + " bytes > cap " + policy.maxBytes());
        }
        Sniffed s = ImageSniffer.sniff(bytes)
                .orElseThrow(() -> new RejectedException("not-an-image", "no known image signature in the first bytes"));
        if (!policy.allowedTypes().contains(s.contentType())) {
            throw new RejectedException("type-not-allowed", s.contentType());
        }
        if (s.pixels() > policy.maxPixels()) {
            throw new RejectedException("too-many-pixels", s.width() + "x" + s.height() + " = " + s.pixels() + " > cap " + policy.maxPixels());
        }
        if (!s.contentType().equals("image/webp")) {
            try {
                BufferedImage img = ImageIO.read(new ByteArrayInputStream(bytes));
                if (img == null) {
                    throw new RejectedException("undecodable", "signature says " + s.contentType() + " but no decoder accepts it");
                }
            } catch (IOException | RuntimeException e) {
                if (e instanceof RejectedException r) throw r;
                throw new RejectedException("undecodable", e.getClass().getSimpleName());
            }
        }
        return s;
    }

input             : valid 16x16 PNG followed by 25 bytes of <script>
ImageVerifier     : ACCEPT (image/png)
why it is still OK: the object is stored as Content-Type image/png with
                    Content-Disposition: attachment, so a browser will not run it as HTML.
                    The check is the header, not the sniffing.

naive writer : key naive/upload.png  Content-Type = text/html  (sender said so; the .png suffix did not matter)
ImageStore   : the verifier refuses these bytes first: 
               not-an-image: no known image signature in the first bytes
objects under naive/ : 1

    public StoredImage put(String owner, byte[] bytes, Sniffed sniffed, String revisedPrompt) {
        requireOwner(owner);
        byte[] raw = new byte[16];
        RANDOM.nextBytes(raw);
        String id = HexFormat.of().formatHex(raw);
        String key = keyFor(owner, id, sniffed.extension());
        String sha = sha256(bytes);
        s3.putObject(PutObjectRequest.builder()
                .bucket(bucket)
                .key(key)
                .contentType(sniffed.contentType())           // from the bytes, never from the sender
                .contentDisposition("attachment")             // browsers download instead of rendering
                .cacheControl("private, max-age=3600")
                .metadata(Map.of("sha256", sha, "owner", owner))
                .build(), RequestBody.fromBytes(bytes));
        return new StoredImage(key, id, sniffed.contentType(), bytes.length, sniffed.width(), sniffed.height(), sha, revisedPrompt);
    }

    public String keyFor(String owner, String id, String extension) {
        requireOwner(owner);
        if (!ID.matcher(id).matches()) {
            throw new RejectedException("bad-id", "an image id is 32 lowercase hex characters");
        }
        return "generated/" + owner + "/" + id + "." + extension;
    }

200 puts of identical bytes -> 200 distinct ids (a content hash would give 1)
owner '../admin'             -> bad-owner: owner must match [a-z0-9][a-z0-9-]{0,31}
owner 'user-42/../../x'      -> bad-owner: owner must match [a-z0-9][a-z0-9-]{0,31}
owner 'USER'                 -> bad-owner: owner must match [a-z0-9][a-z0-9-]{0,31}
owner ''                     -> bad-owner: owner must match [a-z0-9][a-z0-9-]{0,31}
owner 'a b'                  -> bad-owner: owner must match [a-z0-9][a-z0-9-]{0,31}
owner 'user-42\0'            -> bad-owner: owner must match [a-z0-9][a-z0-9-]{0,31}
owner 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' -> bad-owner: owner must match [a-z0-9][a-z0-9-]{0,31}
id    '../../etc/passwd'                 -> bad-id: an image id is 32 lowercase hex characters
id    'ABCDEF0123456789ABCDEF0123456789' -> bad-id: an image id is 32 lowercase hex characters
id    '0123'                             -> bad-id: an image id is 32 lowercase hex characters
id    '0123456789abcdef0123456789abcde/' -> bad-id: an image id is 32 lowercase hex characters
user-43 asks for user-42's id -> NoSuchKeyException (key is rebuilt under user-43/)

image            : chainguard/minio:latest
minio --version  : minio version RELEASE.2026-10-23T20-06-51Z (commit-id=76c06ff1d2cc844050fdeb1d54bf8fa70db72278)
Server header    : MinIO
stored key       : generated/user-42/4cf346e4b7008b1874935d7969e8ccb1.png
content type     : image/png, 6363 bytes, 64x48
sha256           : 7254899daa04ebf862c59d32d2d3280bb179e6c61899505c43aed169c6197bcb
HEAD Content-Type        : image/png
HEAD Content-Disposition : attachment
HEAD Cache-Control       : private, max-age=3600
HEAD metadata            : {owner=user-42, sha256=7254899daa04ebf862c59d32d2d3280bb179e6c61899505c43aed169c6197bcb}
read back equal  : true

signed URL, parameters   : X-Amz-Algorithm=... & X-Amz-Date=... & X-Amz-SignedHeaders=host & X-Amz-Credential=... & X-Amz-Expires=300 & X-Amz-Signature=...
GET signed URL           : 200, 742 bytes, Content-Type image/jpeg
Content-Disposition      : attachment
same URL, other owner    : 403
same path, no signature  : 403

Presigned URLs are bearer tokens. Anyone who holds the URL can read the object until it expires, and it ends up in browser history and proxy logs. Keep the lifetime short, and prefer generating one per request after you have checked that the logged-in user owns the id, rather than storing URLs. The ownership check here is structural (the owner is part of the rebuilt key) but the application still has to pass the session’s owner, not one from the request.

payload chars : 12582912  (decodes to about 9437184 bytes; cap is 8388608)
result        : too-large: base64 payload decodes to about 9437184 bytes > cap 8388608

case                               result
allowed host, 200                  OK 7875 bytes
302 redirect to the same host      fetch-status: 302
endless body (cap 1 MiB)           too-large: download passed the 1048576-byte cap
host not on the list               host-not-allowed: localhost
file:// URL                        bad-scheme: file
http:// when insecure is off       bad-scheme: http
cloud metadata address             host-not-allowed: 169.254.169.254

    private byte[] readCapped(InputStream in) throws IOException {
        try (in) {
            ByteArrayOutputStream out = new ByteArrayOutputStream();
            byte[] buf = new byte[8192];
            long total = 0;
            int n;
            while ((n = in.read(buf)) > 0) {
                total += n;
                if (total > policy.maxBytes()) {
                    throw new RejectedException("too-large", "download passed the " + policy.maxBytes() + "-byte cap");
                }
                out.write(buf, 0, n);
            }
            return out.toByteArray();
        }
    }

Putting it together: one service, four ways to fail early

    public List<StoredImage> generate(ImageRequest request) {
        gate.check(request.prompt());
        ImageOptions o = options.apply(request);
        ImageResponse response = model.call(new ImagePrompt(request.prompt(), o));

        record Pending(byte[] bytes, Sniffed sniffed, String revised) {}
        List<Pending> verified = new ArrayList<>();
        for (ImageGeneration g : response.getResults()) {
            byte[] bytes = bytesOf(g.getOutput());
            Sniffed sniffed = verifier.verify(bytes);
            String revised = g.getMetadata() instanceof OpenAiImageGenerationMetadata m ? m.getRevisedPrompt() : null;
            verified.add(new Pending(bytes, sniffed, revised));
        }
        List<StoredImage> stored = new ArrayList<>();
        for (Pending p : verified) {
            stored.add(store.put(request.owner(), p.bytes(), p.sniffed(), p.revised()));
        }
        return stored;
    }

result                     : not-an-image: no known image signature in the first bytes
objects under batch/       : 0

moderation saw   : [a red bicycle]
ImageModel calls : 1
options sent     : OpenAiImageOptions model=gpt-image-test size=1536x1024 quality=high n=1
prompt sent      : a red bicycle
stored           : generated/happy/65ed822c50b77fecbcedfd866b567c54.png  image/png  7875 bytes  64x64
revised prompt   : a red bicycle on a quiet street, photographic
objects in bucket under generated/happy/ : 1

allowed host           : stored generated/urls/f009e9267986ffc76e6b2aacec391b12.png (image/png, 7875 bytes)
metadata-service URL   : host-not-allowed: 169.254.169.254
garbage base64         : bad-base64: payload is not valid base64

What it costs, by provider

OpenAI, output only, text prompt tokens extra
model quality               1024x1024  1024x1536  1536x1024
gpt-image-2 low                $0.006     $0.005     $0.005
gpt-image-2 medium             $0.053     $0.041     $0.041
gpt-image-2 high               $0.211     $0.165     $0.165
gpt-image-1.5 low              $0.009     $0.013     $0.013
gpt-image-1.5 medium           $0.034      $0.05      $0.05
gpt-image-1.5 high             $0.133       $0.2       $0.2
gpt-image-1-mini low           $0.005     $0.006     $0.006
gpt-image-1-mini medium        $0.011     $0.015     $0.015
gpt-image-1-mini high          $0.036     $0.052     $0.052

Google Gemini image models, standard tier
gemini-3.1-flash-lite-image 1K     $0.0336
gemini-3.1-flash-image 0.5K        $0.045
gemini-3.1-flash-image 1K          $0.067
gemini-3.1-flash-image 2K          $0.101
gemini-3.1-flash-image 4K          $0.151
gemini-3-pro-image 1K-2K           $0.134
gemini-3-pro-image 4K              $0.24
gemini-2.5-flash-image 1K          $0.039

Stability AI, 1 credit = $0.01
Stable Image Ultra                  8.0 credits = $0.080
Stable Diffusion 3.5 Large          6.5 credits = $0.065
Stable Diffusion 3.5 Large Turbo    4.0 credits = $0.040
Stable Diffusion 3.5 Medium         3.5 credits = $0.035
Stable Image Core                   3.0 credits = $0.030
Stable Diffusion 3.5 Flash          2.5 credits = $0.025

What is deliberately missing from the table. (1) OpenAI’s two newest models, gpt-image-2.5-sunburst and gpt-image-2.5-flare, are listed on the pricing page in tokens only ($30 per 1M image output tokens, $8 per 1M image input tokens, $5 per 1M text input tokens); the guide gives a calculator but no fixed per-image table, so I give no per-image figure. (2) gpt-image-1 is not listed because the guide says it was shut down on 2026-10-23. (3) DALL-E is not in the pricing page’s image section on the date I read it, so I give no DALL-E price. (4) Stability: those credit prices are for the services the page lists (Stable Image Core, SD 3.5 and so on). Spring AI’s StabilityAiApi calls /v1/generation/{model}/text-to-image with a default of stable-diffusion-v1-6; that engine is not on the pricing page, so I cannot tell you what a call through the Spring AI module costs. (5) OpenAI’s figures are for the image output only; the prompt’s text tokens are billed on top. (6) Batch pricing exists on both the OpenAI and Google pages at roughly half the standard token rates; I list standard prices only.

1,000 images a day for 30 days = 30,000 images
gpt-image-2 medium 1024x1024       $1,590
gpt-image-1-mini medium 1024x1024  $330
gemini-3.1-flash-image 1K          $2,010
Stable Image Core                  $900

Generation or vision: which half do you need?

Should you even generate images on demand?

Often not on the request path. A generation call takes seconds on a good day and fails in ways your user cannot fix, so treat it as a background job with a status, not a blocking HTTP call. Count the refusals, because a rate of refused prompts is the first signal that your form invites something you did not intend. Keep the originals you store out of any public path. And if your product needs a few hundred fixed pictures, generate them once, review them by hand and ship them as static files: that is cheaper, safer and faster than any of the code above.

What this module does not show. It never ran against a real image model, so image quality, latency, real refusal behaviour and real invoices are all outside what I can claim. The bucket was a throwaway MinIO server, not S3. The checks stop what I tested them against; a determined attacker will test them against more.

Further reading

• The code: image-gen in asmhatre/spring-ai, with output/ holding every transcript quoted above, regenerated by scripts/run-all.sh (about 20 seconds, needs Docker).
• Multimodal Spring AI: Extract Structured Data from Images, the vision half.
• Anthropic Claude vs OpenAI vs Gemini in Spring AI 2.0, for the portable-versus-provider-specific options theme and the same options-reset trap in chat.
• Observability for Spring AI, for turning usage into cost. Image models have their own observation classes in org.springframework.ai.image.observation; I did not run them.
• Prompt Injection Defense in Spring AI.
• Spring AI 1.x to 2.0 migration guide.
• OpenAI: Image generation guide
• OpenAI: Moderation guide
• Google: Gemini image generation
• Stability AI: pricing
• Spring AI reference: Image Model API