Lzh on GitHub

简介

ElevenLabs 提供基于深度学习的自然语音合成软件。其 AI 音频模型能够生成逼真、多样且具有上下文感知的语音、声音和音效，支持 32 种语言。ElevenLabs 文本转语音（TTS）API 使用户能够为任何书籍、文章、PDF、新闻简报或文本添加超逼真的 AI 朗读，实现生动呈现。

先决条件

  1. 创建一个 ElevenLabs 账户并获取 API 密钥。您可以在 ElevenLabs 注册页面 进行注册，登录后在个人主页即可查看 API 密钥。
  2. 将 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-urlElevenLabs API 的基础 URLapi.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 的文本转语音客户端（TTS），对应属性在 ElevenLabsSpeechProperties 中定义。

属性描述默认值
spring.ai.model.audio.speech启用音频语音模型elevenlabs
spring.ai.elevenlabs.tts.options.model-id要使用的模型 IDeleven_turbo_v2_5
spring.ai.elevenlabs.tts.options.voice-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 为前缀的属性可以在运行时被覆盖。

可用输出格式（Output Formats）

枚举值描述
MP3_22050_32MP3，22.05 kHz，32 kbps
MP3_44100_32MP3，44.1 kHz，32 kbps
MP3_44100_64MP3，44.1 kHz，64 kbps
MP3_44100_96MP3，44.1 kHz，96 kbps
MP3_44100_128MP3，44.1 kHz，128 kbps
MP3_44100_192MP3，44.1 kHz，192 kbps
PCM_8000PCM，8 kHz
PCM_16000PCM，16 kHz
PCM_22050PCM，22.05 kHz
PCM_24000PCM，24 kHz
PCM_44100PCM，44.1 kHz
PCM_48000PCM，48 kHz
ULAW_8000µ-law，8 kHz
ALAW_8000A-law，8 kHz
OPUS_48000_32Opus，48 kHz，32 kbps
OPUS_48000_64Opus，48 kHz，64 kbps
OPUS_48000_96Opus，48 kHz，96 kbps
OPUS_48000_128Opus，48 kHz，128 kbps
OPUS_48000_192Opus，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 来自定义语音输出，这样可以控制语音的稳定性（stability）、相似度（similarity）等属性。

示例代码：

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 的文本转语音功能，并获取生成的音频字节。

实时音频流

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

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

通过这种方式，你可以在音频生成的同时实时播放，适用于实时朗读或动态内容播报场景。

语音 API

ElevenLabs Voices API 允许你获取可用语音的信息、语音设置以及默认语音设置。你可以使用该 API 来查找在语音请求中使用的 voiceId。

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

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

然后可以使用以下方法：

  • getVoices()：获取所有可用语音的列表。
  • getDefaultVoiceSettings()：获取语音的默认设置。
  • getVoiceSettings(String voiceId)：获取指定语音的设置。
  • getVoice(String voiceId)：获取指定语音的元数据信息。

示例：

// 获取所有语音
ResponseEntity<ElevenLabsVoicesApi.Voices> voicesResponse = voicesApi.getVoices();
List<ElevenLabsVoicesApi.Voice> voices = voicesResponse.getBody().voices();

// 获取默认语音设置
ResponseEntity<ElevenLabsVoicesApi.VoiceSettings> defaultSettingsResponse = voicesApi.getDefaultVoiceSettings();
ElevenLabsVoicesApi.VoiceSettings defaultSettings = defaultSettingsResponse.getBody();

// 获取特定语音的设置
ResponseEntity<ElevenLabsVoicesApi.VoiceSettings> voiceSettingsResponse = voicesApi.getVoiceSettings(voiceId);
ElevenLabsVoicesApi.VoiceSettings voiceSettings = voiceSettingsResponse.getBody();

// 获取特定语音的详细信息
ResponseEntity<ElevenLabsVoicesApi.Voice> voiceDetailsResponse = voicesApi.getVoice(voiceId);
ElevenLabsVoicesApi.Voice voiceDetails = voiceDetailsResponse.getBody();

通过 Voices API，你可以轻松查找和管理 ElevenLabs 可用语音及其配置，从而在文本转语音请求中选择合适的 voiceId。

示例代码