OpenAI 文本转语音（TTS）

引言

Audio API 基于 OpenAI 的 TTS（文本转语音）模型提供一个语音端点，使用户能够：

朗读一篇书面的博客文章。
用多种语言生成语音音频。
使用流式给出实时音频输出。

NOTE

从 2.0.0-M5 版本起，Spring AI 在所有 OpenAI 模型底层使用官方的 openai-java SDK。此次迁移预期是无缝的，OpenAI API 属性与构建器的现有用户不会遇到破坏性变更。如发现任何问题，请在 Spring AI GitHub Issues 向我们报告。

前置条件

创建一个 OpenAI 账户并获取 API 密钥。你可以在 OpenAI 注册页注册，并在 API Keys 页生成一个 API 密钥。
把 spring-ai-openai 依赖添加到你项目的构建文件。更多信息参见依赖管理一节。

自动配置

NOTE

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

Spring AI 为 OpenAI 文本转语音客户端提供 Spring Boot 自动配置。要启用它，请将以下依赖添加到你的项目的 Maven pom.xml 文件：

xml

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

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

groovy

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

TIP

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

语音属性

连接属性

前缀 spring.ai.openai 用作连接 OpenAI 的属性前缀。

属性	描述	默认值
spring.ai.openai.base-url	要连接到的 URL	https://api.openai.com
spring.ai.openai.api-key	API 密钥	-
spring.ai.openai.organization-id	可选地，你可以指定某组织用于 API 请求。	-
spring.ai.openai.project-id	可选地，你可以指定某项目用于 API 请求。	-
spring.ai.openai.timeout	OpenAI 客户端的请求超时。	60 sec.
spring.ai.openai.max-retries	OpenAI 客户端的最大重试次数。	3
spring.ai.openai.proxy	OpenAI 客户端的代理设置。	-
spring.ai.openai.custom-headers	要添加到 OpenAI 客户端请求的自定义 HTTP 头。	empty
spring.ai.openai.connection-pool-metrics-enabled	是否为底层 OkHttp 客户端启用连接池指标。	false

TIP

对于属于多个组织（或通过旧版用户 API 密钥访问其项目）的用户，可选地，你可以指定哪个组织和项目用于 API 请求。

这些 API 请求的用量将计入所指定组织和项目的用量。

配置属性

NOTE

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

要启用，spring.ai.model.audio.speech=openai（默认启用）

要禁用，spring.ai.model.audio.speech=none（或任何不匹配 openai 的值）

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

前缀 spring.ai.openai.audio.speech 用作配置 OpenAI 文本转语音客户端的属性前缀。

属性	描述	默认值
spring.ai.model.audio.speech	启用音频语音模型	openai
spring.ai.openai.audio.speech.base-url	要连接到的 URL	https://api.openai.com
spring.ai.openai.audio.speech.api-key	API 密钥	-
spring.ai.openai.audio.speech.organization-id	可选，你可以指定某个 API 请求使用哪个组织。	-
spring.ai.openai.audio.speech.project-id	可选，你可以指定某个 API 请求使用哪个项目。	-
spring.ai.openai.audio.speech.model	生成音频要使用的模型 ID。可用模型：`gpt-4o-mini-tts`（默认，为速度和成本优化）、`gpt-4o-tts`（更高质量）、`tts-1`（旧式，为速度优化）、或 `tts-1-hd`（旧式，为质量优化）。	gpt-4o-mini-tts
spring.ai.openai.audio.speech.voice	用于合成的声音。对 OpenAI 的 TTS API，是所选模型可用声音之一：alloy、echo、fable、onyx、nova 和 shimmer。	alloy
spring.ai.openai.audio.speech.response-format	音频输出的格式。受支持的格式有 mp3、opus、aac、flac、wav 和 pcm。	mp3
spring.ai.openai.audio.speech.speed	语音合成的速度。可接受范围从 0.25（最慢）到 4.0（最快）。	1.0
spring.ai.openai.audio.speech.instructions	对声音演绎的控制指令（例如语气、节奏）。仅受 `gpt-4o-mini-tts` 这类模型支持；`tts-1` 和 `tts-1-hd` 会忽略。	-

