OpenAI 文本转语音(TTS)

介绍

音频API基于OpenAI的转语音(TTS)模型提供语音端点,使用户能够:spring-doc.cadn.net.cn

前提条件

  1. 创建一个OpenAI账户并获取API密钥。你可以在 OpenAI 注册页面注册,并在 API 密钥页面生成 API 密钥。spring-doc.cadn.net.cn

  2. 添加春艾开胃依赖你项目的构建文件。更多信息请参阅依赖管理部分。spring-doc.cadn.net.cn

自动配置

春季AI自动配置、起始模块的工件名称发生了重大变化。 更多信息请参阅升级说明spring-doc.cadn.net.cn

Spring AI 为 OpenAI 文本转语音客户端提供了 Spring Boot 自动配置。 要启用它,请在项目的Maven中添加以下依赖pom.xml文件:spring-doc.cadn.net.cn

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

或者去你的Gradlebuild.gradle构建文件:spring-doc.cadn.net.cn

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-openai'
}
请参考依赖管理部分,将Spring AI的物料清单添加到你的构建文件中。

语音属性

连接性质

前缀春.ai.openai作为属性前缀,允许你连接到OpenAI。spring-doc.cadn.net.cn

属性spring-doc.cadn.net.cn

描述spring-doc.cadn.net.cn

默认值spring-doc.cadn.net.cn

Spring.ai.openai.base-urlspring-doc.cadn.net.cn

连接的URL(链接)spring-doc.cadn.net.cn

api.openai.comspring-doc.cadn.net.cn

spring.ai.openai.api-key(春.ai.openai.api-key)spring-doc.cadn.net.cn

API 密钥spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai.organization-idspring-doc.cadn.net.cn

你可以选择指定用于 API 请求的组织。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai.project-idspring-doc.cadn.net.cn

可选地,你可以指定用于 API 请求的项目。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

对于属于多个组织的用户(或通过其遗留用户 API 密钥访问项目),你可以选择指定用于 API 请求的组织和项目。 这些 API 请求的使用将计入指定组织和项目的使用。

配置属性

现在通过带有前缀的顶层属性配置,启用和禁用音频语音自动配置spring.ai.model.audio.speech.spring-doc.cadn.net.cn

启用时,spring.ai.model.audio.speech=openai(默认启用)spring-doc.cadn.net.cn

要禁用,可以选择 spring.ai.model.audio.speech=none(或任何与 openai 不匹配的值)spring-doc.cadn.net.cn

此改动旨在允许配置多个模型。spring-doc.cadn.net.cn

前缀spring.ai.openai.audio.speech作为属性前缀,用于配置OpenAI文本转语音客户端。spring-doc.cadn.net.cn

属性 描述 默认值

spring.ai.model.audio.speechspring-doc.cadn.net.cn

启用音频语音模型spring-doc.cadn.net.cn

OpenAIspring-doc.cadn.net.cn

spring.ai.openai.audio.speech.base-urlspring-doc.cadn.net.cn

连接的URL(链接)spring-doc.cadn.net.cn

api.openai.comspring-doc.cadn.net.cn

spring.ai.openai.audio.speech.api-keyspring-doc.cadn.net.cn

API 密钥spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai.audio.speech.organization-idspring-doc.cadn.net.cn

你可以选择指定用于 API 请求的组织。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai.audio.speech.project-idspring-doc.cadn.net.cn

可选地,你可以指定用于 API 请求的项目。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.openai.audio.speech.options.modelspring-doc.cadn.net.cn

用来生成音频的模型ID。可选型号:GPT-40-MINI-TTS(默认情况下,针对速度和成本进行了优化),GPT-40-TTS(质量更高),TTS-1(传统,优化速度),或者TTS-1-HD(传统,优化质量)。spring-doc.cadn.net.cn

GPT-40-MINI-TTSspring-doc.cadn.net.cn

spring.ai.openai.audio.speech.options.voicespring-doc.cadn.net.cn

合成时的声音。对于OpenAI的TTS API,所选模型可选的声音之一是:合金、回声、寓言、黑曜石、新星和闪烁。spring-doc.cadn.net.cn

合金spring-doc.cadn.net.cn

spring.ai.openai.audio.speech.options.response-formatspring-doc.cadn.net.cn

音频输出的格式。支持的格式包括mp3、opus、aac、flac、wav和PCM。spring-doc.cadn.net.cn

mp3spring-doc.cadn.net.cn

spring.ai.openai.audio.speech.options.speedspring-doc.cadn.net.cn

声音合成的速度。可接受的范围是0.25(最慢)到4.0(最快)。spring-doc.cadn.net.cn

1.0spring-doc.cadn.net.cn

你可以覆盖公共信息Spring.ai.openai.base-url,spring.ai.openai.api-key(春.ai.openai.api-key),spring.ai.openai.organization-idspring.ai.openai.project-id性能。 这spring.ai.openai.audio.speech.base-url,spring.ai.openai.audio.speech.api-key,spring.ai.openai.audio.speech.organization-idspring.ai.openai.audio.speech.project-id如果设置了属性,属性优先于常见属性。 如果你想为不同模型和不同模型端点使用不同的OpenAI账户,这非常有用。
所有以spring.ai.openai.audio.speech.options可以在运行时被覆盖。

运行时选项

OpenAiAudioSpeechOptions类提供了在发送文本转语音请求时可用的选项。启动时,指定了以下选项spring.ai.openai.audio.speech但你可以在运行时覆盖这些设置。spring-doc.cadn.net.cn

