版本：2.0.1

本站内所有文档均为中英对照文档，点击中文可以显示英文。此提醒连续关闭5次后，将不再显示。

文档内容来源于 spring.io，由 springdoc.tech 翻译，版权归属于 SPRING.IO (Broadcom. Inc)。可供个人学习、研究，未经许可，不得进行转载或用于商业行为。

ElevenLabs 文本转语音（TTS）

QWen 3.8 中英对照 ElevenLabs ElevenLabs Text-to-Speech (TTS)

介绍

ElevenLabs 提供基于深度学习的自然语音合成软件。其 AI 音频模型可生成逼真、多用途且具备上下文感知能力的语音、声音和音效，支持 32 种语言。ElevenLabs 文本转语音 API 让用户能够将任何书籍、文章、PDF、通讯或文本通过超逼真的 AI 配音“活化”呈现。

前提条件

创建一个 ElevenLabs 账号并获取 API 密钥。您可以在 ElevenLabs 注册页面进行注册。登录后，您可以在个人资料页面找到您的 API 密钥。
将 spring-ai-elevenlabs 依赖项添加到项目的构建文件中。更多信息，请参阅 Dependency Management 部分。

自动配置

Spring AI 为 ElevenLabs Text-to-Speech Client 提供了 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.elevenlabs.base-url	ElevenLabs API 的基础 URL。	api.elevenlabs.io
spring.ai.elevenlabs.api-key	您的 ElevenLabs API 密钥。	-

配置属性

备注

启用和禁用语音自动配置现通过具有前缀 spring.ai.model.audio.speech 的顶层属性进行配置。

启用时，请设置 spring.ai.model.audio.speech=elevenlabs（默认已启用）

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

进行此更改是为了允许配置多个模型。

前缀 spring.ai.elevenlabs.tts 用作配置 ElevenLabs Text-to-Speech 客户端的属性前缀。该配置在 ElevenLabsSpeechProperties 中定义。

Property	Description	Default
spring.ai.model.audio.speech	启用音频语音模型	elevenlabs
spring.ai.elevenlabs.tts.model-id	要使用的模型 ID。	eleven_turbo_v2_5
spring.ai.elevenlabs.tts.voice-id	要使用的音色 ID。这是音色 ID，不是音色名称。	9BWtsMINqrJLrRacOk9x
spring.ai.elevenlabs.tts.output-format	生成音频的输出格式。详见下文 Output Formats。	mp3_22050_32

备注

也可以使用 spring.ai.elevenlabs.tts.base-url 和 spring.ai.elevenlabs.tts.api-key 专门为 TTS 配置基础 URL 和 API 密钥。不过，除非您有特定原因需要为不同的 ElevenLabs 服务使用不同的凭证，否则一般建议使用全局的 spring.ai.elevenlabs 前缀以保持简洁。更具体的 tts 属性将覆盖全局配置。

提示

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

表 1. 可用的输出格式

枚举值	描述
MP3_22050_32	MP3, 22.05 kHz, 32 kbps
MP3_44100_32	MP3, 44.1 kHz, 32 kbps
MP3_44100_64	MP3, 44.1 kHz, 64 kbps
MP3_44100_96	MP3, 44.1 kHz, 96 kbps
MP3_44100_128	MP3, 44.1 kHz, 128 kbps
MP3_44100_192	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
OPUS_48000_32	Opus, 48 kHz, 32 kbps
OPUS_48000_64	Opus, 48 kHz, 64 kbps
OPUS_48000_96	Opus, 48 kHz, 96 kbps
OPUS_48000_128	Opus, 48 kHz, 128 kbps
OPUS_48000_192	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：应用语言文本规范化。

例如：

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

手动配置

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

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

或者在你的 Gradle build.gradle 构建文件中添加：

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

提示

请参阅 Dependency Management 章节，将 Spring AI BOM 添加到你的构建文件中。

接下来，创建一个 ElevenLabsTextToSpeechModel：

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 Speech API 支持使用 chunk transfer encoding 实现实时音频流传输。这使得音频播放可以在整个音频文件生成完成之前就开始。

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

Voices API

ElevenLabs 声音 API 允许你获取可用声音的信息、它们的设置以及默认声音设置。你可以使用此 API 来发现用于语音请求的 `voiceId`。

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

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

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

getVoices(): 获取所有可用 Voice 的列表。
getDefaultVoiceSettings(): 获取 Voice 的默认设置。
getVoiceSettings(String voiceId): 返回指定 Voice 的设置。
getVoice(String voiceId): 返回指定 Voice 的元数据。

示例：

// 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 的示例。

介绍​

前提条件​

自动配置​

语音属性​

连接属性​

配置属性​

运行时选项​

使用语音设置​

手动配置​

流式实时音频​

Voices API​

示例代码​

介绍