OpenAI SDK Image Generation (正式)

Spring AI supports OpenAI’s DALL-E image generation models through the OpenAI Java SDK, providing a robust and officially-maintained integration with OpenAI’s services including Microsoft Foundry and GitHub Models.

この実装は OpenAI の公式 OpenAI Java SDK [GitHub] (英語) を使用しています。Spring の代替 AI 実装については、OpenAI イメージの生成を参照してください。

DALL-E is a state-of-the-art image generation model from OpenAI that can create realistic images and art from natural language descriptions.

The OpenAI SDK module automatically detects the service provider (OpenAI, Microsoft Foundry, or GitHub Models) based on the base URL you provide.

認証

Authentication is done using a base URL and an API Key. The implementation provides flexible configuration options through Spring Boot properties or environment variables.

OpenAI の使用

If you are using OpenAI directly, create an account at OpenAI サインアップページ (英語) and generate an API key on the API キーページ (英語) 。

The base URL doesn’t need to be set as it defaults to api.openai.com/v1 (英語) :

spring.ai.openai-sdk.api-key=<your-openai-api-key>
# base-url is optional, defaults to https://api.openai.com/v1

Or using environment variables:

export OPENAI_API_KEY=<your-openai-api-key>
# OPENAI_BASE_URL is optional, defaults to https://api.openai.com/v1

Using Microsoft Foundry

Microsoft Foundry is automatically detected when using a Microsoft Foundry URL. You can configure it using properties:

spring.ai.openai-sdk.base-url=https://<your-deployment-url>.openai.azure.com
spring.ai.openai-sdk.api-key=<your-api-key>
spring.ai.openai-sdk.microsoft-deployment-name=<your-deployment-name>

Or using environment variables:

export OPENAI_BASE_URL=https://<your-deployment-url>.openai.azure.com
export OPENAI_API_KEY=<your-api-key>

Passwordless Authentication (Recommended for Azure):

Microsoft Foundry supports passwordless authentication without providing an API key, which is more secure when running on Azure.

To enable passwordless authentication, add the com.azure:azure-identity dependency:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

Then configure without an API key:

spring.ai.openai-sdk.base-url=https://<your-deployment-url>.openai.azure.com
spring.ai.openai-sdk.microsoft-deployment-name=<your-deployment-name>
# No api-key needed - will use Azure credentials from environment

Using GitHub Models

GitHub Models is automatically detected when using the GitHub Models base URL. You’ll need to create a GitHub Personal Access Token (PAT) with the models:read scope.

spring.ai.openai-sdk.base-url=https://models.inference.ai.azure.com
spring.ai.openai-sdk.api-key=github_pat_XXXXXXXXXXX

Or using environment variables:

export OPENAI_BASE_URL=https://models.inference.ai.azure.com
export OPENAI_API_KEY=github_pat_XXXXXXXXXXX
For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) in your properties:
spring.ai.openai-sdk.api-key=${OPENAI_API_KEY}

リポジトリと BOM の追加

Spring AI アーティファクトは、Maven Central リポジトリと Spring スナップショットリポジトリに公開されています。これらのリポジトリをビルドシステムに追加するには、アーティファクトリポジトリセクションを参照してください。

依存関係の管理を支援するために、Spring AI は BOM (部品表) を提供し、一貫したバージョンの Spring AI がプロジェクト全体で使用されるようにします。Spring AI BOM をビルドシステムに追加するには、"依存関係管理" セクションを参照してください。

自動構成

Spring AI provides Spring Boot auto-configuration for the OpenAI SDK Image Model. To enable it add the following dependency to your project’s Maven pom.xml or Gradle build.gradle build files:

  • Maven

  • Gradle

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai-sdk</artifactId>
</dependency>
dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-openai-sdk'
}
Spring AI BOM をビルドファイルに追加するには、"依存関係管理" セクションを参照してください。

プロパティの構成

接続プロパティ

The prefix spring.ai.openai-sdk is used as the property prefix that lets you configure the OpenAI SDK client.

