OpenAI Image Generation

Spring AI 支持 DALL-E，这是 OpenAI 的图像生成模型。

Spring AI supports DALL-E, the Image generation model from OpenAI.

Prerequisites

您需要使用 OpenAI 创建 API 密钥才能访问 ChatGPT 模型。

You will need to create an API key with OpenAI to access ChatGPT models.

在 open.bigmodel.cn 创建账户并在 API密钥 上生成令牌。

Create an account at OpenAI signup page and generate the token on the API Keys page.

Spring AI 项目定义了一个名为 spring.ai.openai.api-key 的配置属性，您应该将其设置为从 openai.com 获取的 API 密钥 的值。

The Spring AI project defines a configuration property named spring.ai.openai.api-key that you should set to the value of the API Key obtained from openai.com.

你可以在` application.properties `文件中设置此配置属性：

You can set this configuration property in your application.properties file:

spring.ai.openai.api-key=<your-openai-api-key>

为了在处理 API 密钥等敏感信息时增强安全性，您可以使用 Spring 表达式语言 (SpEL) 引用自定义环境变量：

For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference a custom environment variable:

# In application.yml
spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}

# In your environment or .env file
export OPENAI_API_KEY=<your-openai-api-key>

你也可以在应用程序代码中以编程方式设置此配置：

You can also set this configuration programmatically in your application code:

// Retrieve API key from a secure source or environment variable
String apiKey = System.getenv("OPENAI_API_KEY");

Auto-configuration

Spring AI 自动配置、启动器模块的工件名称发生了重大变化。请参阅 upgrade notes 以获取更多信息。

There has been a significant change in the Spring AI auto-configuration, starter modules' artifact names. Please refer to the upgrade notes for more information.

Spring AI 提供适用于 OpenAI 图像生成客户端的 Spring Boot 自动配置。要启用它，请将以下依赖项添加到项目的 Maven pom.xml 文件中：

Spring AI provides Spring Boot auto-configuration for the OpenAI Image Generation Client. To enable it add the following dependency to your project’s Maven pom.xml file:

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

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

or to your Gradle build.gradle build file.

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-openai'
}

参见 Dependency Management 部分，将 Spring AI BOM 添加到你的构建文件中。

Refer to the Dependency Management section to add the Spring AI BOM to your build file.

Image Generation Properties

Connection Properties

spring.ai.openai 前缀用作可让你连接到 Open AI 的属性前缀。

The prefix spring.ai.openai is used as the property prefix that lets you connect to OpenAI.

Property

Description

Default

spring.ai.openai.base-url

The URL to connect to

[role="bare"]https://api.openai.com

spring.ai.openai.api-key

The API Key

spring.ai.openai.organization-id

Optionally you can specify which organization used for an API request.

spring.ai.openai.project-id

Optionally, you can specify which project is used for an API request.

对于属于多个组织（或通过其旧版用户 API 密钥访问其项目）的用户，您可以选择指定用于 API 请求的组织和项目。这些 API 请求的使用将计为指定组织和项目的使用。

For users that belong to multiple organizations (or are accessing their projects through their legacy user API key), optionally, you can specify which organization and project is used for an API request. Usage from these API requests will count as usage for the specified organization and project.

Retry Properties

spring.ai.retry 前缀用作可让你配置 OpenAI Image 客户端的重试机制的属性前缀。

The prefix spring.ai.retry is used as the property prefix that lets you configure the retry mechanism for the OpenAI Image client.

Property Description Default

Property	Description	Default
spring.ai.retry.max-attempts	Maximum number of retry attempts.	10
spring.ai.retry.backoff.initial-interval	Initial sleep duration for the exponential backoff policy.	2 sec.
spring.ai.retry.backoff.multiplier	Backoff interval multiplier.	5
spring.ai.retry.backoff.max-interval	Maximum backoff duration.	3 min.
spring.ai.retry.on-client-errors	If false, throw a NonTransientAiException, and do not attempt retry for `4xx` client error codes	false
spring.ai.retry.exclude-on-http-codes	List of HTTP status codes that should not trigger a retry (e.g. to throw NonTransientAiException).	empty
spring.ai.retry.on-http-codes	List of HTTP status codes that should trigger a retry (e.g. to throw TransientAiException).	empty

spring.ai.retry.max-attempts

Maximum number of retry attempts.

spring.ai.retry.backoff.initial-interval

Initial sleep duration for the exponential backoff policy.

2 sec.

spring.ai.retry.backoff.multiplier

Backoff interval multiplier.

spring.ai.retry.backoff.max-interval

Maximum backoff duration.

3 min.

spring.ai.retry.on-client-errors

If false, throw a NonTransientAiException, and do not attempt retry for 4xx client error codes

false

spring.ai.retry.exclude-on-http-codes

List of HTTP status codes that should not trigger a retry (e.g. to throw NonTransientAiException).

empty

spring.ai.retry.on-http-codes

List of HTTP status codes that should trigger a retry (e.g. to throw TransientAiException).

empty

Configuration Properties

图像自动配置的启用和禁用现在通过带有前缀 spring.ai.model.image 的顶级属性进行配置。

