ElevenLabs 文本转语音（TTS）

引言

ElevenLabs 用深度学习提供听感自然的语音合成软件。它的 AI 音频模型能在 32 种语言上生成逼真、多能且具上下文感知能力的语音、声音和音效。ElevenLabs 文本转语音 API 让用户能以超逼真的 AI 旁白，把任何书、文章、PDF、简报或文本演绎得栩栩如生。

前置条件

创建一个 ElevenLabs 账户并获取 API 密钥。你可以在 ElevenLabs 注册页注册。登录后，你的 API 密钥可在个人资料页找到。
把 spring-ai-elevenlabs 依赖添加到你项目的构建文件。更多信息参见依赖管理一节。

自动配置

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

xml

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

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

groovy

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

TIP

参见依赖管理一节，把 Spring AI BOM 添加到你的构建文件。

语音属性

连接属性

前缀 spring.ai.elevenlabs 用作所有 ElevenLabs 相关配置（连接和 TTS 特定设置）的属性前缀。它定义在 ElevenLabsConnectionProperties 中。

属性	描述	默认值
spring.ai.elevenlabs.base-url	ElevenLabs API 的基础 URL。	https://api.elevenlabs.io
spring.ai.elevenlabs.api-key	你的 ElevenLabs API 密钥。	-

配置属性

NOTE

音频语音自动配置的启用与禁用，现通过以 spring.ai.model.audio.speech 为前缀的顶层属性来配置。

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

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

做出此变更是为了支持配置多个模型。

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

属性	描述	默认值
spring.ai.model.audio.speech	启用音频语音模型	elevenlabs
spring.ai.elevenlabs.tts.model-id	要使用的模型 ID。	eleventurbov2_5
spring.ai.elevenlabs.tts.voice-id	要使用的声音 ID。这是 voice ID，不是声音名。	9BWtsMINqrJLrRacOk9x
spring.ai.elevenlabs.tts.output-format	生成音频的输出格式。见下方输出格式。	mp32205032

NOTE

基础 URL 和 API 密钥也可以通过 spring.ai.elevenlabs.tts.base-url 和 spring.ai.elevenlabs.tts.api-key 专门为 TTS 配置。不过，通常建议为简便起见使用全局的 spring.ai.elevenlabs 前缀，除非你有特定理由为不同的 ElevenLabs 服务使用不同凭据。更具体的 tts 属性会覆盖全局的那些。

TIP

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

.可用的输出格式

枚举值	描述
MP32205032	MP3，22.05 kHz，32 kbps
MP34410032	MP3，44.1 kHz，32 kbps
MP34410064	MP3，44.1 kHz，64 kbps
MP34410096	MP3，44.1 kHz，96 kbps
MP344100128	MP3，44.1 kHz，128 kbps
MP344100192	MP3，44.1 kHz，192 kbps
PCM_8000	PCM，8 kHz
PCM_16000	PCM，16 kHz
PCM_22050	PCM，22.05 kHz
PCM_24000	PCM，24 kHz
PCM_44100	PCM，44.1 kHz
PCM_48000	PCM，48 kHz
ULAW_8000	µ-law，8 kHz
ALAW_8000	A-law，8 kHz
OPUS4800032	Opus，48 kHz，32 kbps
OPUS4800064	Opus，48 kHz，64 kbps
OPUS4800096	Opus，48 kHz，96 kbps
OPUS48000128	Opus，48 kHz，128 kbps
OPUS48000192	Opus，48 kHz，192 kbps

运行时选项

ElevenLabsTextToSpeechOptions 类提供进行文本转语音请求时使用的选项。在启动时，使用由 spring.ai.elevenlabs.tts 指定的选项，但你可以在运行时覆盖它们。以下选项可用：

modelId：要使用的模型 ID。
voiceId：要使用的声音 ID。
outputFormat：生成音频的输出格式。
voiceSettings：一个包含声音设置的对象，如 stability、similarityBoost、style、useSpeakerBoost 和 speed。
enableLogging：一个用于启用或禁用日志的布尔值。
languageCode：输入文本的语言代码（例如英语用 "en"）。
pronunciationDictionaryLocators：一个发音词典定位器列表。
seed：用于随机数生成的种子，以获得可复现性。
previousText：主文本之前的文本，用于多轮对话的上下文。
nextText：主文本之后的文本，用于多轮对话的上下文。
previousRequestIds：对话中先前回合的请求 ID。
nextRequestIds：对话中后续回合的请求 ID。
applyTextNormalization：应用文本规范化（"auto"、"on" 或 "off"）。
applyLanguageTextNormalization：应用语言文本规范化。

