此版本仍在开发中，尚未被视为稳定版。如需最新的快照版本，请使用 Spring AI 1.1.3！spring-doc.cadn.net.cn

ElevenLabs 文本转语音 (TTS)

< Introduction >

ElevenLabs 提供基于深度学习的自然语音合成软件。其 AI 音频模型可生成逼真、多功能且具备上下文感知能力的语音、音色和音效，支持 32 种语言。ElevenLabs 文本转语音 API 使用户能够通过超逼真的 AI 旁白，让任何书籍、文章、PDF、新闻通讯或文本栩栩如生。spring-doc.cadn.net.cn

前置条件

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

Auto-configuration

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

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

或添加到您的 Gradle build.gradle 构建文件中：spring-doc.cadn.net.cn

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

请参阅依赖管理部分，将Spring AI BOM添加到您的构建文件中。

语音属性

连接属性

前缀 spring.ai.elevenlabs 用作与 ElevenLabs 相关的**所有**配置（包括连接设置和 TTS 特定设置）的属性前缀。此定义位于 ElevenLabsConnectionProperties 中。spring-doc.cadn.net.cn

<property> </property>spring-doc.cadn.net.cn

<description> </description>spring-doc.cadn.net.cn

默认spring-doc.cadn.net.cn

spring.ai.elevenlabs.base-urlspring-doc.cadn.net.cn

ElevenLabs API 的基础 URL。spring-doc.cadn.net.cn

api.elevenlabs.io spring-doc.cadn.net.cn

spring.ai.elevenlabs.api-keyspring-doc.cadn.net.cn

您的 ElevenLabs API 密钥。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

配置属性

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

要启用，请设置 spring.ai.model.audio.speech=elevenlabs（默认已启用）spring-doc.cadn.net.cn

要禁用，请设置 spring.ai.model.audio.speech=none（或任何不等于 elevenlabs 的值）spring-doc.cadn.net.cn

此更改是为了允许配置多个模型。spring-doc.cadn.net.cn

前缀 spring.ai.elevenlabs.tts 用作属性前缀，专门用于配置 ElevenLabs 文本转语音客户端。此定义位于 ElevenLabsSpeechProperties 中。spring-doc.cadn.net.cn

<property> </property>	<description> </description>	默认
spring.ai.model.audio.speechspring-doc.cadn.net.cn	启用音频语音模型spring-doc.cadn.net.cn	ElevenLabsspring-doc.cadn.net.cn
spring.ai.elevenlabs.tts.options.model-idspring-doc.cadn.net.cn	要使用的模型 ID。spring-doc.cadn.net.cn	eleven_turbo_v2_5spring-doc.cadn.net.cn
spring.ai.elevenlabs.tts.options.voice-idspring-doc.cadn.net.cn	要使用的语音 ID。这是语音 ID，而非语音名称。spring-doc.cadn.net.cn	9BWtsMINqrJLrRacOk9xspring-doc.cadn.net.cn
spring.ai.elevenlabs.tts.options.output-formatspring-doc.cadn.net.cn	生成音频的输出格式。请参阅下方的输出格式。spring-doc.cadn.net.cn	mp3_22050_32spring-doc.cadn.net.cn

默认

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

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

ElevenLabsspring-doc.cadn.net.cn

spring.ai.elevenlabs.tts.options.model-idspring-doc.cadn.net.cn

要使用的模型 ID。spring-doc.cadn.net.cn

eleven_turbo_v2_5spring-doc.cadn.net.cn

spring.ai.elevenlabs.tts.options.voice-idspring-doc.cadn.net.cn

要使用的语音 ID。这是语音 ID，而非语音名称。spring-doc.cadn.net.cn

9BWtsMINqrJLrRacOk9xspring-doc.cadn.net.cn

spring.ai.elevenlabs.tts.options.output-formatspring-doc.cadn.net.cn

生成音频的输出格式。请参阅下方的输出格式。spring-doc.cadn.net.cn

mp3_22050_32spring-doc.cadn.net.cn

