企业官网建设流程全解析

• 人工智能
• AI Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手

本篇指南以 docs/content/zh-Hans/docs/manual/config/providers/speech/elevenlabs.md 为主体，结合仓库中 provider 注册与设置页面的源码实现展开。读完你将掌握在 AIRI 中接入 ElevenLabs TTS 的完整流程：获取并安全存放 API Key、填写服务商配置、验证连通性、选择模型与音色、调试发音参数，并了解 AIRI 为 ElevenLabs 内置的模型清单、音色目录加载机制与 SSML 能力，从而让 AIRI 的回复以你账户中真实存在的音色发声。

为什么选择 ElevenLabs

在 AIRI 的语音合成（TTS）服务商体系中，ElevenLabs 的核心价值在于：它直接对接你的 ElevenLabs 账户音色库。如果你已经拥有自定义音色，或者希望直接使用 ElevenLabs 预置的 Aria、Bill 等官方声线，在 AIRI 中完成 API Key 配置后，即可在设置界面直接浏览、搜索并选择可用声音，无需自己维护音色 ID 列表。

从源码分类看，ElevenLabs 属于付费云服务（pricing: 'paid'、deployment: 'cloud'），其注册定义位于 packages/provider-inference/src/providers/cloud/elevenlabs/index.ts，任务类型为text-to-speech，并在 packages/stage-ui/src/libs/providers/attributes.ts 中被标记为付费云服务商。

第一步：获取 API Key

1. 登录 ElevenLabs 账户，进入控制台的API Keys 设置页面，点击创建新的 API Key。
2. 为密钥设置便于识别的名称，并根据实际用量设置适当的使用限制（如每日额度上限），以便在密钥泄露或异常消耗时能及时感知。
3. 复制密钥并妥善保存（推荐放入密码管理器）。

⚠️API Key 安全不要把 API Key 提交到仓库、截图分享或发送给他人。若怀疑泄露，请立即在 ElevenLabs 控制台撤销该密钥并重新创建，同时在 AIRI 中更新配置。

第二步：在 AIRI 中配置服务商

1. 打开设置 → 服务商 → 语音合成，在服务商列表中选择ElevenLabs（界面中的展示名来自中文语言包，见 packages/i18n/src/locales/zh-Hans/settings.yaml）。
2. 将 API Key 粘贴到API Key（基础设置）输入框中。该字段在配置表单中类型为password，不会明文展示。
3. 保留界面默认的 Base URL；只有当你使用自己的 ElevenLabs 兼容网关时才需要修改。

关于这两个字段，源码中的配置 schema 给出了明确的规则（packages/provider-inference/src/providers/cloud/elevenlabs/index.ts）：

• apiKey：必填字符串，创建 provider 实例时会先trim()去除首尾空白再传入；
• baseUrl：默认值为https://unspeech.hyp3r.link/v1/（一个由 unspeech 库提供的 OpenAI 兼容代理端点，AIRI 通过它统一访问各家语音服务）；
• voiceSettings：包含similarityBoost（默认 0.75）与stability（默认 0.5）两个数值参数。

配置校验器（createElevenLabsValidators）会在保存时执行以下检查：

• apiKey为空 → 报错 "API key is required."；
• baseUrl为空 → 报错 "Base URL is required."；
• baseUrl不是合法绝对 URL（需带http://或https://协议头）→ 报错 "Base URL is not absolute..."；
• baseUrl末尾缺少/→ 报错 "Base URL must end with a trailing slash (/)."。

只有当apiKey与baseUrl都非空时才会触发自动校验（validationRequiredWhen），这也对应设置界面中 "Ping API" 按钮的启用条件。

第三步：验证配置

1. Ping API：点击该按钮测试网络是否连通、API Key 是否填写正确。这一操作实质上是调用上述配置校验器与 provider 初始化逻辑，只有校验通过才会继续发起请求。
2. 选择模型和音色：测试成功后，进入设置 → 发声，选择模型与想使用的声音。模型与音色列表由 AIRI 自动拉取（详见下文"内置模型清单"与"音色目录"两节）。
3. 输入一段短文本并点击试听；能正常播放语音即表示配置成功。若未填写 API Key，试听按钮会被禁用并提示"需要填写 API Key 才能用哦！"（对应 packages/stage-ui/src/components/scenarios/providers/speech-playground.vue 中的apiKeyConfigured判断）。

值得注意的是，设置页（packages/stage-pages/src/pages/settings/providers/speech/elevenlabs.vue）会在你填写apiKey或baseUrl后的 500ms（防抖）内自动校验配置，并通过loadVoicesForProvider预加载音色目录，无需手动刷新。

内置模型清单：AIRI 为 ElevenLabs 预置的 TTS 模型

AIRI 无需请求 ElevenLabs 的模型列表接口，而是在 packages/provider-inference/src/providers/cloud/elevenlabs/list-models.ts 中内置了一份静态模型清单，通过extraMethods.listModels暴露给设置界面（packages/provider-inference/src/providers/cloud/elevenlabs/index.ts）。主要可用于文本转语音（can_do_text_to_speech: true）的模型如下：

