版本：2.0.1

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

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

OpenAI 文本转语音（TTS）

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

介绍

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

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

备注

从版本 2.0.0-M5 开始，Spring AI 底层为所有 OpenAI 模型使用官方 openai-java SDK。此次过渡预期是无缝的，且对于现有使用 OpenAI API 属性和构建器的用户没有破坏性变更。如果您发现任何问题，请通过 Spring AI GitHub Issues 向我们报告。

前置条件

创建 OpenAI 账号并获取 API Key。您可以访问 OpenAI 注册页面进行注册，并在 API Keys 页面生成 API Key。
在项目的构建文件中添加 spring-ai-openai 依赖项。更多信息请参阅 Dependency Management 章节。

自动配置

备注

Spring AI 的自动配置（auto-configuration）以及 starter 模块的构件（artifact）名称已发生重大变更。详情请参阅升级说明。

Spring AI 为 OpenAI Text-to-Speech Client 提供了 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'
}

提示

请参考 Dependency Management 章节，将 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	-
spring.ai.openai.timeout	OpenAI 客户端的请求超时时间	60 秒
spring.ai.openai.max-retries	OpenAI 客户端的最大重试次数	3
spring.ai.openai.proxy	OpenAI 客户端的代理设置	-
spring.ai.openai.custom-headers	为 OpenAI 客户端请求添加的自定义 HTTP 头部	空
spring.ai.openai.connection-pool-metrics-enabled	是否为底层的 OkHttp 客户端启用连接池指标	false

提示

对于属于多个组织（或通过其旧版用户 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 Text-to-Speech 客户端。

属性	描述	默认值
spring.ai.model.audio.speech	启用 Audio Speech Model	openai
spring.ai.openai.audio.speech.base-url	连接的目标 URL	api.openai.com
spring.ai.openai.audio.speech.api-key	API Key	-
spring.ai.openai.audio.speech.organization-id	可选，用于指定 API 请求所使用的组织。	-
spring.ai.openai.audio.speech.project-id	可选，用于指定 API 请求所使用的 Project。	-
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` 会忽略此配置。	-

备注

您可以覆盖通用的 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 为前缀的属性都可以在运行时覆盖。

运行时选项

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)
    .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);

手动配置

在项目的 Maven pom.xml 文件中添加 spring-ai-openai 依赖项：

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

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

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

提示

请参考 Dependency Management 部分，在构建文件中添加 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!");

流中的每个元素最多携带 8 KB 的音频数据，这是 OpenAiAudioSpeechModel 从底层 HTTP 响应中读取字节时使用的内部读缓冲区大小；根据每次读取时从 OpenAI 到达的数据量，这些块可能会更小。

提示

如果你需要将此流传递给仅接受阻塞式 java.io.InputStream 的 API，请参阅将流作为阻塞式 InputStream 进行消费，其中介绍了关键的实践以及一个经过测试的参考实现。

每个打开的流在整个响应持续期间都会占用一个线程，因此 OpenAiAudioSpeechModel 使用专用的 bounded-elastic 调度器来运行流式处理，而不是 Reactor 共享的 Schedulers.boundedElastic()，从而避免沉重的语音流负载导致应用中其他地方的无关阻塞工作被饿死。可以通过 OpenAiAudioSpeechModel.builder().streamScheduler(customScheduler) 进行覆盖，以便在组件间共享调度器，或针对预期的并发流负载调整线程池大小。

自定义 HTTP 客户端

Spring AI 在底层使用官方的 openai-java SDK，并通过 SpringAiOpenAiHttpClient.Builder 构建的自定义 OkHttp 客户端配置其 HTTP 传输层。在底层 OkHttpClient 创建之前，您可以暴露一个或多个 OpenAiHttpClientBuilderCustomizer Bean 来拦截该 builder。每个 customizer 都会接收所有 OpenAI 模型（chat、embedding、image、audio、moderation）共用的同一个 builder，因此自定义配置会统一生效。

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

典型的用例包括：

注册 OkHttp Interceptor 实例（认证、传播请求头、自定义日志记录）；
替换调度器 ExecutorService（例如，将异步 I/O 路由至虚拟线程）；
通过 Builder 配置代理、SSL、主机名验证或连接池大小。

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

相同的钩子也可以在使用 OpenAi*Model.Builder 手动配置模型时使用：

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 包
类型变更：所有 OpenAI TTS 组件中的 speed 参数已从 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 值，您还需要更新它们：

// 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 步中的说明更新您的 imports，将 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 测试提供了一些如何使用该库的一般示例。

介绍​

前置条件​

自动配置​

语音属性​

连接属性​

配置属性​

运行时选项​

手动配置​

流式实时音频​

自定义 HTTP 客户端​

迁移指南​

破坏性变更摘要​

类映射参考​

分步迁移说明​

步骤 1：更新导入​

第 2 步：更新类型引用​

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

步骤 4：更新 Bean 声明​

代码迁移示例​

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

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

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

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

Spring Boot 配置变更​

迁移的好处​

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

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

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

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

示例代码​

介绍

前置条件

自动配置

语音属性

连接属性

配置属性

运行时选项

手动配置

流式实时音频

自定义 HTTP 客户端

迁移指南

破坏性变更摘要

类映射参考

分步迁移说明

步骤 1：更新导入

第 2 步：更新类型引用

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

步骤 4：更新 Bean 声明

代码迁移示例

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

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

示例 3：流式文本转语音

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

Spring Boot 配置变更

迁移的好处

常见迁移问题与解决方案

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

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

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

示例代码