tessl/maven-org-springframework-ai--spring-ai-openai

OpenAI models support for Spring AI, providing comprehensive integration for chat completion, embeddings, image generation, audio transcription, text-to-speech, and content moderation capabilities within Spring Boot applications.

Overview

Eval results

Files

Spring AI OpenAI

Name: tessl/maven-org-springframework-ai--spring-ai-openai
Author: tessl

OpenAI integration for Spring AI, providing Java APIs for chat completion, embeddings, image generation, audio transcription/synthesis, and content moderation within Spring Boot applications.

Package Information

Group ID: org.springframework.ai
Artifact ID: spring-ai-openai
Version: 1.1.2

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

Quick Start

import org.springframework.ai.openai.OpenAiChatModel;
import org.springframework.ai.openai.api.OpenAiApi;
import org.springframework.ai.chat.prompt.Prompt;

// Create API client
var openAiApi = OpenAiApi.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .build();

// Create chat model
var chatModel = OpenAiChatModel.builder()
    .openAiApi(openAiApi)
    .build();

// Generate response
var response = chatModel.call(new Prompt("Explain quantum computing"));
System.out.println(response.getResult().getOutput().getContent());

→ Complete Quick Start Guide

Core Components

Model Layer

High-level implementations of Spring AI interfaces:

Model	Purpose	Reference
`OpenAiChatModel`	Chat completions (GPT-4, GPT-3.5, O-series)	Chat Models
`OpenAiEmbeddingModel`	Vector embeddings for semantic search	Embeddings
`OpenAiImageModel`	Image generation (DALL-E 2/3)	Images
`OpenAiAudioSpeechModel`	Text-to-speech synthesis	Audio
`OpenAiAudioTranscriptionModel`	Audio transcription (Whisper)	Audio
`OpenAiModerationModel`	Content moderation	Moderation

API Client Layer

Low-level REST clients for direct API access:

Client	Purpose	Reference
`OpenAiApi`	Chat & embeddings	API Clients
`OpenAiImageApi`	Image generation	API Clients
`OpenAiAudioApi`	Audio operations	API Clients
`OpenAiModerationApi`	Content moderation	API Clients
`OpenAiFileApi`	File management	API Clients

Key Features

Chat Completion

Multiple models: GPT-4, GPT-3.5, O-series reasoning models
Tool/function calling support
Structured outputs with JSON schema
Multimodal inputs (text, images, audio)
Streaming responses

Embeddings

Models: text-embedding-ada-002, text-embedding-3-small/large
Adjustable dimensions (v3 models)
Batch processing support

Image Generation

DALL-E 2: Multiple images, lower cost
DALL-E 3: Higher quality, single image
Size, quality, and style controls

Audio

TTS: Multiple voices, formats (mp3, opus, aac, flac, wav, pcm)
Transcription: Whisper model, multiple languages, subtitle formats

Content Moderation

Categories: sexual, hate, harassment, self-harm, violence
Confidence scores for each category
Batch moderation support

Architecture

┌─────────────────────────────────────────┐
│         Spring Boot Application         │
├─────────────────────────────────────────┤
│  Model Layer (OpenAiChatModel, etc.)    │
│  ↓ Spring AI Interfaces                 │
├─────────────────────────────────────────┤
│  Options Layer (OpenAiChatOptions, etc.)│
│  ↓ Builder Pattern                      │
├─────────────────────────────────────────┤
│  API Client Layer (OpenAiApi, etc.)     │
│  ↓ REST Communication                   │
├─────────────────────────────────────────┤
│         OpenAI REST API                  │
└─────────────────────────────────────────┘

Features:

Observability: Micrometer integration for metrics and tracing
Retry Support: Spring Retry for transient failures
Reactive Streams: Project Reactor for streaming responses
Auto-Configuration: Spring Boot starter available

Common Patterns

Builder Pattern

var chatModel = OpenAiChatModel.builder()
    .openAiApi(openAiApi)
    .defaultOptions(OpenAiChatOptions.builder()
        .model(OpenAiApi.ChatModel.GPT_4_O.getValue())
        .temperature(0.7)
        .build())
    .build();

Streaming

chatModel.stream(new Prompt("Write a story"))
    .subscribe(response -> {
        System.out.print(response.getResult().getOutput().getContent());
    });

Tool Calling

var options = OpenAiChatOptions.builder()
    .tools(List.of(weatherTool))
    .toolCallbacks(Map.of("get_weather", weatherCallback))
    .build();

Observability

var chatModel = OpenAiChatModel.builder()
    .openAiApi(openAiApi)
    .observationRegistry(observationRegistry)
    .build();