AIRI 在设置页默认选择eleven_multilingual_v2（defaultModel），同时在传统发声设置页的模型下拉框中提供了eleven_monolingual_v1、eleven_multilingual_v1、eleven_multilingual_v2三个快捷选项（见 packages/stage-pages/src/pages/settings/modules/speech.vue）。模型清单中的character_cost_multiplier字段（Multilingual v2 为 1，Turbo/Flash 系列为 0.5）反映了各模型的按字符计费倍率差异，可作为日常使用的成本参考。

测试用例 packages/stage-ui/src/libs/providers/providers/provider-definitions.test.ts 验证了默认baseUrl、voiceSettings默认值以及模型列表均从定义中正确加载，且所有模型都归属于elevenlabs提供方。

音色目录：如何加载、排序与试听

AIRI 通过extraMethods.listVoices实时拉取你的账户音色（packages/provider-inference/src/providers/cloud/elevenlabs/index.ts）：

• 使用unspeech的listVoices调用 ElevenLabs 音色接口；
• 返回的每个音色包含id、name、provider、previewURL（试听音频地址）与languages（支持的语言及代码）；
• 列表做了特殊排序：把官方默认音色（名字含 "Aria" 与 "Bill" 的音色）整体挪到列表末尾，使你的自定义音色排在前面，方便优先选择。

音色目录的加载由 packages/stage-ui/src/stores/modules/speech.ts 中的loadVoicesForProvider/loadVoiceCatalog流程驱动：设置页通过VoiceCardManySelect组件展示音色卡片，支持搜索、播放试听音频（previewURL）、手动输入自定义音色 ID，并在选择后通过trackVoiceSelected记录分析事件。试听面板（SpeechPlayground）还提供语言徽标展示，方便按语言过滤官方音色。

ElevenLabs 特有的发音参数调优

与通用服务商不同，ElevenLabs 的设置页提供了一套专属音色参数（对应中文语言包中的字段说明，见 packages/i18n/src/locales/zh-Hans/settings.yaml），其默认值定义在 packages/stage-pages/src/pages/settings/providers/speech/elevenlabs.vue：

这些参数通过watch实时写入 provider 配置（providerConfig.style、providerConfig.stability等），并在生成语音时随provider.speech(model, {...providerConfig, ...defaultVoiceSettings})一并提交给服务端。注意：源码中的配置 schema 仅固化similarityBoost与stability两个默认值，而style、useSpeakerBoost等参数由设置页补齐默认值后透传。

SSML 支持

从 packages/stage-ui/src/stores/modules/speech.ts 可以看出，elevenlabs属于 AIRI 支持 SSML（语音合成标记语言）的服务商之一（同列还有microsoft-speech、azure-speech）。这意味着：

• 你可以在设置 → 发声中开启 "Enable SSML"，随后在试听面板输入原始 SSML 文本（例如用<prosody pitch="+10%" rate="1.2">精细控制语调与语速）进行测试；
• 对话生成时，若开启 SSML，AIRI 会自动调用generateSSML将普通文本包装为<speak><voice name="...">结构的 SSML（若设置了 pitch/speed/volume 还会生成<prosody>节点，见 packages/stage-ui/src/stores/modules/speech.ts），并将pitch参数编码为带正负号的百分比形式（如+10%/-5%）。

排查与常见问题

• Ping API 失败：依次检查 API Key 是否复制完整且未含空格、Base URL 是否为默认值或合法网关地址（必须带协议头并以/结尾）、账户余额与额度是否充足、网络能否访问外网。
• 能列出模型但没有声音：确认设置 → 发声中已选择有效的模型与音色，并检查该模型是否支持所选音色（不同模型支持的语言范围不同，可参考上文模型表格）。
• 试听按钮置灰：提示"需要填写 API Key 才能用哦！"时，说明 provider 配置尚未通过校验，请回到服务商设置页确认 API Key 已保存。
• 音色列表为空：确认账户中存在可用音色；配置变更后 AIRI 会自动重新加载音色目录（500ms 防抖），也可通过切换模型触发刷新。

相关源码路径速查

• Provider 注册与配置校验：packages/provider-inference/src/providers/cloud/elevenlabs/index.ts
• 内置模型清单：packages/provider-inference/src/providers/cloud/elevenlabs/list-models.ts
• 设置页（参数面板 + 试听面板）：packages/stage-pages/src/pages/settings/providers/speech/elevenlabs.vue
• 发声设置模块：packages/stage-pages/src/pages/settings/modules/speech.vue
• 语音生成与 SSML 管线：packages/stage-ui/src/stores/modules/speech.ts
• 试听面板组件：packages/stage-ui/src/components/scenarios/providers/speech-playground.vue
• 覆盖测试：packages/stage-ui/src/libs/providers/providers/provider-definitions.test.ts
• 中文界面文案：packages/i18n/src/locales/zh-Hans/settings.yaml

至此，从密钥获取、服务商配置、连通性验证，到模型选择、音色加载与发音参数调优，你已掌握在 AIRI 中启用 ElevenLabs TTS 的全链路方法。完成配置后，AIRI 的每次回复都会经由你选定的模型与音色实时合成语音输出。

• 人工智能
• AI Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手