OpenAI 文本转语音(TTS)
前提条件
-
创建一个OpenAI账户并获取API密钥。你可以在 OpenAI 注册页面注册,并在 API 密钥页面生成 API 密钥。
-
添加
春艾开胃依赖你项目的构建文件。更多信息请参阅依赖管理部分。
自动配置
|
春季AI自动配置、起始模块的工件名称发生了重大变化。 更多信息请参阅升级说明。 |
Spring AI 为 OpenAI 文本转语音客户端提供了 Spring Boot 自动配置。
要启用它,请在项目的Maven中添加以下依赖pom.xml文件:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>
或者去你的Gradlebuild.gradle构建文件:
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-openai'
}
| 请参考依赖管理部分,将Spring AI的物料清单添加到你的构建文件中。 |
语音属性
连接性质
前缀春.ai.openai作为属性前缀,允许你连接到OpenAI。
属性 |
描述 |
默认值 |
Spring.ai.openai.base-url |
连接的URL(链接) |
|
spring.ai.openai.api-key(春.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文本转语音客户端。
| 属性 | 描述 | 默认值 |
|---|---|---|
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-40-MINI-TTS |
spring.ai.openai.audio.speech.options.voice |
合成时的声音。对于OpenAI的TTS API,所选模型可选的声音之一是:合金、回声、寓言、黑曜石、新星和闪烁。 |
合金 |
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(春.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类实现了文本语音选项接口,提供便携式和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);
手动配置
添加春艾开胃对你项目Maven的依赖pom.xml文件:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-openai</artifactId>
</dependency>
或者去你的Gradlebuild.gradle构建文件:
dependencies {
implementation 'org.springframework.ai:spring-ai-openai'
}
| 请参考依赖管理部分,将Spring AI的物料清单添加到你的构建文件中。 |
接下来,创建一个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();
实时音频流媒体
语音API支持使用分块传输编码进行实时音频流传输。这意味着音频可以在完整文件生成并可访问之前播放。
这OpenAiAudioSpeechModel实现流式文本转语音模型界面,既提供标准功能,也提供流媒体功能。
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!");
迁徙指南
如果你是从弃用版本升级的语音模型和演讲提示本指南提供了迁移到新共享接口的详细说明。
重大变更摘要
此次迁移包含以下重大变更:
-
移除的类别:六个废弃类别已被移除
org.springframework.ai.openai.audio.speech包 -
套餐变更:核心TTS课程迁移至
org.springframework.ai.audio.tts包 -
类型变更:该
速度参数从浮自双跨越所有OpenAI 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:更新速度参数(浮点→倍)
这速度参数已更改为浮自双. 更新所有事件:
Find: .speed(1.0f)
Replace: .speed(1.0)
Find: .speed(0.5f)
Replace: .speed(0.5)
Find: Float speed
Replace: Double speed
如果你有带有浮点值的序列化数据或配置文件,也需要更新它们:
// Before
{
"speed": 1.0
}
// After (no code change needed for JSON, but be aware of type change in Java)
{
"speed": 1.0
}
代码迁移示例
示例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文件。
不过,如果你有明确的Beans引用或限定词,请更新它们:
// Before
@Qualifier("speechModel")
// After
@Qualifier("textToSpeechModel")
迁徙的好处
-
可移植性:只需编写一次代码,即可轻松切换 OpenAI、ElevenLabs 或其他 TTS 服务商
-
一致性:与ChatModel及其他Spring AI抽象的模式相同
-
类型安全:通过正确的接口实现改进类型层级
-
未来兼容:新的TTS服务提供商将自动使用您现有的代码
-
标准化:一致
双在所有TTS提供商中输入速度参数类型
示例代码
-
OpenAiSpeechModelIT.java测试提供了一些通用的使用示例。