Google GenAI 图像

Gemini 2.5 Flash 图像模型 和 Gemini 3.1 Flash 图像模型 通过 Gemini Developer API 或 Vertex AI，使用 Google 的图像模型提供图像生成。

它们在主流价位和低延迟下提供高质量的图像生成与对话式编辑。

它是 Gemini 3 Pro 图像模型 对应的高效率版本，为速度和大批量开发者用例而优化。

此实现提供两种认证模式：

• Gemini Developer API：使用 API 密钥快速做原型与开发
• Vertex AI：使用 Google Cloud 凭据进行带企业特性的生产部署

前置条件

选择以下认证方式之一：

选项一：Gemini Developer API（API 密钥）

• 从 Google AI Studio 获取一个 API 密钥
• 把 API 密钥设为环境变量或写在你的应用属性里

选项二：Vertex AI（Google Cloud）

• 安装适合你操作系统的 gcloud CLI。
• 通过运行以下命令进行身份认证。 把 PROJECT_ID 替换为你的 Google Cloud 项目 ID，把 ACCOUNT 替换为你的 Google Cloud 用户名。

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

添加仓库与 BOM

Spring AI 的制品发布在 Maven Central 和 Spring Snapshot 仓库中。 参见 制品仓库 一节，把这些仓库添加到你的构建系统。

为便于依赖管理，Spring AI 提供了一个 BOM（物料清单），以确保整个项目中使用一致版本的 Spring AI。参见 依赖管理 一节，把 Spring AI BOM 添加到你的构建系统。

自动配置

NOTE

Spring AI 的自动配置、starter 模块的制品名称发生了重大变更。 更多信息请参阅 升级说明。

Spring AI 为 Google GenAI 图像模型提供 Spring Boot 自动配置。 要启用它，请将以下依赖添加到你的项目的 Maven pom.xml 文件：

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

或添加到你的 Gradle build.gradle 构建文件。

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-google-genai-image'
}

TIP

参见 依赖管理 一节，把 Spring AI BOM 添加到你的构建文件。

图像生成属性

连接属性

前缀 spring.ai.google.genai.image 用作连接 Google GenAI 图像生成 API 的属性前缀。

NOTE

连接属性与 Google GenAI Chat 模块共享。如果你同时使用聊天和图像，你只需用一个前缀配置连接一次即可——用 spring.ai.google.genai 前缀（聊天）或 spring.ai.google.genai.image 前缀（图像）。

属性	描述	默认值
spring.ai.google.genai.image.api-key	Gemini Developer API 的 API 密钥。提供时，客户端使用 Gemini Developer API 而非 Vertex AI。	-
spring.ai.google.genai.image.project-id	Google Cloud Platform 项目 ID（Vertex AI 模式必需）	-
spring.ai.google.genai.image.location	Google Cloud 区域（Vertex AI 模式必需）	-
spring.ai.google.genai.image.credentials-uri	指向 Google Cloud 凭据的 URI。提供时用于创建一个 GoogleCredentials 实例以认证。	-

NOTE

自动配置的启用与禁用，现通过以 spring.ai.model.image 为前缀的顶层属性来配置。

要启用，spring.ai.model.image=google-genai（默认启用）

要禁用，spring.ai.model.image=none（或任何不匹配 google-genai 的值）

做出此变更是为了支持配置多个模型。

图像生成属性

前缀 spring.ai.google.genai.image 是为 Google GenAI 配置图像模型实现的属性前缀。

属性	描述	默认值
spring.ai.model.image	启用 Google GenAI API 模型。	google-genai
spring.ai.google.genai.image.n	要生成的图像数。必须在 1 到 4 之间。	-
spring.ai.google.genai.image.model	要使用的 Google GenAI 模型。受支持的模型包括 gemini-2.5-flash-image、gemini-3-pro-image 和 gemini-3.1-flash-image	-
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	安全过滤的过滤级别。受支持的值为 BLOCKLOWANDABOVE、BLOCKMEDIUMANDABOVE、BLOCKONLYHIGH 和 BLOCK_NONE。	-
spring.ai.google.genai.image.person-generation	允许模型生成人物。受支持的值为 DONTALLOW、ALLOWADULT 和 ALLOW_ALL。	-
spring.ai.google.genai.image.output-mime-type	所生成图像的 MIME 类型。	-
spring.ai.google.genai.image.output-compression-quality	所生成图像的压缩质量（仅对 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	响应中可生成的最大令牌数。	-

示例控制器

创建 一个新的 Spring Boot 项目，并把 spring-ai-starter-model-google-genai-image 添加到你的 pom（或 gradle）依赖。

在 src/main/resources 目录下添加一个 application.properties 文件，以启用并配置 Google GenAI 图像模型：

使用 Gemini Developer API（API 密钥）

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

使用 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

这会创建一个可注入到你类中的 GoogleGenAiImageModel 实现。 下面是一个简单 @Controller 类的示例，它使用图像模型进行图像生成。

@RestController
public class ImageController {

    private final ImageModel imageModel;

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

    @GetMapping("/ai/image")
    public Map 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);
    }
}

手动配置

GoogleGenAiImageModel 实现了 ImageModel。

把 spring-ai-google-genai-image 依赖添加到你的项目的 Maven pom.xml 文件：

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

或添加到你的 Gradle build.gradle 构建文件。

dependencies {
    implementation 'org.springframework.ai:spring-ai-google-genai-image'
}

TIP

参见 依赖管理 一节，把 Spring AI BOM 添加到你的构建文件。

接下来，创建一个 GoogleGenAiImageModel 并将其用于图像生成：

使用 API 密钥

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"));

使用 Vertex AI

GoogleGenAiImageConnectionDetails connectionDetails =
    GoogleGenAiImageConnectionDetails.builder()
        .projectId(System.getenv("GOOGLE_CLOUD_PROJECT"))
        .location(System.getenv("GOOGLE_CLOUD_LOCATION"))
        .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"));

安全过滤级别

Google GenAI 图像 API 支持不同的安全过滤过滤级别：

• BLOCK_LOW_AND_ABOVE：当不安全内容的低、中或高概率时拦截
• BLOCK_MEDIUM_AND_ABOVE：当不安全内容的中或高概率时拦截
• BLOCK_ONLY_HIGH：当不安全内容的高概率时拦截
• BLOCK_NONE：无论不安全内容的概率如何都始终显示
• SAFETY_FILTER_LEVEL_UNSPECIFIED：阈值未指定，用默认阈值拦截

人物生成

Google GenAI 图像 API 允许模型以不同级别生成人物图像：

• DONT_ALLOW：拦截生成人物图像
• ALLOW_ADULT：生成成人图像，但不含儿童
• ALLOW_ALL：生成包含成人与儿童的图像
• PERSON_GENERATION_UNSPECIFIED：阈值未指定，用默认阈值生成人物图像