AIRI 接入 Google Gemini TTS 语音合成：配置、音色选择与源码级原理-平芜编程栈

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

本文基于 AIRI 仓库中的 Google Gemini（TTS）配置文档，完整讲解如何在 AIRI 中接入 Google Gemini 音频语音合成能力。读完本文，你将掌握 API Key 的获取与安全存放、AIRI「语音合成」面板中的完整配置流程、模型与音色的选取方法、验证与排错思路，并通过源码理解一次 Gemini TTS 请求从文本到 WAV 音频的完整数据链路。本文适合已在使用 AIRI 并希望为角色赋予「开口说话」能力的开发者，也适合需要把 Gemini TTS 接入自建语音链路的读者。

为什么选择 Google Gemini 做语音合成

Google Gemini 音频语音合成会复用你已经配置的 Gemini 凭据与支持音频输出的模型。正如官方文档所述，如果你已经在 AIRI 中配置了 Google Gemini 对话能力，并希望在同一服务商下直接获得音频输出，那么选择此项可以让凭据管理和计费统一在一条链路上，无需再引入额外的 TTS 供应商。

从仓库源码看，该能力在 AIRI 中被实现为一个独立的语音提供方google-gemini-audio-speech，声明支持的tasks为text-to-speech与tts，注册入口位于 provider-inference 的提供方索引，其完整实现在 google-gemini-audio-speech/index.ts。界面侧对应的设置页为 google-gemini-audio-speech.vue，多语言文案位于 settings.yaml。

第一步：获取 Gemini API Key

打开 Google AI Studio（aistudio.google.com），登录后进入 API Key 页面创建密钥。
确认当前账户所在地区与配额允许调用支持音频输出的 Gemini 模型。
复制生成的 API Key 并妥善保存。

::: warning API Key 安全不要将 Gemini API Key 提交到仓库、截图或发送给他人。它等同于账户凭据，一旦泄露可能产生费用风险。 :::

AIRI 侧的校验逻辑也印证了这一点：提供方配置的validateConfig校验器只做一件事——检查apiKey是否非空，为空时直接返回API Key is required.错误（见 index.ts）。

第二步：在 AIRI 中配置语音合成

进入设置 → 服务商 → 语音合成 → Google Gemini，填写 Gemini API Key。
保留界面默认 Base URL，除非你使用企业网关或兼容代理，才需要替换为自定义网关地址。

配置项与源码中的默认值

设置页背后对应GoogleGeminiSpeechProviderConfig配置结构，包含五个字段（见 google-gemini-audio-speech.vue）：

配置项	默认值	说明
`apiKey`	无（必填）	Gemini API Key
`baseUrl`	`https://generativelanguage.googleapis.com/v1beta/`	Gemini 生成式语言 API 的 v1beta 端点；带尾斜杠规范化处理（见 index.ts）
`model`	`gemini-2.5-flash-preview-tts`	语音合成模型，可下拉选择
`voice`	`Kore`	预置音色名，在「发声」中启用
`temperature`	`1.0`	合成随机性，范围 0～2，步长 0.1

其中temperature由FieldRange滑块控制，取值 0～2、步长 0.1，UI 描述为「控制语音生成的随机性，值越低越稳定可预测，值越高越有表现力」（见 google-gemini-audio-speech.vue）。注意temperature只有在显式传入时才被写入请求体（body.temperature !== undefined时才会附加），因此不设置时服务端使用默认行为。

支持的三款 TTS 模型

AIRI 内置的模型清单在源码中以googleGeminiTtsModels常量定义（见 index.ts），通过listModels暴露给界面下拉框：

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

这些模型均为「Gemini API text-to-speech」类型，能力标记为text-to-speech。选择时请以界面实际列出为准，并确认你的账户可访问对应模型。

30 款内置音色

AIRI 内置了 30 款 Gemini 预置音色及各自的风格描述（见 index.ts），通过listVoices提供给「发声」设置：

音色	风格	音色	风格
Zephyr	Bright	Puck	Upbeat
Charon	Informative	Kore	Firm
Fenrir	Excitable	Leda	Youthful
Orus	Firm	Aoede	Breezy
Callirrhoe	Easy-going	Autonoe	Bright
Enceladus	Breathy	Iapetus	Clear
Umbriel	Easy-going	Algieba	Smooth
Despina	Smooth	Erinome	Clear
Algenib	Gravelly	Rasalgethi	Informative
Laomedeia	Upbeat	Achernar	Soft
Alnilam	Firm	Schedar	Even
Gacrux	Mature	Pulcherrima	Forward
Achird	Friendly	Zubenelgenubi	Casual
Vindemiatrix	Gentle	Sadachbia	Lively
Sadaltager	Knowledgeable	Sulafat	Warm