プロパティ 説明 デフォルト

spring.ai.openai-sdk.base-url

The URL to connect to. Auto-detects from OPENAI_BASE_URL environment variable if not set.

api.openai.com/v1 (英語)

spring.ai.openai-sdk.api-key

The API Key. Auto-detects from OPENAI_API_KEY environment variable if not set.

-

spring.ai.openai-sdk.organization-id

Optionally specify which organization to use for API requests.

-

spring.ai.openai-sdk.timeout

Request timeout duration.

-

spring.ai.openai-sdk.max-retries

Maximum number of retry attempts for failed requests.

-

spring.ai.openai-sdk.proxy

Proxy settings for OpenAI client (Java Proxy object).

-

spring.ai.openai-sdk.custom-headers

Custom HTTP headers to include in requests. Map of header name to header value.

-

Microsoft Foundry Properties

The OpenAI SDK implementation provides native support for Microsoft Foundry with automatic configuration:

プロパティ 説明 デフォルト

spring.ai.openai-sdk.microsoft-foundry

Enable Microsoft Foundry mode. Auto-detected if base URL contains openai.azure.com, cognitiveservices.azure.com, or .openai.microsoftFoundry.com.

false

spring.ai.openai-sdk.microsoft-deployment-name

Microsoft Foundry deployment name. If not specified, the model name will be used. Also accessible via alias deployment-name.

-

spring.ai.openai-sdk.microsoft-foundry-service-version

Microsoft Foundry API service version.

-

spring.ai.openai-sdk.credential

Credential object for passwordless authentication (requires com.azure:azure-identity dependency).

-

Microsoft Foundry supports passwordless authentication. Add the com.azure:azure-identity dependency and the implementation will automatically attempt to use Azure credentials from the environment when no API key is provided.

GitHub Models Properties

Native support for GitHub Models is available:

プロパティ 説明 デフォルト

spring.ai.openai-sdk.github-models

Enable GitHub Models mode. Auto-detected if base URL contains models.github.ai or models.inference.ai.azure.com.

false

GitHub Models requires a Personal Access Token with the models:read scope. Set it via the OPENAI_API_KEY environment variable or the spring.ai.openai-sdk.api-key property.

Image Model Properties

The prefix spring.ai.openai-sdk.image is the property prefix for configuring the image model implementation:

プロパティ 説明 デフォルト

spring.ai.openai-sdk.image.options.model

The model to use for image generation. Available models: dall-e-2, dall-e-3. See the models (英語) page for more information.

dall-e-3

spring.ai.openai-sdk.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-sdk.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. Available values: standard, hd.

-

spring.ai.openai-sdk.image.options.response-format

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

-

spring.ai.openai-sdk.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-sdk.image.options.width

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

-

spring.ai.openai-sdk.image.options.height

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

-

spring.ai.openai-sdk.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-sdk.image.options.user

エンドユーザーを表す一意の識別子。OpenAI が不正使用を監視および検出できます。

-

spring.ai.openai-sdk.image.options で始まるすべてのプロパティは、リクエスト固有のランタイムオプションを ImagePrompt 呼び出しに追加することによって実行時にオーバーライドできます。

ランタイムオプション

The OpenAiSdkImageOptions.java [GitHub] (英語) provides the OpenAI configurations, such as the model to use, quality, size, style, and number of images to generate.

デフォルトのオプションは、spring.ai.openai-sdk.image.options プロパティを使用して構成することもできます。

At start-time use the OpenAiSdkImageModel constructor to set the default options used for all image generation requests. At run-time you can override the default options, using a OpenAiSdkImageOptions instance as part of your ImagePrompt.

For example to override the default model and quality for a specific request:

ImageResponse response = imageModel.call(
    new ImagePrompt("A light cream colored mini golden doodle",
        OpenAiSdkImageOptions.builder()
            .model("dall-e-3")
            .quality("hd")
            .N(1)
            .width(1024)
            .height(1024)
            .style("vivid")
        .build()));
