OpenAI 文本转语音 (TTS)
< Introduction >
音频 API 提供了一个基于 OpenAI TTS（文本转语音）模型的语音端点，使用户能够：
-
叙述一篇书面博客文章。
-
以多种语言生成语音音频。
-
使用流式传输提供实时音频输出。
前置条件
-
创建一个 OpenAI 账户并获取 API 密钥。您可以在 OpenAI 注册页面 进行注册，并在 API 密钥页面 生成 API 密钥。
-
将
spring-ai-openai依赖项添加到项目的构建文件中。更多信息，请参阅 依赖管理 部分。
Auto-configuration
|
Spring AI自动配置和starter模块的artifact名称有了重大变化。 请参阅升级说明获取更多信息。 |
Spring AI 为 OpenAI 文本转语音客户端提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目的 Maven pom.xml 文件中：
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>或添加到您的 Gradle build.gradle 构建文件中：
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-openai'
}| 请参阅依赖管理部分，将Spring AI BOM添加到您的构建文件中。 |
语音属性
连接属性
使用前缀spring.ai.openai作为属性前缀，以便连接到OpenAI。
<property> </property> |
<description> </description> |
默认 |
spring.ai.openai.base-url |
连接的URL |
|
spring.ai.openai.api-key |
API密钥 |
- |
spring.ai.openai.organization-id |
您可以选择指定用于 API 请求的组织。 |
- |
spring.ai.openai.project-id |
（可选）您可以指定用于 API 请求的项目。 |
- |
| 对于属于多个组织（或通过其旧版用户 API 密钥访问其项目）的用户，您可以选择指定用于 API 请求的组织和项目。 这些 API 请求的使用量将计入指定的组织和项目。 |
配置属性
|
启用和禁用音频语音自动配置现在通过前缀为 要启用，请设置 spring.ai.model.audio.speech=openai（默认已启用） 要禁用，请设置 spring.ai.model.audio.speech=none（或任何不与 openai 匹配的值） 此更改是为了允许配置多个模型。 |
前缀 spring.ai.openai.audio.speech 用作属性前缀，让您能够配置 OpenAI 文本转语音客户端。
| <property> </property> | <description> </description> | 默认 |
|---|---|---|
spring.ai.model.audio.speech |
启用音频语音模型 |
OpenAI |
spring.ai.openai.audio.speech.base-url |
连接的URL |
|
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.options.model |
用于生成音频的模型 ID。可用模型： |
gpt-4o-mini-tts |
spring.ai.openai.audio.speech.options.voice |
用于合成的语音。对于 OpenAI 的 TTS API，这是所选模型可用的语音之一：alloy、echo、fable、onyx、nova 和 shimmer。 |
合金 |
spring.ai.openai.audio.speech.options.response-format |
音频输出的格式。支持的格式包括 mp3、opus、aac、flac、wav 和 pcm。 |
mp3 |
spring.ai.openai.audio.speech.options.speed |
语音合成的速度。可接受范围是从 0.25（最慢）到 4.0（最快）。 |
1.0 |
您可以覆盖通用的 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 账户，这将非常有用。 |
所有以 spring.ai.openai.audio.speech.options 为前缀的属性都可以在运行时被覆盖。 |
运行时选项
OpenAiAudioSpeechOptions 类提供了发出文本转语音请求时使用的选项。
启动时，会使用由 spring.ai.openai.audio.speech 指定的选项，但您可以在运行时覆盖这些选项。
OpenAiAudioSpeechOptions 类实现了 TextToSpeechOptions 接口，提供了可移植的以及针对 OpenAI 的配置选项。
例如：
OpenAiAudioSpeechOptions speechOptions = OpenAiAudioSpeechOptions.builder()
.model("gpt-4o-mini-tts")
.voice(OpenAiAudioApi.SpeechRequest.Voice.ALLOY)
.responseFormat(OpenAiAudioApi.SpeechRequest.AudioResponseFormat.MP3)
.speed(1.0)
.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文件中：
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-openai</artifactId>
</dependency>或添加到您的 Gradle build.gradle 构建文件中：
dependencies {
implementation 'org.springframework.ai:spring-ai-openai'
}| 请参阅依赖管理部分，将Spring AI BOM添加到您的构建文件中。 |
接下来，创建一个 OpenAiAudioSpeechModel：
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();流式实时音频
Speech API 支持使用分块传输编码进行实时音频流传输。这意味着在完整文件生成并可访问之前，即可播放音频。
OpenAiAudioSpeechModel 实现了 StreamingTextToSpeechModel 接口，同时提供标准和流式功能。
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!");迁移指南
如果您正从已弃用的 SpeechModel 和 SpeechPrompt 类进行升级，本指南提供了迁移到新的共享接口的详细说明。
重大变更摘要
此次迁移包含以下破坏性变更：
-
已移除的类：六个已弃用的类已从
org.springframework.ai.openai.audio.speech包中移除 -
包变更：核心 TTS 类已移至
org.springframework.ai.audio.tts包 -
类型变更：
speed参数在所有 OpenAI TTS 组件中从Float变更为Double -
接口层次结构:
TextToSpeechModel现在扩展了StreamingTextToSpeechModel
类映射参考
| 已弃用（已移除） | 新接口 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
逐步迁移说明
步骤 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：更新速度参数（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 值的序列化数据或配置文件，您也需要更新它们：
// 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 定义：
// Before
@Bean
public SpeechModel speechModel(OpenAiAudioApi audioApi) {
return new OpenAiAudioSpeechModel(audioApi);
}
// After
@Bean
public TextToSpeechModel textToSpeechModel(OpenAiAudioApi audioApi) {
return new OpenAiAudioSpeechModel(audioApi);
}代码迁移示例
示例 1：基础文本转语音转换
之前（已弃用）：
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();
}
}使用共享接口后：
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：使用自定义选项的文本转语音
之前（已弃用）：
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();使用共享接口后：
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：流式文本转语音
之前（已弃用）：
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
});使用共享接口后：
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 进行依赖注入
之前（已弃用）：
@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());
}
}使用共享接口后：
@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 引用或限定符，请更新它们：
// Before
@Qualifier("speechModel")
// After
@Qualifier("textToSpeechModel")迁移的好处
-
可移植性：一次编写代码，即可轻松在 OpenAI、ElevenLabs 或其他文本转语音（TTS）提供商之间切换
-
一致性：与 ChatModel 及其他 Spring AI 抽象相同的模式
-
类型安全：通过正确的接口实现改进了类型层次结构
-
面向未来：新的 TTS 提供商将自动与您的现有代码兼容
-
标准化：在所有 TTS 提供商中，速度参数使用一致的
Double类型
示例代码
-
OpenAiSpeechModelIT.java 测试提供了一些关于如何使用该库的通用示例。