合集说明

本篇合并自参考文档「Models / Image Models」章节，覆盖图像模型 API 与各厂商实现，按官方文档顺序排列：（各篇之间以 --- 分隔）

1. Image Model API（图像模型 API）
2. OpenAI Image Generation（OpenAI 图像生成）
3. Azure OpenAI Image Generation（迁移提示）
4. Stability AI Image Generation（Stability AI 图像生成）
5. Google GenAI Image Generation（Google GenAI 图像生成）

Image Model API（图像模型 API）

📌 原文地址：https://docs.spring.io/java-ai/reference/api/imageclient.html 📌 原文版本：Java AI 2.0.1

白话解读

ImageModel API 是 Java AI 对所有图像生成模型（DALL-E、Stable Diffusion、Imagen 等）的统一抽象。它让你能用同一套 API 调用不同厂商的图像生成服务，切换厂商只需要改配置。

1. 简介

Spring Image Model API 设计目标是：

• 简单：几行代码就能生成图像
• 可移植：换厂商（OpenAI / Stability AI / Google）只需要改配置

围绕 ImageModel 接口，提供：

• ImagePrompt：输入封装
• ImageResponse：输出处理
• ImageMessage：单个文本提示（带权重）
• ImageOptions：可移植 + 模型特定的配置选项
• ImageGeneration / Image：单次生成结果

2. API 概述

Image Model API 构建在 Java AI Generic Model API 之上，提供图像特定的抽象。

3. ImageModel 接口

@FunctionalInterface
public interface ImageModel extends Model<ImagePrompt, ImageResponse> {

    ImageResponse call(ImagePrompt request);

}

4. ImagePrompt

public class ImagePrompt implements ModelRequest<List<ImageMessage>> {

    private final List<ImageMessage> messages;
    private ImageOptions imageModelOptions;

    @Override
    public List<ImageMessage> getInstructions() {...}

    @Override
    public ImageOptions getOptions() {...}
}

ImagePrompt 封装了多个 ImageMessage + 可选的模型选项。

5. ImageMessage

public class ImageMessage {

    private String text;     // 提示文本
    private Float weight;   // 权重（正数或负数，取决于模型支持）

    public String getText() {...}
    public Float getWeight() {...}
}

小技巧

权重让支持该特性的模型（如 Stable Diffusion）能区分主要提示和次要提示。比如"一只猫，正权重" + "卡通风格，弱权重"。

6. ImageOptions

public interface ImageOptions extends ModelOptions {

    Integer getN();                      // 生成数量
    String getModel();                   // 模型名
    Integer getWidth();                  // 宽度
    Integer getHeight();                 // 高度
    String getResponseFormat();          // "url"/"base64"/"byte[]" 等

}

每个厂商有自己的特定选项：

• OpenAI: quality、style
• Stability AI: steps、cfg_scale、sampler、style_preset

小技巧

两阶段配置：启动时用厂商特定选项配置默认值，运行时用 ImagePrompt 覆盖——兼顾配置简洁和灵活性。

7. ImageResponse

public class ImageResponse implements ModelResponse<ImageGeneration> {

    private final ImageResponseMetadata imageResponseMetadata;
    private final List<ImageGeneration> imageGenerations;

    @Override
    public ImageGeneration getResult() {
        return getResults().get(0);     // 默认取第一个
    }

    @Override
    public List<ImageGeneration> getResults() {...}

    @Override
    public ImageResponseMetadata getMetadata() {...}
}

每个 ImageGeneration 包含从一次提示生成的多个输出之一。

8. ImageGeneration

public class ImageGeneration implements ModelResult<Image> {

    private ImageGenerationMetadata imageGenerationMetadata;
    private Image image;

    @Override
    public Image getOutput() {...}

    @Override
    public ImageGenerationMetadata getMetadata() {...}
}

9. 可用的实现

厂商	模型系列	starter
OpenAI	DALL-E 2、DALL-E 3、gpt-image-1	spring-ai-starter-model-openai
Stability AI	Stable Diffusion v1.6 等	spring-ai-starter-model-stability-ai
Google GenAI	Imagen（gemini-2.5-flash-image 等）	spring-ai-starter-model-google-genai-image