Spring Boot Integration

Auto-Configuration

spring.ai.openai.api-key=${OPENAI_API_KEY}
spring.ai.openai.chat.options.model=gpt-4o
spring.ai.openai.chat.options.temperature=0.7

Dependency Injection

@RestController
public class ChatController {
    private final OpenAiChatModel chatModel;

    public ChatController(OpenAiChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @PostMapping("/chat")
    public String chat(@RequestBody String message) {
        return chatModel.call(new Prompt(message))
            .getResult().getOutput().getContent();
    }
}

Model Reference

Chat Models

public enum OpenAiApi.ChatModel {
    // Reasoning: O4_MINI, O3, O3_MINI, O1, O1_MINI, O1_PRO
    // GPT-5: GPT_5, GPT_5_MINI, GPT_5_NANO
    // GPT-4o: GPT_4_O, GPT_4_O_MINI, GPT_4_O_AUDIO_PREVIEW
    // GPT-4.1: GPT_4_1, GPT_4_1_MINI, GPT_4_1_NANO
    // Legacy: GPT_4_TURBO, GPT_4, GPT_3_5_TURBO
}

Embedding Models

public enum OpenAiApi.EmbeddingModel {
    TEXT_EMBEDDING_ADA_002,      // 1536 dimensions (fixed)
    TEXT_EMBEDDING_3_SMALL,      // Up to 1536 dimensions
    TEXT_EMBEDDING_3_LARGE       // Up to 3072 dimensions
}

Image Models

public enum OpenAiImageApi.ImageModel {
    DALL_E_2,    // Multiple images, lower cost
    DALL_E_3     // Higher quality, single image
}

Error Handling

import org.springframework.ai.openai.api.common.OpenAiApiClientErrorException;

try {
    var response = chatModel.call(new Prompt("Hello"));
} catch (OpenAiApiClientErrorException e) {
    switch (e.getStatusCode()) {
        case 401 -> System.err.println("Invalid API key");
        case 429 -> System.err.println("Rate limit exceeded");
        case 400 -> System.err.println("Invalid request");
        default -> System.err.println("API error: " + e.getMessage());
    }
}

→ Complete Error Handling Guide

Production Best Practices

Security

Store API keys in environment variables or secrets manager
Never hardcode credentials
Use organization/project IDs for multi-tenant scenarios

Performance

Configure connection pooling for high throughput
Set appropriate timeouts (connect: 10s, read: 60s)
Use streaming for long responses

Reliability

Implement retry with exponential backoff
Handle rate limits gracefully
Monitor token usage and costs

Observability

Enable Micrometer metrics
Track request latency and error rates
Monitor token consumption

→ Complete Production Guide

Resources

Guides

Quick Start Guide - Get started in 5 minutes
Spring Boot Integration - Auto-configuration setup

Examples

Real-World Scenarios - Production patterns and use cases
Edge Cases - Advanced scenarios and troubleshooting

Reference

Chat Models - Complete chat API documentation
Embedding Models - Vector embeddings API
Image Models - DALL-E image generation
Audio Models - TTS and transcription
Moderation Models - Content moderation
API Clients - Low-level REST clients

Quick Reference

Core Imports

// Models
import org.springframework.ai.openai.OpenAiChatModel;
import org.springframework.ai.openai.OpenAiEmbeddingModel;
import org.springframework.ai.openai.OpenAiImageModel;

// Options
import org.springframework.ai.openai.OpenAiChatOptions;
import org.springframework.ai.openai.OpenAiEmbeddingOptions;

// API Clients
import org.springframework.ai.openai.api.OpenAiApi;

Common Configuration

// Temperature: 0.0 (deterministic) to 2.0 (creative)
// Max Tokens: Limit response length
// Top P: Alternative to temperature (0.0-1.0)
// Stop: Sequences to stop generation

Rate Limits

Monitor via response headers:

x-ratelimit-limit-requests
x-ratelimit-remaining-requests
x-ratelimit-limit-tokens
x-ratelimit-remaining-tokens

Token Usage

var usage = response.getMetadata().getUsage();
System.out.println("Total tokens: " + usage.getTotalTokens());

Support

Documentation: Spring AI Reference
GitHub: spring-projects/spring-ai
OpenAI API: platform.openai.com/docs

Install with Tessl CLI

npx tessl i tessl/maven-org-springframework-ai--spring-ai-openai@1.1.0

Workspace: tessl
Visibility: Public
Created: 26 days ago
Last updated: 26 days ago
Describes: pkg:maven/org.springframework.ai/spring-ai-openai@1.1.x