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

简介

ElevenLabs 提供基于深度学习的自然语音合成软件。其 AI 音频模型能够生成逼真、通用且具备上下文感知能力的语音、音色和音效，支持 32 种语言。ElevenLabs 文本转语音 API 可让用户通过超逼真的 AI 语音播报，为任意书籍、文章、PDF、新闻简报或文本赋予生命力。

前提条件

注册 ElevenLabs 账号并获取 API 密钥。你可以在 ElevenLabs 注册页面完成注册，登录后在个人资料页面查看你的 API 密钥。

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

自动配置

Spring AI 为 ElevenLabs 文本转语音客户端提供了 Spring Boot 自动配置。要启用该功能，请将以下依赖添加到项目的 Maven pom.xml 文件中：

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

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

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-elevenlabs'
}

请参考依赖管理章节，将 Spring AI BOM 添加到你的构建文件中。

语音合成配置属性

连接属性

spring.ai.elevenlabs 用作所有 ElevenLabs 相关配置的属性前缀（包括连接配置和 TTS 专属配置），该配置在 ElevenLabsConnectionProperties 中定义。

配置属性

音频语音合成自动配置的启用和禁用现在通过以 spring.ai.model.audio.speech 为前缀的顶级属性进行配置。

启用：spring.ai.model.audio.speech=elevenlabs（默认启用）

禁用：spring.ai.model.audio.speech=none（或任何与 elevenlabs 不匹配的值）

进行此更改是为了支持多模型配置。

spring.ai.elevenlabs.tts 前缀用作属性前缀，专门用于配置 ElevenLabs 文本转语音客户端，该配置在 ElevenLabsSpeechProperties 中定义。

基础地址和 API 密钥也可以通过 spring.ai.elevenlabs.tts.base-url 和 spring.ai.elevenlabs.tts.api-key 专门为 TTS 配置。但通常建议为了简便使用全局 spring.ai.elevenlabs 前缀，除非你需要为不同的 ElevenLabs 服务使用不同的凭证。更具体的 TTS 属性会覆盖全局属性。

所有以 spring.ai.elevenlabs.tts.options 为前缀的属性均可在运行时覆盖。

表 1. 可用输出格式

运行时选项

ElevenLabsTextToSpeechOptions 类提供了文本转语音请求的配置选项。启动时会使用 spring.ai.elevenlabs.tts 指定的配置，你也可以在运行时覆盖这些配置。可用选项如下：

modelId：使用的模型 ID；

voiceId：使用的音色 ID；

outputFormat：生成音频的输出格式；

voiceSettings：包含音色配置的对象，如稳定性、相似度增强、风格、使用扬声器增强、语速；

enableLogging：布尔值，启用或禁用日志；

languageCode：输入文本的语言代码（如 "en" 代表英语）；

pronunciationDictionaryLocators：发音字典定位器列表；

seed：随机数生成种子，用于结果复现；

previousText：主文本之前的内容，用于多轮对话上下文；

nextText：主文本之后的内容，用于多轮对话上下文；

previousRequestIds：对话上一轮的请求 ID；

nextRequestIds：对话下一轮的请求 ID；

applyTextNormalization：应用文本标准化（可选值 "auto"、"on"、"off"）；

applyLanguageTextNormalization：应用语言文本标准化。

示例：

ElevenLabsTextToSpeechOptions speechOptions = ElevenLabsTextToSpeechOptions.builder()
    .model("eleven_multilingual_v2")
    .voiceId("your_voice_id")
    .outputFormat(ElevenLabsApi.OutputFormat.MP3_44100_128.getValue())
    .build();

TextToSpeechPrompt speechPrompt = new TextToSpeechPrompt("Hello, this is a text-to-speech example.", speechOptions);
TextToSpeechResponse response = elevenLabsTextToSpeechModel.call(speechPrompt);

使用音色配置

你可以在配置中提供 VoiceSettings 来自定义语音输出，控制稳定性、相似度等属性。

var voiceSettings = new ElevenLabsApi.SpeechRequest.VoiceSettings(0.75f, 0.75f, 0.0f, true);

ElevenLabsTextToSpeechOptions speechOptions = ElevenLabsTextToSpeechOptions.builder()
    .model("eleven_multilingual_v2")
    .voiceId("your_voice_id")
    .voiceSettings(voiceSettings)
    .build();