10. 小结

ImageModel API 是 Java AI 中所有图像相关功能的统一入口。它的设计哲学跟 ChatModel / EmbeddingModel 一脉相承：

• 一个核心接口（ImageModel）
• 一组配套类（ImagePrompt / ImageResponse / ImageGeneration）
• 厂商特定的扩展（OpenAiImageOptions / StabilityAiImageOptions 等）

理解了这些基础概念，后续章节（OpenAI/Stability/Google 图像生成）就是配置细节的差异。

---

OpenAI Image Generation（OpenAI 图像生成）

📌 原文地址：https://docs.spring.io/java-ai/reference/api/image/openai-image.html 📌 原文版本：Java AI 2.0.1

白话解读

OpenAI 的图像生成模型（DALL-E 系列、gpt-image-1）支持文生图、图生图。Java AI 通过 OpenAI starter 接入，从 2.0.0-M5 起底层切到官方 openai-java SDK。

1. 简介

Java AI 支持 OpenAI 的 DALL-E 系列图像生成模型：

• DALL-E 2：旧版，性价比款
• DALL-E 3：经典款，质量好，支持 HD 质量 + vivid/natural 风格
• gpt-image-1：最新多模态图像生成模型（默认 gpt-image-1-mini）

2. 准备工作

1. 在 https://platform.openai.com 注册账号。
2. 到 https://platform.openai.com/api-keys 生成 API Key。
3. 配置 spring.ai.openai.api-key。

2.1 安全做法

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}

export OPENAI_API_KEY=<your-openai-api-key>

3. 自动配置

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

4. 连接属性（与 Chat 共用）

属性	描述	默认值
spring.ai.openai.base-url	API 入口	api.openai.com
spring.ai.openai.api-key	API Key	-
spring.ai.openai.organization-id	组织 ID	-
spring.ai.openai.project-id	项目 ID	-
spring.ai.openai.timeout	请求超时	60 sec
spring.ai.openai.max-retries	客户端内置重试	3
spring.ai.openai.proxy	代理	-
spring.ai.openai.custom-headers	自定义 HTTP 头	empty
spring.ai.openai.connection-pool-metrics-enabled	OkHttp 连接池指标	false

5. 图像生成属性

5.1 重试属性

属性	描述	默认值
spring.ai.retry.max-attempts	最大重试次数	10
spring.ai.retry.backoff.initial-interval	指数退避初始间隔	2 sec
spring.ai.retry.backoff.multiplier	退避乘数	5
spring.ai.retry.backoff.max-interval	最大退避时长	3 min
spring.ai.retry.on-client-errors	4xx 错误是否重试	false
spring.ai.retry.exclude-on-http-codes	不重试的 HTTP 状态码	empty
spring.ai.retry.on-http-codes	触发重试的 HTTP 状态码	empty

5.2 启用开关

spring:
  ai:
    model:
      image: openai       # 默认启用
      # image: none      # 禁用

5.3 模型配置属性

属性	描述	默认值
spring.ai.openai.image.n	生成数量（1~10，dall-e-3 只支持 1）	-
spring.ai.openai.image.model	模型名	gpt-image-1-mini
spring.ai.openai.image.quality	图像质量（仅 dall-e-3：hd/standard）	-
spring.ai.openai.image.response_format	返回格式：url 或 b64_json	-
spring.ai.openai.image.size	尺寸字符串（dall-e-2：256x256、512x512、1024x1024；dall-e-3：1024x1024、1792x1024、1024x1792）	-
spring.ai.openai.image.size_width	宽度（dall-e-2：256、512、1024）	-
spring.ai.openai.image.size_height	高度（dall-e-2：256、512、1024）	-
spring.ai.openai.image.style	风格（仅 dall-e-3：vivid/natural）	-
spring.ai.openai.image.user	最终用户唯一标识	-

5.4 覆盖通用属性

跟 Chat 一样，可以为 image 单独配置 base-url / api-key：

