This version is still in development and is not considered stable yet. For the latest stable version, please use Spring AI 2.1.0!

OpenAI Text-to-Speech (TTS)

Introduction

The Audio API provides a speech endpoint based on OpenAI’s TTS (text-to-speech) model, enabling users to:

  • Narrate a written blog post.

  • Produce spoken audio in multiple languages.

  • Give real-time audio output using streaming.

Spring AI uses the official openai-java SDK for all OpenAI models. If you are upgrading from a version that used the Spring AI OpenAI client, see OpenAI Java SDK Transition. Report any issues at Spring AI GitHub Issues.

Prerequisites

  1. Create an OpenAI account and obtain an API key. You can sign up at the OpenAI signup page and generate an API key on the API Keys page.

  2. Add the spring-ai-openai dependency to your project’s build file. For more information, refer to the Dependency Management section.

Auto-configuration

Spring AI provides Spring Boot auto-configuration for the OpenAI Text-to-Speech 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>

or to your Gradle build.gradle build file:

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-openai'
}
Refer to the Dependency Management section to add the Spring AI BOM to your build file.

Speech Properties

Connection Properties

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

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.timeout

Request timeout for the OpenAI client.

60 sec.

spring.ai.openai.max-retries

Maximum number of retries for the OpenAI client.

3

spring.ai.openai.proxy

Proxy settings for the OpenAI client.

-

spring.ai.openai.custom-headers

Custom HTTP headers to add to OpenAI client requests.

empty

spring.ai.openai.connection-pool-metrics-enabled

Whether to enable connection pool metrics for the underlying OkHttp client.

false

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.

Configuration Properties

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

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

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

This change is done to allow configuration of multiple models.

The prefix spring.ai.openai.audio.speech is used as the property prefix that lets you configure the OpenAI Text-to-Speech client.

Property Description Default

spring.ai.model.audio.speech

Enable Audio Speech Model

openai

spring.ai.openai.audio.speech.base-url

The URL to connect to

api.openai.com

spring.ai.openai.audio.speech.api-key

The API Key

-

spring.ai.openai.audio.speech.organization-id

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

-

spring.ai.openai.audio.speech.model

ID of the model to use for generating the audio. Available models: gpt-4o-mini-tts (default, optimized for speed and cost), gpt-4o-tts (higher quality), tts-1 (legacy, optimized for speed), or tts-1-hd (legacy, optimized for quality).

gpt-4o-mini-tts

spring.ai.openai.audio.speech.voice

The voice to use for synthesis. For OpenAI’s TTS API, One of the available voices for the chosen model: alloy, echo, fable, onyx, nova, and shimmer.

alloy

spring.ai.openai.audio.speech.response-format

The format of the audio output. Supported formats are mp3, opus, aac, flac, wav, and pcm.

mp3

spring.ai.openai.audio.speech.speed

The speed of the voice synthesis. The acceptable range is from 0.25 (slowest) to 4.0 (fastest).

1.0

spring.ai.openai.audio.speech.instructions

Control instructions for the voice delivery (e.g. tone, pace). Only supported by models such as gpt-4o-mini-tts; ignored by tts-1 and tts-1-hd.

-

You can override the common spring.ai.openai.base-url, spring.ai.openai.api-key, spring.ai.openai.organization-id properties. The spring.ai.openai.audio.speech.base-url, spring.ai.openai.audio.speech.api-key and spring.ai.openai.audio.speech.organization-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.
All properties prefixed with spring.ai.openai.audio.speech can be overridden at runtime.

Runtime Options

The OpenAiAudioSpeechOptions class provides the options to use when making a text-to-speech request. On start-up, the options specified by spring.ai.openai.audio.speech are used but you can override these at runtime.

The OpenAiAudioSpeechOptions class implements the TextToSpeechOptions interface, providing both portable and OpenAI-specific configuration options.

For example:

OpenAiAudioSpeechOptions speechOptions = OpenAiAudioSpeechOptions.builder()
    .model("gpt-4o-mini-tts")
    .voice(OpenAiAudioSpeechOptions.Voice.ALLOY)
    .responseFormat(OpenAiAudioSpeechOptions.AudioResponseFormat.MP3)
    .speed(1.0)
    .instructions("Friendly; warm tone; natural pauses")
    .build();