OpenAiAudioSpeechOptions类实现了文本语音选项接口,提供便携式和OpenAI专用配置选项。spring-doc.cadn.net.cn

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文件:spring-doc.cadn.net.cn

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

或者去你的Gradlebuild.gradle构建文件:spring-doc.cadn.net.cn

dependencies {
    implementation 'org.springframework.ai:spring-ai-openai'
}
请参考依赖管理部分,将Spring AI的物料清单添加到你的构建文件中。

接下来,创建一个OpenAiAudioSpeechModel:spring-doc.cadn.net.cn

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支持使用分块传输编码进行实时音频流传输。这意味着音频可以在完整文件生成并可访问之前播放。spring-doc.cadn.net.cn

OpenAiAudioSpeechModel实现流式文本转语音模型界面,既提供标准功能,也提供流媒体功能。spring-doc.cadn.net.cn

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

迁徙指南

如果你是从弃用版本升级的语音模型演讲提示本指南提供了迁移到新共享接口的详细说明。spring-doc.cadn.net.cn

重大变更摘要

此次迁移包含以下重大变更:spring-doc.cadn.net.cn

  1. 移除的类别:六个废弃类别已被移除org.springframework.ai.openai.audio.speechspring-doc.cadn.net.cn

  2. 套餐变更:核心TTS课程迁移至org.springframework.ai.audio.ttsspring-doc.cadn.net.cn

  3. 类型变更:该速度参数从跨越所有OpenAI TTS组件spring-doc.cadn.net.cn

  4. 界面层级文本转语音模型现今延伸流式文本转语音模型spring-doc.cadn.net.cn

类映射参考

已弃用(已移除) 新界面

语音模型spring-doc.cadn.net.cn

文本转语音模型spring-doc.cadn.net.cn

StreamingSpeechModelspring-doc.cadn.net.cn

流式文本转语音模型spring-doc.cadn.net.cn

演讲提示spring-doc.cadn.net.cn

文本转语音提示spring-doc.cadn.net.cn

语音反应spring-doc.cadn.net.cn

文本转语音回复spring-doc.cadn.net.cn

演讲信息spring-doc.cadn.net.cn

文字转语音信息spring-doc.cadn.net.cn

演讲(在org.springframework.ai.openai.audio.speech)spring-doc.cadn.net.cn

演讲(在org.springframework.ai.audio.tts)spring-doc.cadn.net.cn

逐步迁移说明

步骤1:更新导入

替换所有旧导入的org.springframework.ai.openai.audio.speech包含新共享接口的包装:spring-doc.cadn.net.cn

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:更新类型引用

替换代码中的所有类型引用:spring-doc.cadn.net.cn

Find:    SpeechModel
Replace: TextToSpeechModel

Find:    StreamingSpeechModel
Replace: StreamingTextToSpeechModel

Find:    SpeechPrompt
Replace: TextToSpeechPrompt

Find:    SpeechResponse
Replace: TextToSpeechResponse

Find:    SpeechMessage
Replace: TextToSpeechMessage

步骤3:更新速度参数(浮点→倍)

速度参数已更改为. 更新所有事件:spring-doc.cadn.net.cn

Find:    .speed(1.0f)
Replace: .speed(1.0)

Find:    .speed(0.5f)
Replace: .speed(0.5)

Find:    Float speed
Replace: Double speed

如果你有带有浮点值的序列化数据或配置文件,也需要更新它们:spring-doc.cadn.net.cn

// Before
{
  "speed": 1.0
}

// After (no code change needed for JSON, but be aware of type change in Java)
{
  "speed": 1.0
}

步骤4:更新豆子声明

如果你有 Spring Boot 自动配置或手动豆子定义:spring-doc.cadn.net.cn

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

// After
@Bean
public TextToSpeechModel textToSpeechModel(OpenAiAudioApi audioApi) {
    return new OpenAiAudioSpeechModel(audioApi);
}

代码迁移示例

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

之前(已弃用):spring-doc.cadn.net.cn

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

之后(使用共享接口):spring-doc.cadn.net.cn

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:带有自定义选项的文本转语音

之前(已弃用):spring-doc.cadn.net.cn

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

之后(使用共享接口):spring-doc.cadn.net.cn

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:流式文本转语音

之前(已弃用):spring-doc.cadn.net.cn

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

之后(使用共享接口):spring-doc.cadn.net.cn

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进行依赖注入

之前(已弃用):spring-doc.cadn.net.cn

@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());
    }
}

之后(使用共享接口):spring-doc.cadn.net.cn

@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.propertiesapplication.yml文件。spring-doc.cadn.net.cn

不过,如果你有明确的Beans引用或限定词,请更新它们:spring-doc.cadn.net.cn

// Before
@Qualifier("speechModel")

// After
@Qualifier("textToSpeechModel")

迁徙的好处

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

问题1:编译错误——找不到符号语音模型

error: cannot find symbol SpeechModel

溶液: 按照步骤1的步骤更新导入,进行更改语音模型文本转语音模型.spring-doc.cadn.net.cn

问题2:类型不匹配——浮点无法转换成双倍

error: incompatible types: float cannot be converted to Double

溶液: 移除f浮点数文字的后缀(例如,change1.0f1.0).spring-doc.cadn.net.cn

问题3:运行时豆子创建错误

NoSuchBeanDefinitionException: No qualifying bean of type 'SpeechModel'

溶液: 更新你的依赖注入以使用文本转语音模型而不是语音模型.spring-doc.cadn.net.cn

示例代码