spring:
  ai:
    openai:
      base-url: https://api.openai.com
      chat:
        base-url: https://chat.openai.com
      image:
        base-url: https://image.openai.com

6. 运行时选项

ImageResponse response = openaiImageModel.call(
    new ImagePrompt("A light cream colored mini golden doodle",
        OpenAiImageOptions.builder()
                .quality("hd")
                .n(4)
                .height(1024)
                .width(1024)
                .build()));

也可以用 ImageOptionsBuilder#builder() 创建可移植的 options。

7. 自定义 HTTP 客户端

跟 Chat/Embedding 一样，通过 OpenAiHttpClientBuilderCustomizer 拦截 OkHttp 客户端构建：

@FunctionalInterface
public interface OpenAiHttpClientBuilderCustomizer {
    void customize(SpringAiOpenAiHttpClient.Builder builder);
}

典型用例：注册 OkHttp Interceptor、配置代理、SSL、连接池等。

var chatModel = OpenAiChatModel.builder()
    .options(OpenAiChatOptions.builder().model("gpt-4o").build())
    .httpClientBuilderCustomizer(myCustomizer)
    .build();

8. 模型对比

模型	适用场景	支持参数
dall-e-2	旧版生成，性价比	size, n, response_format
dall-e-3	高质量文生图	size, quality (hd/standard), style (vivid/natural), n=1
gpt-image-1	最新多模态生成	多模态输入
gpt-image-1-mini	性价比版（默认）	多模态输入

9. 完整示例

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      image:
        model: dall-e-3
        quality: hd
        size: 1792x1024
        style: vivid

@RestController
public class ImageController {

    private final ImageModel imageModel;

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

    @GetMapping("/ai/image")
    public Map<String, Object> generate(
            @RequestParam(value = "message", defaultValue = "A light cream colored mini golden doodle") String message) {
        ImageResponse response = imageModel.call(new ImagePrompt(message));
        // response.getResult().getOutput().getUrl() 拿到图像 URL
        return Map.of("images", response);
    }
}

10. 注意事项

注意

• dall-e-3 只支持 n=1：想生成多张图只能多次调用。
• 质量参数 hd 仅 dall-e-3：其他模型不支持。
• 风格参数 style 仅 dall-e-3：vivid（戏剧性）或 natural（自然）。
• 响应 URL 过期：默认返回的 URL 有效期 1 小时，要长期保存请用 response_format=b64_json。
• gpt-image-1 多模态：支持文本 + 图像输入，更灵活但 API 用法略不同。

11. 小结

OpenAI Image Generation 的特点：

• 统一入口：跟 Chat/Embedding 共用 OpenAI starter
• 多模型可选：DALL-E 2 / 3、gpt-image-1 按需选
• 质量与风格：HD、vivid/natural 让细节可控
• API 兼容：底层用 openai-java SDK，跟官方一致

适用场景：

• 营销素材：海报、社交媒体图
• 原型设计：UI/UX 概念图
• 内容创作：插画、配图

如果你需要更高艺术性或定制化，Stable Diffusion / Imagen 可能更合适。

---

Azure OpenAI Image Generation（迁移提示）

📌 原文地址：https://docs.spring.io/java-ai/reference/api/image/azure-openai-image.html 📌 原文版本：Java AI 2.0.1

白话解读

这一页在 Java AI 2.0.1 中只是个简短迁移通知——Azure OpenAI 图像生成模块已经合并到 OpenAI Image Generation 里。

1. 官方说明

原文翻译如下：

自 Java AI 2.0.0-M5 起，应使用 OpenAI Image 来访问部署在 Azure / Microsoft Foundry 上的 OpenAI 模型。

英文原文：

As of Java AI 2.0.0-M5, OpenAI Image should be used to access OpenAI models deployed on Azure / Microsoft Foundry.

2. 含义解读

• 不再维护单独的 Azure OpenAI 图像 starter
• 改用通用的 OpenAI Image 模块，把 base-url 指向 Azure endpoint
• 同时适用于 Azure OpenAI Service 与 Microsoft Foundry