TextToSpeechPrompt speechPrompt = new TextToSpeechPrompt("Hello, this is a text-to-speech example.", speechOptions);
TextToSpeechResponse response = openAiAudioSpeechModel.call(speechPrompt);

Manual Configuration

Add the spring-ai-openai dependency to your project’s Maven pom.xml file:

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

or to your Gradle build.gradle build file:

dependencies {
    implementation 'org.springframework.ai:spring-ai-openai'
}
Refer to the Dependency Management section to add the Spring AI BOM to your build file.

Next, create an OpenAiAudioSpeechModel:

var openAiAudioSpeechModel = OpenAiAudioSpeechModel.builder()
    .options(OpenAiAudioSpeechOptions.builder()
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .build())
    .build();

var speechOptions = OpenAiAudioSpeechOptions.builder()
    .responseFormat(OpenAiAudioSpeechOptions.AudioResponseFormat.MP3)
    .speed(1.0)
    .model("gpt-4o-mini-tts")
    .build();

var speechPrompt = new TextToSpeechPrompt("Hello, this is a text-to-speech example.", speechOptions);
TextToSpeechResponse response = openAiAudioSpeechModel.call(speechPrompt);

// Accessing metadata (rate limit info)
OpenAiAudioSpeechResponseMetadata metadata = (OpenAiAudioSpeechResponseMetadata) response.getMetadata();

byte[] responseAsBytes = response.getResult().getOutput();

Streaming Real-time Audio

The Speech API provides support for real-time audio streaming using chunk transfer encoding. This means that the audio is able to be played before the full file has been generated and made accessible.

The OpenAiAudioSpeechModel implements the StreamingTextToSpeechModel interface, providing both standard and streaming capabilities.

var openAiAudioSpeechModel = OpenAiAudioSpeechModel.builder()
    .options(OpenAiAudioSpeechOptions.builder()
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .build())
    .build();

OpenAiAudioSpeechOptions speechOptions = OpenAiAudioSpeechOptions.builder()
    .voice(OpenAiAudioSpeechOptions.Voice.ALLOY)
    .speed(1.0)
    .responseFormat(OpenAiAudioSpeechOptions.AudioResponseFormat.MP3)
    .model("gpt-4o-mini-tts")
    .build();

TextToSpeechPrompt speechPrompt = new TextToSpeechPrompt("Today is a wonderful day to build something people love!", speechOptions);

Flux<TextToSpeechResponse> responseStream = openAiAudioSpeechModel.stream(speechPrompt);

// You can also stream raw audio bytes directly
Flux<byte[]> audioByteStream = openAiAudioSpeechModel.stream("Hello, world!");

Each element of the stream carries at most 8 KB of audio, the internal read-buffer size OpenAiAudioSpeechModel uses when pulling bytes from the underlying HTTP response; chunks can be smaller than that, depending on how much data has arrived from OpenAI at the time of each read.

If you need to hand this stream to an API that only accepts a blocking java.io.InputStream, see Consuming the Stream as a Blocking InputStream for the practices that matter and a tested reference implementation.

Each open stream pins a thread for its whole response duration, so OpenAiAudioSpeechModel runs streaming on a dedicated bounded-elastic scheduler rather than Reactor’s shared Schedulers.boundedElastic(), keeping heavy speech-streaming load from starving unrelated blocking work elsewhere in the application. Override it with OpenAiAudioSpeechModel.builder().streamScheduler(customScheduler) to share a scheduler across components or to size the pool differently for expected concurrent-stream load.

Customizing the HTTP Client

Spring AI uses the official openai-java SDK under the hood and configures its HTTP transport with a custom OkHttp client built by SpringAiOpenAiHttpClient.Builder. You can intercept that builder before the underlying OkHttpClient is created by exposing one or more OpenAiHttpClientBuilderCustomizer beans. Each customizer receives the same builder used by every OpenAI model (chat, embedding, image, audio, moderation), so the customization applies uniformly.

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

Typical use cases include:

  • registering OkHttp Interceptor instances (authentication, propagation headers, custom logging);

  • swapping the dispatcher ExecutorService (for example, to route async I/O through virtual threads);

  • configuring proxy, SSL, hostname verification, or the connection-pool sizing exposed by the builder.

When several customizers are present, they are applied in @Order / Ordered order, after Spring AI’s own defaults, so user code wins.

The same hook is available when wiring a model manually via the OpenAi*Model.Builder:

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

Example Code