NOTE

你可以覆盖通用的 spring.ai.openai.base-url、spring.ai.openai.api-key、spring.ai.openai.organization-id 和 spring.ai.openai.project-id 属性。

若设置了 spring.ai.openai.audio.speech.base-url、spring.ai.openai.audio.speech.api-key、spring.ai.openai.audio.speech.organization-id 和 spring.ai.openai.audio.speech.project-id 属性，它们优先于通用属性。当你想为不同模型、不同模型端点使用不同的 OpenAI 账户时，这很有用。

TIP

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

运行时选项

OpenAiAudioSpeechOptions 类提供进行文本转语音请求时使用的选项。在启动时，使用由 spring.ai.openai.audio.speech 指定的选项，但你可以在运行时覆盖它们。

OpenAiAudioSpeechOptions 类实现了 TextToSpeechOptions 接口，同时提供可移植和 OpenAI 特定的配置选项。

例如：

java

OpenAiAudioSpeechOptions speechOptions = OpenAiAudioSpeechOptions.builder()
    .model("gpt-4o-mini-tts")
    .voice(OpenAiAudioApi.SpeechRequest.Voice.ALLOY)
    .responseFormat(OpenAiAudioApi.SpeechRequest.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);

手动配置

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

xml

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

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

groovy

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

TIP

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

接下来，创建一个 OpenAiAudioSpeechModel：

java

var openAiAudioApi = new OpenAiAudioApi()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .build();

var openAiAudioSpeechModel = new OpenAiAudioSpeechModel(openAiAudioApi);

var speechOptions = OpenAiAudioSpeechOptions.builder()
    .responseFormat(OpenAiAudioApi.SpeechRequest.AudioResponseFormat.MP3)
    .speed(1.0)
    .model(OpenAiAudioApi.TtsModel.GPT_4_O_MINI_TTS.value)
    .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();

流式实时音频

语音 API 通过块传输编码支持实时音频流式。这意味着音频能在整个文件生成并可访问之前就被播放。

OpenAiAudioSpeechModel 实现了 StreamingTextToSpeechModel 接口，同时提供标准与流式能力。

java

var openAiAudioApi = new OpenAiAudioApi()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .build();

var openAiAudioSpeechModel = new OpenAiAudioSpeechModel(openAiAudioApi);

OpenAiAudioSpeechOptions speechOptions = OpenAiAudioSpeechOptions.builder()
    .voice(OpenAiAudioApi.SpeechRequest.Voice.ALLOY)
    .speed(1.0)
    .responseFormat(OpenAiAudioApi.SpeechRequest.AudioResponseFormat.MP3)
    .model(OpenAiAudioApi.TtsModel.GPT_4_O_MINI_TTS.value)
    .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!");

流的每个元素至多携带 8 KB 音频，即 OpenAiAudioSpeechModel 从底层 HTTP 响应拉取字节时使用的内部读缓冲区大小；块可能比这更小，取决于每次读取时已从 OpenAI 到达的数据量。

TIP

如果你需要把这个流交给一个只接受阻塞式 java.io.InputStream 的 API，参见把流作为阻塞式 InputStream 消费，其中有值得注意的实践和一个经过测试的参考实现。

每个打开的流会为其整个响应时长占用一个线程，因此 OpenAiAudioSpeechModel 在一个专做的 bounded-elastic 调度器上运行流式，而非用 Reactor 共享的 Schedulers.boundedElastic()，从而避免繁重的语音流负载饿死应用中别处无关联的阻塞工作。用 OpenAiAudioSpeechModel.builder().streamScheduler(customScheduler) 覆盖它，以便在组件间共享一个调度器，或为预期的并发流负载 differently 调整池大小。

定制 HTTP 客户端

Spring AI 在底层使用官方的 openai-java SDK，并通过由 SpringAiOpenAiHttpClient.Builder 构建的自定义 OkHttp 客户端来配置其 HTTP 传输。你可以通过暴露一个或多个 OpenAiHttpClientBuilderCustomizer bean，在底层 OkHttpClient 创建之前拦截那个构建器。每个定制器接收的都是每个 OpenAI 模型（聊天、嵌入、图像、音频、审核）所使用的同一个构建器，因此该定制会统一生效。