3. 替代方案

3.1 通过 OpenAI Image 访问 Azure

spring:
  ai:
    openai:
      # Azure OpenAI 服务的 endpoint
      base-url: https://{your-resource}.openai.azure.com/openai/deployments/{your-deployment}
      api-key: ${AZURE_OPENAI_API_KEY}
      image:
        # 你的部署名（deployment name）
        model: dall-e-3
        quality: hd
        size: 1792x1024
        style: vivid

也可以只覆盖 image 专用 base-url：

spring:
  ai:
    openai:
      base-url: https://api.openai.com
      api-key: ${OPENAI_API_KEY}
      chat:
        model: gpt-4o
      image:
        base-url: https://{your-resource}.openai.azure.com/openai/deployments/{your-deployment}
        api-key: ${AZURE_OPENAI_API_KEY}
        model: dall-e-3

3.2 通过 Microsoft Foundry 访问

Microsoft Foundry 也支持 OpenAI 兼容端点：

spring:
  ai:
    openai:
      base-url: https://{your-foundry-endpoint}/v1
      api-key: ${FOUNDRY_API_KEY}
      image:
        model: dall-e-3

3.3 历史方案（已不推荐）

Java AI 2.0.0-M5 之前曾经有过：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-azure-openai</artifactId>
</dependency>

这个 starter 已经被弃用，请迁移到 OpenAI starter。

4. Azure 上常见的图像模型部署

部署名	实际模型	说明
dall-e-3	DALL-E 3	高质量
dall-e-2	DALL-E 2	性价比
gpt-image-1	GPT Image 1	最新多模态

白话解读

Azure 上的"部署名"（deployment name）跟实际的 OpenAI 模型名可以不一样。Java AI 用 spring.ai.openai.image.model 字段，它应该是部署名而不是模型 ID。

5. 注意事项

注意

• Azure endpoint 路径里必须包含 deployments/<your-deployment>，否则 Azure 会拒绝。
• Azure OpenAI 的 API 路径与 OpenAI 官方略有不同（多 /openai/deployments/<deployment>），注意不要照抄 OpenAI 的 URL。
• 部分 Azure 区域支持 v1 兼容 API，可直接用 https://<resource>.openai.azure.com/openai/v1 + 部署名作为 model。
• DALL-E 3 在 Azure 上需要单独申请权限（不像 GPT-4 默认开放）。

6. 小结

Azure OpenAI Image Generation 在 Java AI 2.0.1 中已经没有独立页面——改用 OpenAI Image 模块加 Azure 端点即可。这种统一入口的设计让 Java AI 在跨厂商（OpenAI 官方、Azure、Microsoft Foundry）时非常省事。

如果你需要更详细的 Azure 特定配置（如 AAD 身份验证、Managed Identity），可参考 OpenAI Image 页面的"连接属性"和"运行时选项"部分，结合 Azure 官方文档。

---

Stability AI Image Generation（Stability AI 图像生成）

📌 原文地址：https://docs.spring.io/java-ai/reference/api/image/stabilityai-image.html 📌 原文版本：Java AI 2.0.1

白话解读

Stability AI 是 Stable Diffusion 模型背后的厂商。Java AI 提供专用 starter，能调扩散步数、CFG scale、采样器、风格预设等高级参数——比 DALL-E 更精细。

1. 简介

Stability AI 提供文生图模型（Stable Diffusion 系列）。Java AI 集成它的 API，提供丰富的生成参数控制。

主要模型：

• stable-diffusion-v1-6（默认）
• stable-diffusion-xl-1024-v1-0
• stable-diffusion-3-*

2. 准备工作

1. 到 https://platform.stability.ai 注册账号。
2. 在 API Keys 页面生成令牌。
3. 配置 spring.ai.stabilityai.api-key。

spring:
  ai:
    stabilityai:
      api-key: ${STABILITYAI_API_KEY}

export STABILITYAI_API_KEY=<your-stabilityai-api-key>

3. 自动配置

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-stability-ai</artifactId>
</dependency>