例如：

java

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 来定制声音输出。这让你能控制 stability 和 similarity 等属性。

java

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 文件：

xml

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

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

groovy

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

TIP

参见依赖管理一节，把 Spring AI BOM 添加到你的构建文件。

接下来，创建一个 ElevenLabsTextToSpeechModel：

java

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

ElevenLabsTextToSpeechModel elevenLabsTextToSpeechModel = ElevenLabsTextToSpeechModel.builder()
	.elevenLabsApi(elevenLabsApi)
	.options(ElevenLabsTextToSpeechOptions.builder()
		.model("eleven_turbo_v2_5")
		.voiceId("your_voice_id") // e.g. "9BWtsMINqrJLrRacOk9x"
		.outputFormat("mp3_44100_128")
		.build())
	.build();

// The call will use the default options configured above.
TextToSpeechPrompt speechPrompt = new TextToSpeechPrompt("Hello, this is a text-to-speech example.");
TextToSpeechResponse response = elevenLabsTextToSpeechModel.call(speechPrompt);

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

流式实时音频

ElevenLabs 语音 API 通过块传输编码支持实时音频流式。这让音频播放能在整个音频文件生成完毕之前就开始。

java

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

Flux<TextToSpeechResponse> responseStream = elevenLabsTextToSpeechModel.stream(speechPrompt);

// Process the stream, e.g., play the audio chunks
responseStream.subscribe(speechResponse -> {
    byte[] audioChunk = speechResponse.getResult().getOutput();
    // Play the audioChunk
});

声音 API

ElevenLabs 声音 API 让你能获取关于可用声音、它们的设置以及默认声音设置的信息。你可以用这个 API 来发现你在语音请求中要使用的 voiceId。

要使用声音 API，你需要创建一个 ElevenLabsVoicesApi 的实例：

java

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

随后你可以使用以下方法：

getVoices()：检索所有可用声音的列表。
getDefaultVoiceSettings()：获取声音的默认设置。
getVoiceSettings(String voiceId)：返回某个特定声音的设置。
getVoice(String voiceId)：返回某个特定声音的元数据。

示例：

java

// Get all voices
ResponseEntity<ElevenLabsVoicesApi.Voices> voicesResponse = voicesApi.getVoices();
List<ElevenLabsVoicesApi.Voice> voices = voicesResponse.getBody().voices();

// Get default voice settings
ResponseEntity<ElevenLabsVoicesApi.VoiceSettings> defaultSettingsResponse = voicesApi.getDefaultVoiceSettings();
ElevenLabsVoicesApi.VoiceSettings defaultSettings = defaultSettingsResponse.getBody();

// Get settings for a specific voice
ResponseEntity<ElevenLabsVoicesApi.VoiceSettings> voiceSettingsResponse = voicesApi.getVoiceSettings(voiceId);
ElevenLabsVoicesApi.VoiceSettings voiceSettings = voiceSettingsResponse.getBody();

// Get details for a specific voice
ResponseEntity<ElevenLabsVoicesApi.Voice> voiceDetailsResponse = voicesApi.getVoice(voiceId);
ElevenLabsVoicesApi.Voice voiceDetails = voiceDetailsResponse.getBody();

示例代码

ElevenLabsTextToSpeechModelIT.java 测试提供了一些关于如何使用该库的通用示例。
ElevenLabsApiIT.java 测试提供了使用底层 ElevenLabsApi 的示例。

Chat Client API

顾问（Advisor）API

结构化输出

模型

聊天模型 API

嵌入模型 API

Amazon Bedrock

VertexAI

图像模型 API

音频模型

转录 API

文本转语音（TTS）API

审核模型

工具调用

Model Context Protocol (MCP)

MCP 服务端 Boot Starter

MCP 注解

检索增强生成

向量数据库

ElevenLabs 文本转语音（TTS）

引言

前置条件

自动配置

语音属性

连接属性

配置属性

运行时选项

使用声音设置

手动配置

流式实时音频

声音 API

示例代码

友情链接