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

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

ElevenLabs 文本转语音 (TTS)

Deepseek 3.2 中英对照 ElevenLabs ElevenLabs Text-to-Speech (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.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 文本转语音客户端的属性前缀，具体定义在 ElevenLabsSpeechProperties 中。

属性	描述	默认值
spring.ai.model.audio.speech	启用音频语音模型	elevenlabs
spring.ai.elevenlabs.tts.options.model-id	要使用的模型 ID。	eleven_turbo_v2_5
spring.ai.elevenlabs.tts.options.voice-id	要使用的声音 ID。这是声音 ID，而非声音名称。	9BWtsMINqrJLrRacOk9x
spring.ai.elevenlabs.tts.options.output-format	生成音频的输出格式。请参阅下方的输出格式。	mp3_22050_32

备注

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

提示

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

表 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'
}

提示

请参考依赖管理部分，将 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") // 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支持使用分块传输编码进行实时音频流传输。这使得音频播放可以在整个音频文件生成之前开始。

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来发现语音ID（voiceId），以便在你的语音请求中使用。

要使用 Voices API，您需要创建 ElevenLabsVoicesApi 的实例：

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

接下来，你可以使用以下方法：

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

示例：

// 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​

示例代码​

简介