Enabling and disabling of the image auto-configurations are now configured via top level properties with the prefix spring.ai.model.image.

要启用，请设置 spring.ai.model.image=openai（默认已启用）

To enable, spring.ai.model.image=openai (It is enabled by default)

要禁用，请设置 spring.ai.model.image=none（或任何不匹配 openai 的值）

To disable, spring.ai.model.image=none (or any value which doesn’t match openai)

此更改旨在允许配置多个模型。

This change is done to allow configuration of multiple models.

前缀 spring.ai.openai.image 是属性前缀，可用于配置 OpenAI 的 ImageModel 实现。

The prefix spring.ai.openai.image is the property prefix that lets you configure the ImageModel implementation for OpenAI.

Property

Description

Default

spring.ai.openai.image.enabled (Removed and no longer valid)

Enable OpenAI image model.

true

spring.ai.model.image

Enable OpenAI image model.

openai

spring.ai.openai.image.base-url

Optional overrides the spring.ai.openai.base-url to provide chat specific url

spring.ai.openai.image.api-key

Optional overrides the spring.ai.openai.api-key to provide chat specific api-key

spring.ai.openai.image.organization-id

Optionally you can specify which organization used for an API request.

spring.ai.openai.image.project-id

Optionally, you can specify which project is used for an API request.

spring.ai.openai.image.options.n

The number of images to generate. Must be between 1 and 10. For dall-e-3, only n=1 is supported.

spring.ai.openai.image.options.model

The model to use for image generation.

OpenAiImageApi.DEFAULT_IMAGE_MODEL

spring.ai.openai.image.options.quality

The quality of the image that will be generated. HD creates images with finer details and greater consistency across the image. This parameter is only supported for dall-e-3.

spring.ai.openai.image.options.response_format

The format in which the generated images are returned. Must be one of URL or b64_json.

spring.ai.openai.image.options.size

The size of the generated images. Must be one of 256x256, 512x512, or 1024x1024 for dall-e-2. Must be one of 1024x1024, 1792x1024, or 1024x1792 for dall-e-3 models.

spring.ai.openai.image.options.size_width

The width of the generated images. Must be one of 256, 512, or 1024 for dall-e-2.

spring.ai.openai.image.options.size_height

The height of the generated images. Must be one of 256, 512, or 1024 for dall-e-2.

spring.ai.openai.image.options.style

The style of the generated images. Must be one of vivid or natural. Vivid causes the model to lean towards generating hyper-real and dramatic images. Natural causes the model to produce more natural, less hyper-real looking images. This parameter is only supported for dall-e-3.

spring.ai.openai.image.options.user

A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse.

您可以覆盖通用的 spring.ai.openai.base-url 、 spring.ai.openai.api-key 、 spring.ai.openai.organization-id 和 spring.ai.openai.project-id 属性。如果设置了 spring.ai.openai.image.base-url 、 spring.ai.openai.image.api-key 、 spring.ai.openai.image.organization-id 和 spring.ai.openai.image.project-id 属性，它们将优先于通用属性。如果您希望为不同的模型和不同的模型端点使用不同的 OpenAI 帐户，这将非常有用。

You can override the common spring.ai.openai.base-url, spring.ai.openai.api-key, spring.ai.openai.organization-id and spring.ai.openai.project-id properties. The spring.ai.openai.image.base-url, spring.ai.openai.image.api-key, spring.ai.openai.image.organization-id and spring.ai.openai.image.project-id properties if set take precedence over the common properties. This is useful if you want to use different OpenAI accounts for different models and different model endpoints.

所有以 spring.ai.openai.image.options 为前缀的属性都可以在运行时被覆盖。

All properties prefixed with spring.ai.openai.image.options can be overridden at runtime.

Runtime Options

OpenAiImageOptions.java提供模型配置，例如使用的模型、质量、大小等。

The OpenAiImageOptions.java provides model configurations, such as the model to use, the quality, the size, etc.

在启动时，可以使用 OpenAiImageModel(OpenAiImageApi openAiImageApi) 构造函数和 withDefaultOptions(OpenAiImageOptions defaultOptions) 方法配置默认选项。或者，使用前面描述的 spring.ai.openai.image.options.* 属性。

On start-up, the default options can be configured with the OpenAiImageModel(OpenAiImageApi openAiImageApi) constructor and the withDefaultOptions(OpenAiImageOptions defaultOptions) method. Alternatively, use the spring.ai.openai.image.options.* properties described previously.

在运行时，你可以通过将新的请求特定选项添加到 ImagePrompt 调用来覆盖默认选项。例如，要覆盖 OpenAI 特定的选项（例如质量和创建的图像数量），请使用以下代码示例：

At runtime you can override the default options by adding new, request specific, options to the ImagePrompt call. For example to override the OpenAI specific options such as quality and the number of images to create, use the following code example:

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

);

除了模型特定的 OpenAiImageOptions ，您还可以使用通过 ImageOptionsBuilder#builder() 创建的可移植 ImageOptions 实例。

In addition to the model specific OpenAiImageOptions you can use a portable ImageOptions instance, created with the ImageOptionsBuilder#builder().