OpenAI 文本转语音（TTS）

简介

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

为书面博客文章生成语音朗读。
以多种语言生成口语化音频。
使用流式传输实现实时音频输出。

前置条件

创建一个 OpenAI 账户并获取 API 密钥。你可以在 OpenAI 注册页面进行注册，并在 API 密钥页面生成 API 密钥。
将 spring-ai-openai 依赖添加到你的项目构建文件中。更多信息请参考依赖管理部分。

语音属性

连接属性

属性前缀 spring.ai.openai 用于配置与 OpenAI 的连接。

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

对于属于多个组织的用户（或通过遗留的用户 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 文本转语音（TTS）客户端。

属性	描述	默认值
`spring.ai.model.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`	合成语音使用的声音。可用声音：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);

以上示例展示了如何使用 OpenAiAudioSpeechOptions 配置模型、语音、音频格式及语速，并将其应用于文本转语音请求。

手动配置

将 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();

该示例展示了如何配置模型、语速和输出格式，并调用 OpenAI 文本转语音服务，同时获取生成的音频数据及相关元数据。

实时音频流

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

// 也可以直接流式获取原始音频字节
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`（位于 `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 值，也需要注意类型变化：

// 之前
{
  "speed": 1.0
}

// 之后（JSON 不需要改动，但在 Java 中类型已变为 Double）
{
  "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：基础文本转语音（Text-to-Speech）

迁移前（已废弃）：

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

Flux<SpeechResponse> stream = 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");

Flux<TextToSpeechResponse> stream = 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 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 引用或限定符，需要进行更新：

// 迁移前
@Qualifier("speechModel")

// 迁移后
@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 测试提供了一些使用该库的通用示例。

Text-To-Speech (TTS) API

Spring AI 提供了统一的文本转语音（TTS）API，通过 TextToSpeechModel 和 StreamingTextToSpeechModel 接口实现。这使您可以编写可移植的代码，适用于不同的 TTS 提供商。

ElevenLabs