4. 连接属性

属性	描述	默认值
spring.ai.stabilityai.base-url	API 入口	api.stability.ai/v1
spring.ai.stabilityai.api-key	API Key	-

5. 启用开关

spring:
  ai:
    model:
      image: stabilityai     # 默认启用
      # image: none        # 禁用

6. 图像生成属性

属性	描述	默认值
spring.ai.stabilityai.image.n	生成数量（1~10）	1
spring.ai.stabilityai.image.model	模型名	stable-diffusion-v1-6
spring.ai.stabilityai.image.width	宽度（像素，必须被 64 整除）	512
spring.ai.stabilityai.image.height	高度（像素，必须被 64 整除）	512
spring.ai.stabilityai.image.response-format	返回格式：application/json 或 image/png	-
spring.ai.stabilityai.image.cfg_scale	提示词遵循严格度（0~35）	7
spring.ai.stabilityai.image.clip_guidance_preset	CLIP 引导预设	NONE
spring.ai.stabilityai.image.sampler	扩散采样器（省略则自动选）	-
spring.ai.stabilityai.image.seed	随机噪声种子（0~4294967295）	0
spring.ai.stabilityai.image.steps	扩散步数（10~50）	30
spring.ai.stabilityai.image.style_preset	风格预设（如 cinematic、photographic）	-

7. 关键参数说明

7.1 cfg_scale（CFG = Classifier-Free Guidance）

控制模型"多严格地遵循你的提示"：

• 值越高：图像越贴合文字描述，但可能过度饱和、不自然
• 值越低：图像更自由、更多样，但可能偏离提示
• 典型值：7（默认）、10_{15（更严格）、3}5（更自由）

7.2 steps（扩散步数）

控制去噪迭代次数：

• 步数越多：图像越精细，但耗时翻倍
• 步数越少：速度快，但细节少
• 典型值：30（默认）、50（高质量）、20（快速草稿）

7.3 style_preset（风格预设）

常用预设：

值	风格
photographic	摄影风格
cinematic	电影风格
anime	动漫风格
comic-book	漫画风格
digital-art	数字艺术
enhance	增强细节
fantasy-art	奇幻艺术
isometric	等距视图
low-poly	低多边形
neon-punk	霓虹朋克
origami	折纸
pixel-art	像素艺术
tile-texture	瓷砖纹理
3d-model	3D 模型

8. 运行时选项

ImageResponse response = stabilityaiImageModel.call(
    new ImagePrompt("A light cream colored mini golden doodle",
        StabilityAiImageOptions.builder()
                .stylePreset("cinematic")   // 电影风格
                .n(4)                       // 生成 4 张
                .height(1024)
                .width(1024)
                .steps(50)                  // 高质量
                .cfgScale(10)               // 严格遵循提示
                .build()));

也可以用 ImageOptionsBuilder#builder() 创建可移植的 options。

9. 完整示例

spring:
  ai:
    stabilityai:
      api-key: ${STABILITYAI_API_KEY}
      image:
        model: stable-diffusion-xl-1024-v1-0
        steps: 40
        cfg_scale: 8
        style_preset: photographic
        width: 1024
        height: 1024

@RestController
public class ImageController {

    private final ImageModel imageModel;

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

    @GetMapping("/ai/image")
    public Map<String, Object> generate(
            @RequestParam(value = "message", defaultValue = "A light cream colored mini golden doodle") String message) {
        ImageResponse response = imageModel.call(new ImagePrompt(message));
        return Map.of("images", response);
    }
}

10. 注意事项

注意

• 尺寸必须被 64 整除：常见值 512、768、1024，不要选 600、900。
• response-format=image/png：直接返回 PNG 字节流，便于在 Web 里展示；application/json 返回 base64 编码。
• 种子固定可复现：相同 prompt + seed + steps + cfg_scale 会生成几乎一致的图像，方便调试。
• 模型定价：Stable Diffusion 按扩散步数计费，步数越多越贵。

11. 小结

Stability AI Image Generation 的特点：

