企业官网建设流程全解析

AIRI 集成 Google Gemini TTS：语音合成提供者配置、模型语音选择与实现原理

【免费下载链接】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-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi

Google Gemini Audio 语音合成是 AIRI 中一个直接复用 Gemini 凭据的文本转语音（TTS）提供者，适合已经为 AIRI 配置过 Gemini、希望同一服务商同时提供语音输出能力的用户。本文基于仓库中该功能的官方配置文档与其源码实现，完整讲解从 API Key 申请、提供者配置、模型与语音选择，到让 AIRI 普通响应真正使用 Gemini 发声的全流程，并深入剖析其底层 API 调用与音频处理原理。

为什么选择 Google Gemini 作为语音合成提供者

AIRI 内置了多个语音合成提供者（如 ElevenLabs、Microsoft Speech、MiniMax、本地 Kokoro 等），其中 Google Gemini（google-gemini-audio-speech）走的是「复用既有凭据」的思路：如果你已经在 AIRI 中配置过 Google Gemini 并持有 API Key，就无需再申请一套独立的 TTS 服务凭据，直接在同一服务商的生态内获得音频输出能力。该提供者被注册为text-to-speech与tts两类任务，可从提供者注册表直接检索到。

第一步：申请 Gemini API Key

1. 登录 Google AI Studio（aistudio.google.com），进入 API Key 管理页面创建新的 API Key。
2. 确认你的账户/区域可以访问支持音频输出的 Gemini 模型（Gemini 系列中带-tts后缀的模型）。
3. 复制生成的 Key 并妥善保管，后续配置中需要粘贴到 AIRI。

安全警告：Gemini API Key 是敏感凭据，不要将其提交进版本库、不要出现在截图或日志中、不要与任何人共享。它直接决定了第三方能否以你的身份消耗 Gemini 配额。

第二步：在 AIRI 中配置提供者

配置入口

打开设置 → 提供者 → 语音合成 → Google Gemini（对应源码页面 google-gemini-audio-speech.vue），在表单中填写：

Base URL 的约定

从 google-gemini-audio-speech/index.ts 可以看到，配置 schema 中apiKey必填、baseUrl可选且有默认值。除非你正在使用企业网关或兼容代理（例如需要统一出口、审计或自建中转的场景），否则应保持界面上的默认 Base URL 不变。

底层对 Base URL 做了归一化处理：normalizeBaseUrl会先去除首尾空白，再保证以/结尾（value.endsWith('/') ? value : \${value}/``），因此无论是带尾斜杠还是不带尾斜杠的地址都能被正确拼接。

第三步：模型与音色选择

配置完成后，提供者会通过listModels与listVoices两个扩展方法向设置界面暴露可选项，页面在挂载时会调用loadModelsForConfiguredProviders、fetchModelsForProvider以及speechStore.loadVoicesForProvider(providerId)拉取这些数据（见 google-gemini-audio-speech.vue）。语音列表最终被写入availableVoices[providerId]（见 speech.ts），供播放场与语音选择器使用。

支持的 TTS 模型

源码中注册了以下三个模型（index.ts）：

• gemini-2.5-flash-preview-tts（默认）
• gemini-2.5-pro-preview-tts
• gemini-3.1-flash-tts-preview

支持的音色

提供者内置了 30 种预置音色，每种都附带风格描述，可在界面中直接按需挑选：

Temperature 参数

在提供者设置的进阶区域中，temperature用于控制语音生成的随机性：取值越低语音越稳定可预测，越高越富有表现力（见 google-gemini-audio-speech.vue）。它仅在调用时显式传入才生效，未设置时不会写入请求体。

第四步：验证配置是否可用

1. 在提供者设置页选择模型与一个可用音色。
2. 使用同页的Playground（播放场），输入一段短文本（页面默认文本为 "Hello! This is a test of the Google Gemini Speech."）并触发合成，确认能正常播放音频。

验证逻辑由validateConfig校验器提供：只要apiKey非空即为「有效」，对应错误信息为API Key is required.（见 index.ts）。若校验失败，设置页会显示错误提示，并提供「强制继续」的选项。此外，provider-definitions.test.ts 中的测试用例会遍历全部已注册提供者并断言getDefinedProvider('google-gemini-audio-speech')有定义，保证该提供者在每次构建中都能被正确注册。

第五步：让 AIRI 的普通响应使用 Gemini 发声

仅完成 Playground 测试并不会让日常对话自动使用 Gemini 发声。要让 AIRI 在普通响应中调用该提供者，还需要：

1. 打开设置 → 模块 → 语音合成。
2. 将语音合成提供者切换为Google Gemini，并选择前面验证过的音频模型与音色。

这一步将 Gemini 从「仅在设置页可测试」提升为「模块级默认 TTS」，此后 AIRI 的普通文本响应才会经由该提供者合成语音。

底层实现原理：一次 Gemini TTS 请求的全过程

该提供者的核心实现位于 google-gemini-audio-speech/index.ts，它没有使用 OpenAI 兼容的/audio/speech接口，而是直接对接 Gemini 的generateContent端点，调用链如下：

1. 构造请求：向{baseUrl}models/{model}:generateContent发送POST请求，认证头为x-goog-api-key: {apiKey}。
2. 请求体：
   • contents: [{ parts: [{ text: input }] }]承载待合成文本；
   • generationConfig.responseModalities: ['AUDIO']声明只返回音频；
   • speechConfig.voiceConfig.prebuiltVoiceConfig.voiceName指定音色，缺省时使用Kore；
   • 可选携带temperature。
3. 响应解析：从candidates[0].content.parts中找出携带inlineData的片段，取其inlineData.data（Base64 编码的 PCM16 原始音频）。
4. 音频转换：decodeBase64将 Base64 还原为字节数组，再经toWavFromPCM16(audio, 24000)（来自@proj-airi/audio/encoding）封装为24 kHz 采样率的 WAV流，最终以audio/wav响应返回给上层语音管道。

也就是说，Gemini 返回的是未封装的裸 PCM 数据，AIRI 负责在其上补充 WAV 头、统一音频格式，从而与后端既有的音频播放链路无缝对接。理解这一点有助于排查「请求成功但无声音」类问题——声音能否播放，最终取决于所选模型是否真的在AUDIO模态下返回了内联音频数据。

故障排查

如果确认以上均无误，可在设置页重新触发一次 Playground 合成，观察播放结果与错误提示，通常能快速定位是凭据问题、区域问题还是模型能力问题。

【免费下载链接】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-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi