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

AIRI 支持将 OpenRouter 作为语音合成（Text-to-Speech）服务商，让你在同一个 OpenRouter 账户下统一管理音频模型与音色。本文基于 openrouter.md（韩文版）（英文版见 openrouter.md，简体中文版见 openrouter.md），并结合仓库源码说明配置项背后的实现细节。读完本文，你将掌握：如何申请 API Key、如何在 AIRI 设置界面完成配置、如何通过「发声」模块选择模型与音色并做发声测试，以及无声音等常见问题的排查思路。

为什么选择 OpenRouter 语音？

OpenRouter 本身是一个聚合式 API 服务商，它把多家上游模型提供商的接口统一收敛到一套 OpenAI 兼容协议之下。在 AIRI 的语音合成场景中，选择 OpenRouter 意味着：

• 可以在同一个 OpenRouter 账户里集中管理多个音频模型和音色，而不必为每家上游分别申请密钥；
• 实际可用性（网络环境、支付方式、服务商政策）因用户所在地区而异，例如简体中文文档提示中国大陆用户可优先尝试 302.AI 等替代聚合渠道。

这一点在源码中也有体现：AIRI 的 provider 注册表里同时存在openrouter-ai（对话/chat 任务）与openrouter-audio-speech（文本转语音任务）两个条目，其中 openrouter-audio-speech/index.ts 正是本文主角——语音合成提供商的完整实现。

第一步：获取 OpenRouter API Key

在开始配置前，需要先在 OpenRouter 控制台创建密钥：

1. 打开 OpenRouter 的 API Keys 页面，创建一个新的 API Key。
2. 为密钥设置适当的名称、有效期和额度限制，便于后续管理和控制成本。
3. 复制密钥并妥善保存，配置时粘贴到 AIRI 中。

API Key 安全警告不要将 API Key 提交到仓库、放入截图，或发送给他人。一旦密钥泄露，请立即在 OpenRouter 控制台撤销它并创建新密钥。

从源码实现看，API Key 是 OpenRouter 语音提供商的必填项：配置 Schema 定义为apiKey: z.string()，且校验器在apiKey为空时直接判定配置无效（提示API Key is required.），对应 openrouter-audio-speech/index.ts。

第二步：在 AIRI 中配置 OpenRouter

配置路径为设置 → 服务商 → 语音合成 → OpenRouter，对应仓库中的设置页面 openrouter-audio-speech.vue，该页面由SpeechProviderSettings骨架与两个自定义插槽（voice-settings模型选择、playground发声实验台）构成。

需要填写的基础配置只有两项：

在源码中，Base URL 的默认值与归一化逻辑非常清晰：

• 默认地址常量定义为https://openrouter.ai/api/v1/（见 openrouter-audio-speech/index.ts）；
• 若用户清空了 Base URL，会回退到默认值；若用户输入的值末尾缺少/，会自动补上，保证拼接请求路径时格式正确（normalizeBaseUrl，见 openrouter-audio-speech/index.ts）。

因此保留默认 Base URL是最稳妥的做法；只有当你自建 OpenRouter 兼容代理或网关时才需要改动它。

第三步：验证配置并测试发声

配置完成后，进入设置 → 模块 → 发声（不同语言文档中亦有“语音合成”的表述）：

1. 选择刚才配置的OpenRouter服务商，并选择要使用的模型与音色。
2. 输入一段测试文本，点击测试声音（Test Voice）按钮。
3. 若能正常播放生成的语音，说明配置成功；若显示错误，请根据错误信息检查凭据与模型。

模型选择

OpenRouter 语音提供商默认使用openai/gpt-audio-mini模型（见 openrouter-audio-speech/index.ts），设置页面同样以该值作为兜底默认（见 openrouter-audio-speech.vue）。