モデル固有の OpenAiSdkImageOptions [GitHub] (英語) に加えて、ImageOptionsBuilder#builder() [GitHub] (英語) で作成されたポータブル ImageOptions [GitHub] (英語) インスタンスを使用できます。

サンプルコントローラー

新しい Spring Boot プロジェクトを作成し、spring-ai-openai-sdk を pom (または gradle) の依存関係に追加します。

Add an application.properties file under the src/main/resources directory to configure the OpenAI SDK image model:

spring.ai.openai-sdk.api-key=YOUR_API_KEY
spring.ai.openai-sdk.image.options.model=dall-e-3
api-key を OpenAI の資格情報に置き換えます。

This will create an OpenAiSdkImageModel implementation that you can inject into your classes. Here is an example of a simple @RestController class that uses the image model.

@RestController
public class ImageController {

    private final ImageModel imageModel;

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

    @GetMapping("/ai/image")
    public Map<String, Object> generateImage(
            @RequestParam(value = "prompt", defaultValue = "A light cream colored mini golden doodle") String prompt) {
        ImageResponse response = this.imageModel.call(
            new ImagePrompt(prompt,
                OpenAiSdkImageOptions.builder()
                    .quality("hd")
                    .N(1)
                    .width(1024)
                    .height(1024)
                .build()));

        String imageUrl = response.getResult().getOutput().getUrl();
        return Map.of("url", imageUrl);
    }
}

手動構成

The OpenAiSdkImageModel [GitHub] (英語) implements the ImageModel and uses the official OpenAI Java SDK to connect to the OpenAI service.

If you are not using Spring Boot auto-configuration, you can manually configure the OpenAI SDK Image Model. For this add the spring-ai-openai-sdk dependency to your project’s Maven pom.xml file:

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

または、Gradle build.gradle ビルドファイルに次の内容を追加します。

dependencies {
    implementation 'org.springframework.ai:spring-ai-openai-sdk'
}
Spring AI BOM をビルドファイルに追加するには、"依存関係管理" セクションを参照してください。
The spring-ai-openai-sdk dependency provides access also to the OpenAiSdkChatModel and OpenAiSdkEmbeddingModel. For more information about the OpenAiSdkChatModel refer to the OpenAI SDK チャット section.

Next, create an OpenAiSdkImageModel instance and use it to generate images:

var imageOptions = OpenAiSdkImageOptions.builder()
    .model("dall-e-3")
    .quality("hd")
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .build();

var imageModel = new OpenAiSdkImageModel(imageOptions);

ImageResponse response = imageModel.call(
    new ImagePrompt("A light cream colored mini golden doodle",
        OpenAiSdkImageOptions.builder()
            .N(1)
            .width(1024)
            .height(1024)
        .build()));

The OpenAiSdkImageOptions provides the configuration information for the image generation requests. The options class offers a builder() for easy options creation.

Microsoft Foundry Configuration

For Microsoft Foundry:

var imageOptions = OpenAiSdkImageOptions.builder()
    .baseUrl("https://your-resource.openai.azure.com")
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .deploymentName("dall-e-3")
    .azureOpenAIServiceVersion(AzureOpenAIServiceVersion.V2024_10_01_PREVIEW)
    .azure(true)  // Enables Microsoft Foundry mode
    .build();

var imageModel = new OpenAiSdkImageModel(imageOptions);
Microsoft Foundry supports passwordless authentication. Add the com.azure:azure-identity dependency to your project. If you don’t provide an API key, the implementation will automatically attempt to use Azure credentials from your environment.

GitHub Models Configuration

For GitHub Models:

var imageOptions = OpenAiSdkImageOptions.builder()
    .baseUrl("https://models.inference.ai.azure.com")
    .apiKey(System.getenv("GITHUB_TOKEN"))
    .model("dall-e-3")
    .githubModels(true)
    .build();

var imageModel = new OpenAiSdkImageModel(imageOptions);

可観測性

The OpenAI SDK implementation supports Spring AI’s observability features through Micrometer. All image model operations are instrumented for monitoring and tracing.

追加リソース