Spring AI 使用 OpenAI 文本转语音（TTS）

简介

音频 API 提供了基于 OpenAI 文本转语音（TTS）模型的语音合成接口，支持用户实现以下功能：

为书面博客文章进行语音播报；

生成多语言的语音音频；

通过流式传输实现实时音频输出。

前提条件

注册 OpenAI 账号并获取 API 密钥。你可以在 OpenAI 注册页面创建账号，并在 API 密钥页面生成 API 密钥。

将 spring-ai-openai 依赖添加到项目的构建文件中。更多信息请参考依赖管理章节。

自动配置

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 连接。

对于属于多个组织的用户（或通过旧版用户 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.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);

// 获取元数据（速率限制信息）
OpenAiAudioSpeechResponseMetadata metadata = (OpenAiAudioSpeechResponseMetadata) response.getMetadata();

byte[] responseAsBytes = response.getResult().getOutput();

实时音频流式传输

语音合成 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);

FluxresponseStream = openAiAudioSpeechModel.stream(speechPrompt);

// 也可以直接流式传输原始音频字节
FluxaudioByteStream = openAiAudioSpeechModel.stream("Hello, world!");

迁移指南

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

破坏性变更总结

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

移除的类：org.springframework.ai.openai.audio.speech 包下 6 个已废弃的类已被移除；

包路径变更：核心 TTS 类迁移至 org.springframework.ai.audio.tts 包；

类型变更：所有 OpenAI TTS 组件的 speed 参数从 Float 改为 Double；

接口层级：TextToSpeechModel 现在继承 StreamingTextToSpeechModel。

类映射参考

分步迁移说明

步骤 1：更新导入

将所有旧包 org.springframework.ai.openai.audio.speech 的导入替换为新的通用接口：

查找：    import org.springframework.ai.openai.audio.speech.SpeechModel;
替换：import org.springframework.ai.audio.tts.TextToSpeechModel;

查找：    import org.springframework.ai.openai.audio.speech.StreamingSpeechModel;
替换：import org.springframework.ai.audio.tts.StreamingTextToSpeechModel;

查找：    import org.springframework.ai.openai.audio.speech.SpeechPrompt;
替换：import org.springframework.ai.audio.tts.TextToSpeechPrompt;

查找：    import org.springframework.ai.openai.audio.speech.SpeechResponse;
替换：import org.springframework.ai.audio.tts.TextToSpeechResponse;

查找：    import org.springframework.ai.openai.audio.speech.SpeechMessage;
替换：import org.springframework.ai.audio.tts.TextToSpeechMessage;

查找：    import org.springframework.ai.openai.audio.speech.Speech;
替换：import org.springframework.ai.audio.tts.Speech;

步骤 2：更新类型引用

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

查找：    SpeechModel
替换：TextToSpeechModel

查找：    StreamingSpeechModel
替换：StreamingTextToSpeechModel

查找：    SpeechPrompt
替换：TextToSpeechPrompt

查找：    SpeechResponse
替换：TextToSpeechResponse

查找：    SpeechMessage
替换：TextToSpeechMessage

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

speed 参数类型从 Float 改为 Double，更新所有使用场景：

查找：    .speed(1.0f)
替换：.speed(1.0)

查找：    .speed(0.5f)
替换：.speed(0.5)

查找：    Float speed
替换：Double speed

如果你的序列化数据或配置文件包含 Float 数值，也需要同步更新：

// 旧版
{
  "speed": 1.0
}

// 新版（JSON 无需代码修改，仅需注意 Java 中的类型变更）
{
  "speed": 1.0
}

步骤 4：更新 Bean 声明

如果存在 Spring Boot 自动配置或手动 Bean 定义：

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

// 新版
@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 类型
    .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 类型
    .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");

Fluxstream = model.stream(prompt);
stream.subscribe(response -> {
    byte[] audioChunk = response.getResult().getOutput();
    // 处理音频分片
});

新版（使用通用接口）：

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

Fluxstream = model.stream(prompt);
stream.subscribe(response -> {
    byte[] audioChunk = response.getResult().getOutput();
    // 处理音频分片
});

示例 4：Spring Boot 依赖注入

旧版（已废弃）：

@RestController
public class OldSpeechController {

    private final SpeechModel speechModel;

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

    @PostMapping("/narrate")
    public ResponseEntitynarrate(@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 ResponseEntitynarrate(@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 引用或限定符，需要更新：

// 旧版
@Qualifier("speechModel")

// 新版
@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。

示例代码

OpenAiSpeechModelIT.java 测试类提供了使用该库的通用示例。