页面上方的模型下拉框数据来自listModels扩展方法：AIRI 会请求 OpenRouter 的models?output_modality=audio端点，只拉取支持音频输出的模型，并自动过滤掉不可用的条目；请求失败时则返回空列表（见 openrouter-audio-speech/index.ts）。页面挂载时会自动加载已配置服务商的模型列表与音色列表（openrouter-audio-speech.vue）。

音色选择

音色列表来自内置的 OpenAI 风格声线集合，共 13 个，涵盖alloy、ash、ballad、coral、echo、fable、onyx、nova、sage、shimmer、verse、marin、cedar（见 openrouter-audio-speech/index.ts）。也就是说，只要上游模型支持 OpenAI 兼容的voice参数，这些声线即可直接选用。

源码视角：一次发声请求在 AIRI 内部如何流转

为了让你更清楚地理解“点了测试按钮之后发生了什么”，这里结合源码还原完整调用链：

1. 设置页的handleGenerateSpeech从 provider 实例化管道取出SpeechProvider，拿到用户输入的文本、所选音色和模型（见 openrouter-audio-speech.vue）。
2. 真正的请求封装在createAudioFetch中（openrouter-audio-speech/index.ts）：
   • 向{baseUrl}chat/completions发起 POST 请求，携带Authorization: Bearer <apiKey>；
   • 附带OpenRouter 归属信息头HTTP-Referer: https://airi.moeru.ai/与X-OpenRouter-Title: Project AIRI（这两个头定义于 openrouter-ai/index.ts），以满足 OpenRouter 对来源标注的要求；
   • 请求体把测试文本包装成Read this text aloud exactly as written...的朗读提示词，并声明modalities: ['text', 'audio']、audio: { voice, format: 'pcm16' }、stream: true。
3. 响应处理上，AIRI 以流式方式逐行解析 SSE 事件（以data:开头、遇[DONE]结束），从choices[0].delta.audio.data中提取 base64 编码的 PCM16 音频分片（openrouter-audio-speech/index.ts）。
4. 所有分片拼接解码后，调用toWavFromPCM16(bytes, 24000)以24 kHz 采样率封装成标准 WAV 文件，再以audio/wav类型返回给播放器（openrouter-audio-speech/index.ts）。WAV 封装本身位于 wav.ts，并有对应的 wav.test.ts 测试用例覆盖。

说明：OpenRouter 语音提供商在 provider 定义中被标记为paidCloud类（见 attributes.ts），即按使用量计费的云服务，因此账户余额不足会直接导致请求失败——这也是下方排查清单中要重点检查的原因。

常见问题排查

当点击测试后没有声音时，按以下顺序排查：

1. 所选模型是否支持音频输出：OpenRouter 上并非所有模型都支持语音模态。AIRI 的模型下拉框已通过output_modality=audio过滤，但若你手动填写了不支持的模型 ID，则不会有音频返回。
2. 账户余额与额度：paidCloud类服务按量计费，余额不足时请求会报错，请到 OpenRouter 控制台检查账户余额与密钥的额度限制。
3. 网络连接：OpenRouter 为境外聚合服务，请确认网络环境可正常访问https://openrouter.ai/api/v1/。
4. 凭据有效性：若错误信息提示鉴权失败，请重新检查 API Key 是否粘贴完整、是否已过期或被撤销；必要时在 OpenRouter 控制台新建密钥后重新配置。

小结

OpenRouter 为 AIRI 提供了一条“一个账户、多模型多音色”的语音合成路径。核心配置仅需 API Key 与默认 Base URL 两项，随后即可在“发声”模块中自由切换音频模型与 13 种内置声线。结合源码可以看到，AIRI 对 OpenRouter 的接入完全复用 OpenAI 兼容的chat/completions音频流协议，并在本地完成 PCM16 → WAV 的转封装，实现链路清晰、可排查性良好。若你所在网络环境访问 OpenRouter 不稳定，也可以参考 语音合成服务商文档目录 中的其他提供商方案。

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