java

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

典型用例包括：

注册 OkHttp 的 Interceptor 实例（身份认证、传播头、自定义日志）；
更换调度器的 ExecutorService（例如，把异步 I/O 路由到虚拟线程）；
配置代理、SSL、主机名验证，或构建器暴露的连接池大小。

当存在多个定制器时，它们会按 @Order / Ordered 顺序、在 Spring AI 自身默认值之后应用，因此用户代码胜出。

当通过 OpenAi*Model.Builder 手动装配模型时，同样的钩子也可用：

java

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

迁移指南

如果你正从已弃用的 SpeechModel 和 SpeechPrompt 类升级，本指南提供迁移到新共享接口的详细说明。

破坏性变更概览

本次迁移包含以下破坏性变更：

移除的类：六个已弃用的类从 org.springframework.ai.openai.audio.speech 包中移除
包变更：核心 TTS 类移到 org.springframework.ai.audio.tts 包
类型变更：speed 参数在所有 OpenAI TTS 组件中从 Float 改为 Double
接口层次：TextToSpeechModel 现在继承 StreamingTextToSpeechModel

类映射参考

已弃用（移除）	新接口
`SpeechModel`	`TextToSpeechModel`
`StreamingSpeechModel`	`StreamingTextToSpeechModel`
`SpeechPrompt`	`TextToSpeechPrompt`
`SpeechResponse`	`TextToSpeechResponse`
`SpeechMessage`	`TextToSpeechMessage`
`Speech`（在 `org.springframework.ai.openai.audio.speech`）	`Speech`（在 `org.springframework.ai.audio.tts`）

分步迁移说明

步骤 1：更新导入

把所有来自旧 org.springframework.ai.openai.audio.speech 包的导入替换为新的共享接口：

Find:    import org.springframework.ai.openai.audio.speech.SpeechModel;
Replace: import org.springframework.ai.audio.tts.TextToSpeechModel;

Find:    import org.springframework.ai.openai.audio.speech.StreamingSpeechModel;
Replace: import org.springframework.ai.audio.tts.StreamingTextToSpeechModel;

Find:    import org.springframework.ai.openai.audio.speech.SpeechPrompt;
Replace: import org.springframework.ai.audio.tts.TextToSpeechPrompt;

Find:    import org.springframework.ai.openai.audio.speech.SpeechResponse;
Replace: import org.springframework.ai.audio.tts.TextToSpeechResponse;

Find:    import org.springframework.ai.openai.audio.speech.SpeechMessage;
Replace: import org.springframework.ai.audio.tts.TextToSpeechMessage;

Find:    import org.springframework.ai.openai.audio.speech.Speech;
Replace: import org.springframework.ai.audio.tts.Speech;

步骤 2：更新类型引用

替换代码中所有类型引用：

Find:    SpeechModel
Replace: TextToSpeechModel

Find:    StreamingSpeechModel
Replace: StreamingTextToSpeechModel

Find:    SpeechPrompt
Replace: TextToSpeechPrompt

Find:    SpeechResponse
Replace: TextToSpeechResponse

Find:    SpeechMessage
Replace: TextToSpeechMessage

步骤 3：更新 Speed 参数（Float → Double）

speed 参数从 Float 改为了 Double。更新所有出现之处：

Find:    .speed(1.0f)
Replace: .speed(1.0)

Find:    .speed(0.5f)
Replace: .speed(0.5)

Find:    Float speed
Replace: Double speed

若你有序列化过的数据或带 Float 值的配置文件，你也需要更新它们：

json

// Before
{
  "speed": 1.0
}

// After (no code change needed for JSON, but be aware of type change in Java)
{
  "speed": 1.0
}

步骤 4：更新 Bean 声明

若你有 Spring Boot 自动配置或手动的 bean 定义：

java

// Before
@Bean
public SpeechModel speechModel(OpenAiAudioApi audioApi) {
    return new OpenAiAudioSpeechModel(audioApi);
}