TextToSpeechPrompt speechPrompt = new TextToSpeechPrompt("This is a test with custom voice settings!", speechOptions);
TextToSpeechResponse response = elevenLabsTextToSpeechModel.call(speechPrompt);

手动配置

将 spring-ai-elevenlabs 依赖添加到项目的 Maven pom.xml 文件中：

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

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

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

请参考依赖管理章节，将 Spring AI BOM 添加到你的构建文件中。

接下来，创建 ElevenLabsTextToSpeechModel 实例：

ElevenLabsApi elevenLabsApi = ElevenLabsApi.builder()
		.apiKey(System.getenv("ELEVEN_LABS_API_KEY"))
		.build();

ElevenLabsTextToSpeechModel elevenLabsTextToSpeechModel = ElevenLabsTextToSpeechModel.builder()
	.elevenLabsApi(elevenLabsApi)
	.defaultOptions(ElevenLabsTextToSpeechOptions.builder()
		.model("eleven_turbo_v2_5")
		.voiceId("your_voice_id") // 示例："9BWtsMINqrJLrRacOk9x"
		.outputFormat("mp3_44100_128")
		.build())
	.build();

// 调用时会使用上述配置的默认选项
TextToSpeechPrompt speechPrompt = new TextToSpeechPrompt("Hello, this is a text-to-speech example.");
TextToSpeechResponse response = elevenLabsTextToSpeechModel.call(speechPrompt);

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

实时音频流式传输

ElevenLabs 语音合成 API 支持通过分块传输编码实现实时音频流式传输，允许音频在完整生成前就开始播放。

ElevenLabsApi elevenLabsApi = ElevenLabsApi.builder()
		.apiKey(System.getenv("ELEVEN_LABS_API_KEY"))
		.build();

ElevenLabsTextToSpeechModel elevenLabsTextToSpeechModel = ElevenLabsTextToSpeechModel.builder()
	.elevenLabsApi(elevenLabsApi)
	.build();

ElevenLabsTextToSpeechOptions streamingOptions = ElevenLabsTextToSpeechOptions.builder()
    .model("eleven_turbo_v2_5")
    .voiceId("your_voice_id")
    .outputFormat("mp3_44100_128")
    .build();

TextToSpeechPrompt speechPrompt = new TextToSpeechPrompt("Today is a wonderful day to build something people love!", streamingOptions);

FluxresponseStream = elevenLabsTextToSpeechModel.stream(speechPrompt);

// 处理音频流，例如播放音频分片
responseStream.subscribe(speechResponse -> {
    byte[] audioChunk = speechResponse.getResult().getOutput();
    // 播放 audioChunk
});

音色 API

ElevenLabs 音色 API 允许你获取可用音色、其配置以及默认音色配置的信息。你可以使用该 API 查询语音合成请求中使用的 voiceId。

使用音色 API 前，需要创建 ElevenLabsVoicesApi 实例：

ElevenLabsVoicesApi voicesApi = ElevenLabsVoicesApi.builder()
        .apiKey(System.getenv("ELEVEN_LABS_API_KEY"))
        .build();

随后可使用以下方法：

getVoices()：获取所有可用音色列表；

getDefaultVoiceSettings()：获取音色默认配置；

getVoiceSettings(String voiceId)：获取指定音色的配置；

getVoice(String voiceId)：获取指定音色的元数据。

示例：

// 获取所有音色
ResponseEntityvoicesResponse = voicesApi.getVoices();
Listvoices = voicesResponse.getBody().voices();

// 获取音色默认配置
ResponseEntitydefaultSettingsResponse = voicesApi.getDefaultVoiceSettings();
ElevenLabsVoicesApi.VoiceSettings defaultSettings = defaultSettingsResponse.getBody();

// 获取指定音色的配置
ResponseEntityvoiceSettingsResponse = voicesApi.getVoiceSettings(voiceId);
ElevenLabsVoicesApi.VoiceSettings voiceSettings = voiceSettingsResponse.getBody();

// 获取指定音色的详情
ResponseEntityvoiceDetailsResponse = voicesApi.getVoice(voiceId);
ElevenLabsVoicesApi.Voice voiceDetails = voiceDetailsResponse.getBody();

示例代码

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

ElevenLabsApiIT.java 测试类提供了使用底层 ElevenLabsApi 的示例。