基础 URL 和 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. 可用的输出格式
枚举值spring-doc.cadn.net.cn	<description> </description>spring-doc.cadn.net.cn
MP3_22050_32spring-doc.cadn.net.cn	MP3，22.05 kHz，32 kbpsspring-doc.cadn.net.cn
MP3_44100_32spring-doc.cadn.net.cn	MP3，44.1 kHz，32 kbpsspring-doc.cadn.net.cn
MP3_44100_64spring-doc.cadn.net.cn	MP3，44.1 kHz，64 kbpsspring-doc.cadn.net.cn
MP3_44100_96spring-doc.cadn.net.cn	MP3，44.1 kHz，96 kbpsspring-doc.cadn.net.cn
MP3_44100_128spring-doc.cadn.net.cn	MP3，44.1 kHz，128 kbpsspring-doc.cadn.net.cn
MP3_44100_192spring-doc.cadn.net.cn	MP3，44.1 kHz，192 kbpsspring-doc.cadn.net.cn
PCM_8000spring-doc.cadn.net.cn	PCM，8 kHzspring-doc.cadn.net.cn
PCM_16000spring-doc.cadn.net.cn	PCM，16 kHzspring-doc.cadn.net.cn
PCM_22050spring-doc.cadn.net.cn	脉冲编码调制，22.05 kHzspring-doc.cadn.net.cn
PCM_24000spring-doc.cadn.net.cn	PCM，24 kHzspring-doc.cadn.net.cn
PCM_44100spring-doc.cadn.net.cn	PCM，44.1 kHzspring-doc.cadn.net.cn
PCM_48000spring-doc.cadn.net.cn	PCM，48 kHzspring-doc.cadn.net.cn
ULAW_8000spring-doc.cadn.net.cn	µ 律，8 kHzspring-doc.cadn.net.cn
ALAW_8000spring-doc.cadn.net.cn	A 律，8 kHzspring-doc.cadn.net.cn
OPUS_48000_32spring-doc.cadn.net.cn	Opus，48 kHz，32 kbpsspring-doc.cadn.net.cn
OPUS_48000_64spring-doc.cadn.net.cn	Opus，48 kHz，64 kbpsspring-doc.cadn.net.cn
OPUS_48000_96spring-doc.cadn.net.cn	Opus，48 kHz，96 kbpsspring-doc.cadn.net.cn
OPUS_48000_128spring-doc.cadn.net.cn	Opus，48 kHz，128 kbpsspring-doc.cadn.net.cn
OPUS_48000_192spring-doc.cadn.net.cn	Opus，48 kHz，192 kbpsspring-doc.cadn.net.cn

运行时选项

ElevenLabsTextToSpeechOptions 类提供了在发起文本转语音请求时可用的选项。启动时，会使用由 spring.ai.elevenlabs.tts 指定的选项，但您可以在运行时覆盖这些选项。以下是可用的选项：spring-doc.cadn.net.cn

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

例如：spring-doc.cadn.net.cn

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 来自定义语音输出。这使您能够控制稳定性和相似度等属性。spring-doc.cadn.net.cn

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

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

或添加到您的 Gradle build.gradle 构建文件中：spring-doc.cadn.net.cn

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

请参阅依赖管理部分，将Spring AI BOM添加到您的构建文件中。

接下来，创建一个 ElevenLabsTextToSpeechModel：spring-doc.cadn.net.cn

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") // 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 支持使用分块传输编码进行实时音频流传输。这使得在生成完整音频文件之前即可开始播放音频。spring-doc.cadn.net.cn

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 Voices API 允许您检索有关可用语音、其设置以及默认语音设置的信息。您可以使用此 API 发现要在语音请求中使用的 `voiceId`。spring-doc.cadn.net.cn

要使用 Voices API，您需要创建 ElevenLabsVoicesApi 的实例：spring-doc.cadn.net.cn

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

然后您可以使用以下方法：spring-doc.cadn.net.cn

getVoices(): 获取所有可用语音的列表。spring-doc.cadn.net.cn
getDefaultVoiceSettings(): 获取语音的默认设置。spring-doc.cadn.net.cn
getVoiceSettings(String voiceId)：返回特定语音的设置。spring-doc.cadn.net.cn
getVoice(String voiceId): 返回有关特定语音的元数据。spring-doc.cadn.net.cn

示例：spring-doc.cadn.net.cn

// 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 测试提供了一些如何使用该库的通用示例。spring-doc.cadn.net.cn
ElevenLabsApiIT.java 测试提供了使用底层 ElevenLabsApi 的示例。spring-doc.cadn.net.cn