// After
@Bean
public TextToSpeechModel textToSpeechModel(OpenAiAudioApi audioApi) {
    return new OpenAiAudioSpeechModel(audioApi);
}

代码迁移示例

示例 1：基本的文本转语音转换

修改前（已弃用）：

java

import org.springframework.ai.openai.audio.speech.*;

@Service
public class OldNarrationService {

    private final SpeechModel speechModel;

    public OldNarrationService(SpeechModel speechModel) {
        this.speechModel = speechModel;
    }

    public byte[] createNarration(String text) {
        SpeechPrompt prompt = new SpeechPrompt(text);
        SpeechResponse response = speechModel.call(prompt);
        return response.getResult().getOutput();
    }
}

修改后（使用共享接口）：

java

import org.springframework.ai.audio.tts.*;
import org.springframework.ai.openai.OpenAiAudioSpeechModel;

@Service
public class NarrationService {

    private final TextToSpeechModel textToSpeechModel;

    public NarrationService(TextToSpeechModel textToSpeechModel) {
        this.textToSpeechModel = textToSpeechModel;
    }

    public byte[] createNarration(String text) {
        TextToSpeechPrompt prompt = new TextToSpeechPrompt(text);
        TextToSpeechResponse response = textToSpeechModel.call(prompt);
        return response.getResult().getOutput();
    }
}

示例 2：带自定义选项的文本转语音

修改前（已弃用）：

java

import org.springframework.ai.openai.audio.speech.*;
import org.springframework.ai.openai.api.OpenAiAudioApi;

SpeechModel model = new OpenAiAudioSpeechModel(audioApi);

OpenAiAudioSpeechOptions options = OpenAiAudioSpeechOptions.builder()
    .model("tts-1")
    .voice(OpenAiAudioApi.SpeechRequest.Voice.NOVA)
    .speed(1.0f)  // Float value
    .responseFormat(OpenAiAudioApi.SpeechRequest.AudioResponseFormat.MP3)
    .build();

SpeechPrompt prompt = new SpeechPrompt("Hello, world!", options);
SpeechResponse response = model.call(prompt);
byte[] audio = response.getResult().getOutput();

修改后（使用共享接口）：

java

import org.springframework.ai.audio.tts.*;
import org.springframework.ai.openai.OpenAiAudioSpeechModel;
import org.springframework.ai.openai.OpenAiAudioSpeechOptions;
import org.springframework.ai.openai.api.OpenAiAudioApi;

TextToSpeechModel model = new OpenAiAudioSpeechModel(audioApi);

OpenAiAudioSpeechOptions options = OpenAiAudioSpeechOptions.builder()
    .model("tts-1")
    .voice(OpenAiAudioApi.SpeechRequest.Voice.NOVA)
    .speed(1.0)  // Double value
    .responseFormat(OpenAiAudioApi.SpeechRequest.AudioResponseFormat.MP3)
    .build();

TextToSpeechPrompt prompt = new TextToSpeechPrompt("Hello, world!", options);
TextToSpeechResponse response = model.call(prompt);
byte[] audio = response.getResult().getOutput();

示例 3：流式文本转语音

修改前（已弃用）：

java

import org.springframework.ai.openai.audio.speech.*;
import reactor.core.publisher.Flux;

StreamingSpeechModel model = new OpenAiAudioSpeechModel(audioApi);
SpeechPrompt prompt = new SpeechPrompt("Stream this text");

Flux<SpeechResponse> stream = model.stream(prompt);
stream.subscribe(response -> {
    byte[] audioChunk = response.getResult().getOutput();
    // Process audio chunk
});

修改后（使用共享接口）：

java

import org.springframework.ai.audio.tts.*;
import org.springframework.ai.openai.OpenAiAudioSpeechModel;
import reactor.core.publisher.Flux;

TextToSpeechModel model = new OpenAiAudioSpeechModel(audioApi);
TextToSpeechPrompt prompt = new TextToSpeechPrompt("Stream this text");

Flux<TextToSpeechResponse> stream = model.stream(prompt);
stream.subscribe(response -> {
    byte[] audioChunk = response.getResult().getOutput();
    // Process audio chunk
});

