本站内所有文档均为中英对照文档，点击中文可以显示英文。此提醒连续关闭5次后，将不再显示。

文档内容来源于 spring.io，由 springdoc.tech 翻译，版权归属于 SPRING.IO (Broadcom. Inc)。可供个人学习、研究，未经许可，不得进行转载或用于商业行为。

OpenAI 文本转语音（TTS）

QWen Max 中英对照 OpenAI OpenAI Text-to-Speech (TTS)

介绍

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

以语音形式讲述一篇书面博客文章。
生成多种语言的语音音频。
使用流式传输提供实时音频输出。

前提条件

创建一个 OpenAI 账户并获取 API 密钥。您可以在 OpenAI 注册页面注册，并在 API Keys 页面生成 API 密钥。
在项目的构建文件中添加 spring-ai-openai 依赖。更多信息请参阅 Dependency Management 部分。

自动配置

备注

Spring AI 的自动配置和启动模块的工件名称发生了重大变化。请参阅升级说明以获取更多信息。

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。

属性	描述	默认值
spring.ai.openai.base-url	连接的 URL	api.openai.com
spring.ai.openai.api-key	API Key	-
spring.ai.openai.organization-id	可选，可指定用于 API 请求的组织 ID	-
spring.ai.openai.project-id	可选，可指定用于 API 请求的项目 ID	-

提示

对于属于多个组织的用户（或通过其旧版用户 API 密钥访问项目），您可以选择指定哪个组织和项目用于 API 请求。这些 API 请求的使用量将计入所指定的组织和项目。

配置属性

备注

音频语音自动配置的启用和禁用现在通过带有前缀 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	启用 Audio Speech 模型	openai
spring.ai.openai.audio.speech.base-url	连接的 URL	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.options.model	用于生成音频的模型 ID。可用模型：`gpt-4o-mini-tts`（默认，优化速度和成本）、`gpt-4o-tts`（更高音质）、`tts-1`（旧版，优化速度）或 `tts-1-hd`（旧版，优化音质）。	gpt-4o-mini-tts
spring.ai.openai.audio.speech.options.voice	用于合成的语音。对于 OpenAI 的 TTS API，可选语音包括所选模型支持的：alloy、echo、fable、onyx、nova 和 shimmer。	alloy
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 使用分块传输编码（chunk transfer encoding）支持实时音频流。这意味着音频可以在完整文件生成并可访问之前播放。

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 包
类型变更：所有 OpenAI TTS 组件中的 speed 参数类型已从 Float 改为 Double
接口继承关系：TextToSpeechModel 现在继承自 StreamingTextToSpeechModel

类映射参考

已弃用（已移除）	新接口
`SpeechModel`	`TextToSpeechModel`
`StreamingSpeechModel`	`StreamingTextToSpeechModel`
`SpeechPrompt`	`TextToSpeechPrompt`
`SpeechResponse`	`TextToSpeechResponse`
`SpeechMessage`	`TextToSpeechMessage`
`Speech` (in `org.springframework.ai.openai.audio.speech`)	`Speech` (in `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：更新速度参数（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 类型作为语速参数

常见迁移问题及解决方案

问题 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。

示例代码

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

介绍​

前提条件​

自动配置​

语音属性​

连接属性​

配置属性​

运行时选项​

手动配置​

流式实时音频​

迁移指南​

重大变更摘要​

类映射参考​

分步迁移说明​

步骤 1：更新导入​

步骤 2：更新类型引用​

步骤 3：更新速度参数（Float → Double）​

步骤 4：更新 Bean 声明​

代码迁移示例​

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

示例 2：使用自定义选项的文本转语音​

示例 3：流式文本转语音​

示例 4：使用 Spring Boot 进行依赖注入​

Spring Boot 配置变更​

迁移的优势​

常见迁移问题及解决方案​

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

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

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

示例代码​

介绍

前提条件

自动配置

语音属性

连接属性

配置属性

运行时选项

手动配置

流式实时音频

迁移指南

重大变更摘要

类映射参考

分步迁移说明

步骤 1：更新导入

步骤 2：更新类型引用

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

步骤 4：更新 Bean 声明

代码迁移示例

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

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

示例 3：流式文本转语音

示例 4：使用 Spring Boot 进行依赖注入

Spring Boot 配置变更

迁移的优势

常见迁移问题及解决方案

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

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

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

示例代码