AIRI 接入火山引擎语音合成TTS实战指南App ID / API Key 配置、音色验证与发声启用【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi火山引擎语音合成TTS是 AIRI 支持的云端语音合成服务来源之一适合已经在该平台创建了语音应用、管理了音色资源的用户直接复用。本文基于仓库中的官方配置文档volcengine.md完整梳理从控制台准备凭据、在 AIRI 中填写配置、通过 Ping API 验证到最终在“发声”模块启用音色并试听的完整流程同时结合provider-inference与stage-ui的源码讲清每个配置项在底层是如何被校验、加载音色与合成语音的。读完本文你将能独立完成火山引擎 TTS 在 AIRI 中的接入与排障。为什么选择火山引擎作为语音来源火山引擎是字节跳动旗下的云服务平台其语音合成服务提供大量中英文音色与多语言能力。AIRI 之所以把火山引擎作为可选的 TTS 服务来源核心场景是配置复用如果你已经在火山引擎控制台创建过语音应用、并针对场景挑选好了音色那么只需在 AIRI 中填写同一套应用凭据即可把整套音色资源迁移到 AIRI 的说话模块中无需在多个平台重复管理密钥与音色。从仓库的服务来源注册表可以看到火山引擎被定义为tasks: [text-to-speech]的云端服务来源见 packages/provider-inference/src/providers/cloud/unspeech/index.ts与 Deepgram、Microsoft Speech、阿里百炼等并列属于“语音文本转语音模型服务来源”分类中文界面中的展示名即为“火山引擎”见 packages/i18n/src/locales/zh-Hans/settings.yaml。第一步在火山引擎控制台准备应用凭据接入前需要先在火山引擎侧准备两项凭据二者必须来自同一个账户下的同一个语音应用App ID登录火山引擎控制台创建或打开已有的语音应用后在应用详情页复制该应用的 App ID。它是火山引擎语音服务用来区分应用实例的标识。API Key在同一个应用的密钥管理区域创建对应的 API Key。API Key 用于接口调用的身份鉴权对应 AIRI 界面中的 “API 密钥” 字段。安全提醒不要把 API Key 或 App ID 凭据公开例如提交到公开仓库、截图分享。一旦怀疑泄露应第一时间在火山引擎控制台更换密钥并同步更新 AIRI 中的配置。这也是仓库多语言文案中反复强调密钥授权语义的原因API 密钥用于授权此服务来源的请求见 packages/i18n/src/locales/zh-Hans/settings.yaml。第二步在 AIRI 中配置火山引擎服务来源完成凭据准备后在 AIRI 中按以下路径完成配置打开设置 → 服务商 → 语音合成在服务来源列表中找到并进入火山引擎对应仓库中的路由页面 volcengine.vueprovider id 为volcengine。填写API Key必填与App ID必填火山引擎独有字段。Base URL保持界面默认值即可除非你使用了兼容网关如自建的 unspeech 兼容代理才需要修改。配置项逐一说明火山引擎服务来源的完整配置项由源码中的 Zod schema 定义见 packages/provider-inference/src/providers/cloud/unspeech/index.ts配置项类型是否必填说明apiKeystring是火山引擎应用的 API Key界面中以密码形式展示与输入baseUrlstring是有默认值服务网关地址默认https://unspeech.hyp3r.link/v1/用于连接 unspeech 兼容网关使用自建兼容网关时需以/结尾的绝对 URLapp.appIdstring是火山引擎语音应用的 App ID是该服务来源区别于其他 unspeech 系提供商的独有字段从源码可见火山引擎复用了 unspeech 的统一配置骨架unspeechConfigSchema只额外扩展了app.appId字段volcengineSpeechConfigSchema unspeechConfigSchema.extend({ app: z.object({ appId: z.string() }) })。因此在界面中除了所有 unspeech 系提供商都有的API 密钥与Base URL火山引擎还单独渲染了一个必填的App ID输入框见 volcengine.vue其界面文案“可在控制台获取的 App ID”与源码中的 schema 一一对应。附加参数语速、音高与响度进入火山引擎配置页的“声音配置”区可以调节合成参数。源码中火山引擎页面提供了语速speedRatio滑条取值范围0.5 ~ 2.0、步进0.01默认1.0见 volcengine.vue。该值会写入服务来源配置的audio.speedRatio字段合成时作用于语音输出速度。此外通用语音设置还包含音高pitch与响度volume两项见 packages/i18n/src/locales/zh-Hans/settings.yaml音高用于调节合成语音的尖锐或低沉程度响度调节输出的音量大小。这些参数与语速一起可以在不更换音色的前提下微调发声效果。高级能力SSML 输入配置页的试听区域还支持自定义 SSML启用“选用自定义 SSML”开关后可以输入原始 SSML 文本如加入break停顿、强调重音等标记代替纯文本进行合成见 packages/i18n/src/locales/zh-Hans/settings.yaml适合需要精细控制合成节奏与语调的场景。第三步验证配置并启用发声配置填写完成后按以下顺序验证与启用Ping API验证配置点击验证按钮AIRI 会发起一次配置校验。底层会依次检查API Key 是否已填写、Base URL 是否填写且为带协议http:///https://的绝对地址、URL 是否以/结尾以及火山引擎特有的 App ID 是否已填写见 packages/provider-inference/src/providers/cloud/unspeech/index.ts。校验通过即代表网络连通、凭据格式正确。源码中该校验器被标记为requireAppId true任何一项缺失都会导致验证失败并给出明确错误提示。选择模型和音色测试成功后进入配置页的声音选择区域。火山引擎当前注册的模型为v1listModels返回[{ id: v1, provider: volcano-engine }]见 unspeech/index.ts模型与声线均在界面中通过下拉选择。选择完成后到设置 → 发声中确认已启用该语音来源并为角色卡指定“声音 / 模型”与“声音 / 声线”角色卡的speech_model字段即为此用途见 packages/i18n/src/locales/zh-Hans/settings.yaml。输入短文本试听在试听Playground区域输入一段短文本并点击播放确认能正常生成并播放语音。试听组件会调用服务来源的speech方法实时合成并把返回的音频数据转为 Blob 后播放见 speech-playground.vue页面加载时也会自动校验配置并拉取该来源的可用音色目录loadVoicesForProvider见 packages/stage-ui/src/stores/modules/speech.ts。音色目录的加载机制火山引擎的音色不是硬编码在仓库中的而是通过 unspeech 网关实时拉取服务来源定义中的listVoices会调用createUnVolcengine创建 provider 实例再经由listVoices统一接口获取音色列表最终映射为包含id、name、previewURL试听链接、languages支持语言、gender音色性别等信息的VoiceInfo结构见 unspeech/index.ts。这意味着只要你配置的火山引擎应用开通了新的音色重新加载后即可在 AIRI 中直接选用无需升级软件。常见问题排查如果配置或试听环节出现问题按以下顺序排查验证Ping失败优先核对App ID 与 API Key 是否来自同一个火山引擎语音应用。这两项是绑定关系混用不同应用的凭据会导致鉴权失败。其次是检查 Base URL若已修改需确保是带http://或https://协议的绝对地址并且以/结尾源码校验器会对此给出“Base URL must end with a trailing slash”类提示。验证通过但没有声音确认该火山引擎应用已开通语音合成服务且当前 AIRI 中已选择音色模型v1下至少选中一个声线。另外检查“发声”模块中该语音来源是否处于启用状态以及角色卡是否绑定了对应的“声音 / 模型”与“声音 / 声线”。音色列表为空确认网络可访问默认的 unspeech 网关地址或你的兼容网关并检查配置页加载音色时是否出现报错配置保存后如果服务来源的 API Key、App ID 或 Base URL 发生变化页面会自动重新校验并刷新音色目录。与 AIRI 其他语音能力的衔接火山引擎接入后它与 AIRI 语音体系的其余部分协同工作发声模块作为语音合成的总开关见 packages/i18n/src/locales/zh-Hans/settings.yaml统一管理所有 TTS 服务来源的启用状态角色卡通过“语音 / 提供商 → 声音 / 模型 → 声音 / 声线”三级配置把具体音色绑定到每个角色见 packages/i18n/src/locales/zh-Hans/settings.yaml。对于已在火山引擎沉淀了音色资产、又希望让 AIRI 角色开口说话的用户这是一条成本最低的接入路径——只需完成本文三步配置即可让 AIRI 用火山引擎的音色完成实时语音输出。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