示例 4：用 Spring Boot 做依赖注入

修改前（已弃用）：

java

@RestController
public class OldSpeechController {

    private final SpeechModel speechModel;

    @Autowired
    public OldSpeechController(SpeechModel speechModel) {
        this.speechModel = speechModel;
    }

    @PostMapping("/narrate")
    public ResponseEntity<byte[]> narrate(@RequestBody String text) {
        SpeechPrompt prompt = new SpeechPrompt(text);
        SpeechResponse response = speechModel.call(prompt);
        return ResponseEntity.ok()
            .contentType(MediaType.parseMediaType("audio/mpeg"))
            .body(response.getResult().getOutput());
    }
}

修改后（使用共享接口）：

java

@RestController
public class SpeechController {

    private final TextToSpeechModel textToSpeechModel;

    @Autowired
    public SpeechController(TextToSpeechModel textToSpeechModel) {
        this.textToSpeechModel = textToSpeechModel;
    }

    @PostMapping("/narrate")
    public ResponseEntity<byte[]> narrate(@RequestBody String text) {
        TextToSpeechPrompt prompt = new TextToSpeechPrompt(text);
        TextToSpeechResponse response = textToSpeechModel.call(prompt);
        return ResponseEntity.ok()
            .contentType(MediaType.parseMediaType("audio/mpeg"))
            .body(response.getResult().getOutput());
    }
}

Spring Boot 配置变更

Spring Boot 自动配置属性保持不变。你的 application.properties 或 application.yml 文件无需改动。

然而，若你有显式的 bean 引用或限定符，请更新它们：

java

// Before
@Qualifier("speechModel")

// After
@Qualifier("textToSpeechModel")

此次迁移的好处

可移植性：一次编写代码，即可在 OpenAI、ElevenLabs 或其他 TTS 服务商间轻松切换
一致性：与 ChatModel 及其他 Spring AI 抽象相同的模式
类型安全：借助恰当的接口实现，改进了类型层次
面向未来：新的 TTS 服务商将自动与你既有的代码协作
标准化：跨所有 TTS 服务商为 speed 参数统一使用 Double 类型

常见迁移问题与解决

问题 1：编译错误 - 找不到符号 SpeechModel

错误：

error: cannot find symbol SpeechModel

解决： 按步骤 1 所述更新你的导入，把 SpeechModel 改为 TextToSpeechModel。

问题 2：类型不匹配 - Float 无法转换为 Double

错误：

error: incompatible types: float cannot be converted to Double

解决： 从浮点字面量去掉 f 后缀（例如把 1.0f 改为 1.0）。

问题 3：运行时的 Bean 创建错误

错误：

NoSuchBeanDefinitionException: No qualifying bean of type 'SpeechModel'

解决： 更新你的依赖注入，用 TextToSpeechModel 取代 SpeechModel。

示例代码

OpenAiAudioSpeechModelIT.java 测试提供了一些关于如何使用该库的通用示例。

顾问（Advisor）API

聊天模型 API

嵌入模型 API

Amazon Bedrock

VertexAI

图像模型 API

音频模型

转录 API

文本转语音（TTS）API

审核模型

MCP 服务端 Boot Starter

MCP 注解

OpenAI 文本转语音（TTS）

引言

前置条件

自动配置

语音属性

连接属性

配置属性

运行时选项

手动配置

流式实时音频

定制 HTTP 客户端

迁移指南

破坏性变更概览

类映射参考

分步迁移说明

步骤 1：更新导入

步骤 2：更新类型引用

步骤 3：更新 Speed 参数（Float → Double）

步骤 4：更新 Bean 声明

代码迁移示例

示例 1：基本的文本转语音转换

示例 2：带自定义选项的文本转语音

示例 3：流式文本转语音

示例 4：用 Spring Boot 做依赖注入

Spring Boot 配置变更

此次迁移的好处

常见迁移问题与解决

问题 1：编译错误 - 找不到符号 SpeechModel

问题 2：类型不匹配 - Float 无法转换为 Double

问题 3：运行时的 Bean 创建错误

示例代码

友情链接