• 参数丰富：CFG scale、steps、sampler、style preset 等细节可控
• 艺术性更强：Stable Diffusion 在风格化、创意图像上比 DALL-E 更强
• 可复现：seed 固定可重现图像
• 多尺寸引擎：XL、v3 等不同模型按需选

适用场景：

• 风格化内容：动漫、奇幻、赛博朋克等
• 概念设计：游戏、影视、产品概念图
• 大批量生成：CF 生成、素材库建设

如果你需要快速生成、要求文字描述精准贴合，DALL-E 3 更合适；如果追求艺术性和参数控制，Stability AI 是首选。

---

Google GenAI Image Generation（Google GenAI 图像生成）

📌 原文地址：https://docs.spring.io/java-ai/reference/api/image/google-genai-image.html 📌 原文版本：Java AI 2.0.1

白话解读

Google 的图像生成模型（Imagen 系列）走 GenAI 接口，既能用 Gemini Developer API（API Key 快速接入），也能用 Vertex AI（GCP 生产部署）。支持宽高比、安全过滤级别、人物生成策略等独特参数。

1. 简介

Google GenAI 图像生成提供：

• gemini-2.5-flash-image：性价比款，主流通用图像生成
• gemini-3-pro-image：高质量款，对标 GPT-Image-1
• gemini-3.1-flash-image：最新高效率款

支持两种鉴权：

• Gemini Developer API：用 API Key 接入，适合快速开发
• Vertex AI：用 Google Cloud 凭证接入，适合生产部署

2. 准备工作

方式 A：Gemini Developer API

到 https://aistudio.google.com/apikey 申请 API Key。

方式 B：Vertex AI

gcloud config set project <PROJECT_ID>
gcloud auth application-default login <ACCOUNT>

3. 自动配置

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-google-genai-image</artifactId>
</dependency>

4. 连接属性

连接属性与 Google GenAI Chat 共用一份配置。

属性	描述	默认值
spring.ai.google.genai.image.api-key	Gemini Developer API Key	-
spring.ai.google.genai.image.project-id	GCP 项目 ID（Vertex AI 模式必填）	-
spring.ai.google.genai.image.location	GCP 区域（Vertex AI 模式必填）	-
spring.ai.google.genai.image.credentials-uri	GCP 凭证 URI（可选）	-

5. 启用开关

spring:
  ai:
    model:
      image: google-genai     # 默认启用
      # image: none         # 禁用

6. 图像生成属性

属性	描述	默认值
spring.ai.model.image	启用 GenAI 图像	google-genai
spring.ai.google.genai.image.n	生成数量（1~4）	-
spring.ai.google.genai.image.model	模型名	-
spring.ai.google.genai.image.aspect-ratio	宽高比（1:1、3:4、4:3、9:16、16:9）	1:1
spring.ai.google.genai.image.seed	随机种子（add-watermark=true 时不可用）	-
spring.ai.google.genai.image.safety-filter-level	安全过滤级别	-
spring.ai.google.genai.image.person-generation	人物生成策略	-
spring.ai.google.genai.image.output-mime-type	输出 MIME 类型	-
spring.ai.google.genai.image.output-compression-quality	JPEG 压缩质量（仅 image/jpeg）	-
spring.ai.google.genai.image.labels	跟踪计费的标签	-
spring.ai.google.genai.image.image-size	最大维度（1K、2K）	-
spring.ai.google.genai.image.temperature	采样温度	-
spring.ai.google.genai.image.top-p	核采样	-
spring.ai.google.genai.image.top-k	top-k 采样	-
spring.ai.google.genai.image.max-output-tokens	最大输出 token 数	-

6.1 安全过滤级别

值	行为
BLOCK_LOW_AND_ABOVE	低/中/高概率不安全都阻止
BLOCK_MEDIUM_AND_ABOVE	中/高概率阻止
BLOCK_ONLY_HIGH	仅高概率阻止
BLOCK_NONE	不阻止
SAFETY_FILTER_LEVEL_UNSPECIFIED	未指定，用默认阈值

6.2 人物生成策略