所有音色均标记为语言auto，可兼容上述全部三款模型（compatibleModels覆盖googleGeminiTtsModels），即音色选择不依赖具体模型。若不显式指定音色，服务端请求默认使用Kore（见 index.ts）。

第三步：验证配置并试听

Ping API：点击此按钮测试网络是否连通以及 API Key 是否填写正确。
选择模型和音色：测试成功后，选择界面列出的支持语音输出的模型，再到设置 → 发声启用对应音色。
输入短文本试听：确认音频可正常播放。

设置页加载时会自动完成三件事（见 google-gemini-audio-speech.vue）：

拉取已配置提供方的模型列表（loadModelsForConfiguredProviders）；
拉取该提供方的模型目录（fetchModelsForProvider）；
拉取该提供方的音色目录（loadVoicesForProvider），音色列表缓存在 speech store 的availableVoices中。

试听功能由SpeechPlayground组件承载，默认试听文本为Hello! This is a test of the Google Gemini Speech.；点击试听后，页面调用handleGenerateSpeech→speechStore.speech()，最终经由@xsai/generate-speech的generateSpeech完成请求（见 speech store）。

此外，设置页内置了提供方校验结果提示：校验失败会展示红色Alert，并允许通过「continueAnyway」按钮强制继续；校验成功则展示绿色成功提示（见 google-gemini-audio-speech.vue）。

::: tip 发声设置要点在 AIRI 中，「发声」是语音输出的总开关。只有同时选中了提供方、模型、音色三项（speech store 的configured计算属性要求hasModel && hasVoice同时为真，见 speech.ts），语音链路才会判定为已就绪。相关选择会持久化在settings/speech/active-provider、settings/speech/active-model、settings/speech/voice等本地存储键中。 :::

深入：一次 Gemini TTS 请求的完整数据链路

AIRI 并没有直接使用 OpenAI 兼容的音频端点，而是为 Gemini 实现了专用的createAudioFetch请求适配器（见 index.ts），整个流程可以拆解为四个阶段：

1. 请求构造。适配器解析调用方传入的input、model、voice、temperature，缺input或缺model都会直接抛错。随后向`${baseUrl}models/${model}:generateContent`发起POST请求，认证方式不是 Bearer Token，而是请求头x-goog-api-key携带 API Key。

2. 生成参数。请求体包含：

contents：把输入文本包装为单个 part 的text字段；
generationConfig.responseModalities: ['AUDIO']：显式要求模型以音频形式响应；
generationConfig.speechConfig.voiceConfig.prebuiltVoiceConfig.voiceName：指定音色名，缺省为Kore；
可选temperature。

3. 响应解析。从candidates[0].content.parts中找到携带inlineData的 part，取出 base64 编码的音频数据；若响应中没有音频数据则抛出Gemini TTS response missing audio data。

4. PCM16 → WAV 转码。Gemini 返回的inlineData是 24kHz 的 PCM16 原始采样数据，AIRI 通过toWavFromPCM16(decodeBase64(audio), 24000)将其封装为标准 WAV（见 index.ts）。该转换函数位于 packages/audio/src/encoding/wav.ts，会写入标准的 RIFF/WAVE 头（采样率 24000、单声道、16 位量化），测试用例在 wav.test.ts 中验证了 WAV 头的采样率字段确实为 24000。

也就是说，AIRI 会把 Gemini 的音频输出统一规格化为24kHz / 单声道 / PCM16 的 WAV 数据再交给上层播放，这保证了不同 TTS 供应商的音频在 AIRI 的统一语音管线中能被一致地消费。

排查指南

验证失败时，按以下顺序逐项检查：

API Key 是否正确：确认粘贴无多余空格、未串行、未过期；源码校验器只做非空检查，真实凭据是否有效需要由 Ping / 试听请求来确认。
账户地区与配额：Gemini 模型的可用性与计费受账户地区影响，部分区域可能无法访问音频输出模型。
网络连通性：确认能够访问generativelanguage.googleapis.com，企业代理、防火墙或自定义 Base URL 拼写错误都会导致失败。
请求成功但无声音：确认所选模型确实支持音频输出（务必选择*tts*系列模型），并确认在「发声」中已启用音色；同时检查系统音量与音频输出设备。
自定义 Base URL 场景：若使用企业网关或兼容代理，请确认网关完整透传x-goog-api-key头并兼容generateContent接口，且 URL 以/结尾或由 AIRI 自动补全。