值	行为
DONT_ALLOW	阻止生成人物
ALLOW_ADULT	允许成人，不允许儿童
ALLOW_ALL	允许所有（包括儿童）
PERSON_GENERATION_UNSPECIFIED	未指定，用默认阈值

小技巧

人物生成策略是 Google 独有的合规控制——欧盟、美国对儿童图像生成有严格法规（如 COPPA），强烈建议生产环境用 ALLOW_ADULT 或 DONT_ALLOW。

7. 示例控制器

7.1 使用 Gemini Developer API

spring.ai.google.genai.image.api-key=YOUR_API_KEY
spring.ai.google.genai.image.model=gemini-2.5-flash-image

7.2 使用 Vertex AI

spring.ai.google.genai.image.project-id=YOUR_PROJECT_ID
spring.ai.google.genai.image.location=YOUR_PROJECT_LOCATION
spring.ai.google.genai.image.model=gemini-2.5-flash-image

@RestController
public class ImageController {

    private final ImageModel imageModel;

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

    @GetMapping("/ai/image")
    public Map<String, Object> generate(
            @RequestParam(value = "message", defaultValue = "A painting of a sunset over a mountain") String message) {
        ImagePrompt imagePrompt = new ImagePrompt(message);
        ImageResponse imageResponse = this.imageModel.call(imagePrompt);
        return Map.of("images", imageResponse);
    }
}

8. 手动配置（不用 Starter）

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-google-genai-image</artifactId>
</dependency>

8.1 使用 API Key

GoogleGenAiImageConnectionDetails connectionDetails =
    GoogleGenAiImageConnectionDetails.builder()
        .apiKey(System.getenv("GOOGLE_API_KEY"))
        .build();

GoogleGenAiImageOptions options = GoogleGenAiImageOptions.builder()
    .model(GoogleGenAiImageOptions.DEFAULT_MODEL_NAME)
    .build();

var imageModel = new GoogleGenAiImageModel(connectionDetails, options);

ImageResponse imageResponse = imageModel.call(new ImagePrompt("A painting of a sunset over a mountain"));

8.2 使用 Vertex AI

GoogleGenAiImageConnectionDetails connectionDetails =
    GoogleGenAiImageConnectionDetails.builder()
        .projectId(System.getenv("GOOGLE_CLOUD_PROJECT"))
        .location(System.getenv("GOOGLE_CLOUD_LOCATION"))
        .build();

var imageModel = new GoogleGenAiImageModel(connectionDetails,
    GoogleGenAiImageOptions.builder()
        .model("gemini-2.5-flash-image")
        .build());

ImageResponse imageResponse = imageModel.call(new ImagePrompt("A painting of a sunset over a mountain"));

9. 注意事项

注意

• 多模态输入：gemini-2.5-flash-image 等模型支持文本 + 图像输入，可以做对话式编辑。
• API Key 与 Vertex 不能混用：要么用 API Key，要么用 Vertex AI 的 project-id + location。
• 安全过滤默认开启：生产环境务必设置 safety-filter-level，避免输出不合规内容。
• 人物生成严格控制：欧盟、美国对儿童图像生成有法规约束，请谨慎设置 ALLOW_ALL。
• 图像最大尺寸：默认只支持 1K，2K 需要显式设置 image-size=2K。

10. 小结

Google GenAI Image Generation 的特点：

• 双鉴权：API Key 快速原型 + Vertex AI 生产部署
• 合规友好：自带安全过滤 + 人物生成策略
• 多模态：支持对话式编辑（用文本指令修改已有图像）
• Gemini 模型：与 Gemini 多模态模型共享架构

适用场景：

• GCP 生态：统一鉴权、计费、合规
• 合规要求高：医疗、教育、儿童内容
• 需要编辑能力：对话式修改图像

如果你主要用 OpenAI 或追求艺术风格，OpenAI Image / Stability AI 更合适。

版权所有

版权归属：今朝· Liushigong · Relax Box

许可证：署名-非商业性 4.0 国际 (CC-BY-NC-4.0)

贡献者: Jinzhao