在 AIRI 中配置 OpenAI 兼容 TTS从 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本篇技术指南讲解如何在 AIRI 中接入 OpenAI 官方语音合成TTS服务或任何提供 OpenAI 兼容语音接口的服务商覆盖 API Key 获取、Base URL 与模型配置、音色选择、发声验证以及常见故障排查。读完本文你将能够在“发声”模块中自由切换已配置的语音服务商、模型与音色让 AIRI 真正开口说话并理解从文本到音频的底层处理链路。为什么选择 OpenAI 兼容 TTSAIRI 的语音合成TTS功能将文字回复转化为语音朗读出来。如果你的语音服务商明确提供 OpenAI 兼容的语音合成接口就可以使用同一种配置方式接入 AIRI官方文档将其列为推荐方案。需要特别注意的是仅 API 地址以/v1结尾或密钥以sk-开头不能保证服务兼容接入前请务必确认服务商文档中明确声明支持 OpenAI 语音合成create speech接口。从源码结构看AIRI 在 provider-inference 服务商注册表 中同时注册了两个 TTS 相关服务商见 openai-audio 实现服务商 ID名称默认 Base URL适用场景openai-audio-speechOpenAIhttps://api.openai.com/v1/OpenAI 官方语音服务openai-compatible-audio-speechOpenAI Compatible空必须填写任何遵循 OpenAI 规范的第三方语音 API两者在设置界面中分别对应“OpenAI”与“OpenAI 兼容 API”两个入口任务类型tasks均为text-to-speech。官方服务商的模型与音色列表内置在仓库中兼容服务商则通过请求/v1/models动态获取模型列表。第一步获取 API Key登录所选服务商的管理控制台。在 API 密钥或开发者设置页面创建 API Key。复制密钥并妥善保存后续填入 AIRI 配置中。⚠️API Key 安全不要将 API Key 提交到仓库、放入截图或发送给他人。密钥泄露后请立即在服务商控制台撤销它并创建新密钥。AIRI 的凭据默认保存在当前设备的本地设置中切勿在截图、日志、Issue 或聊天记录中公开。第二步在 AIRI 中配置打开设置 → 服务商 → 语音合成 → OpenAI 兼容 API使用官方服务时选择“OpenAI”。填写 API Key 和要使用的 TTS 模型 ID。使用 OpenAI 官方服务时保留默认 Base URLhttps://api.openai.com/v1/使用兼容服务时填写服务商文档提供的 API 根地址。根据需要调整语速。配置字段说明结合 common.md 通用配置说明 与 openai-audio 配置结构字段含义填写建议API Key服务商签发的访问令牌密码输入框直接粘贴完整密钥不要添加引号或空格Base URL服务商 API 的根地址官方服务保留默认值自定义地址必须填写完整https://或http://地址模型TTS 使用的模型 ID优先从 AIRI 的列表中选择若列表加载失败按服务商文档手动填写音色TTS 朗读时使用的 voice ID先选择模型再选择该模型支持的音色语速朗读速度按需调整Base URL 的校验规则从源码可以确认AIRI 在提交配置时会执行严格的前置校验见 createAudioValidatorsAPI Key 必填为空直接报错Base URL 必填兼容服务商必须显式填写必须为绝对地址需包含http://或https://scheme否则提示“Base URL is not absolute”必须以斜杠/结尾源码中的normalizeBaseUrl会自动为未以/结尾的地址补上尾斜杠但校验器仍会提示用户规范填写。理解这一规则有助于排查问题例如把https://api.example.com/v1缺少尾斜杠直接粘贴时校验可能失败或行为与预期不一致。第三步验证配置打开设置 → 发声选择已配置的服务商、模型和音色。输入一段测试文本并点击测试。能正常播放语音即表示配置成功如果显示错误请根据错误信息检查凭据、模型 ID 与 Base URL。语音服务商的验证是在“发声”模块的测试区中通过实际播放结果来完成的见 audio.md 与 common.md 的“验证结果”说明这与聊天服务商的 Ping API 方式不同因此必须真正触发一次语音合成请求才能确认配置有效。内置模型与音色清单OpenAI 官方 TTS 服务商在仓库中内置了以下模型见 openAISpeechModels模型 ID展示名称说明tts-1TTS-1为实时文本转语音任务优化tts-1-hdTTS-1-HD更高保真的音频输出gpt-4o-mini-ttsGPT-4o Mini TTS面向文本转语音优化的 GPT-4o Minigpt-4o-mini-tts-2025-12-15GPT-4o Mini TTS (2025-12-15)指定快照版本由于 OpenAI 不提供音色列表接口仓库中的音色清单见 openAISpeechVoices严格对照 create-speech API 维护共 13 个音色TTS-1 系列与 GPT-4o Mini TTS 通用9 个alloy、ash、coral、echo、fable、onyx、nova、sage、shimmer仅 GPT-4o Mini TTS 支持4 个ballad、verse、marin、cedar。因此在选择音色时应先确认所选模型与音色的兼容关系源码中每个音色都通过compatibleModels声明了可用模型。若选择了ballad音色却搭配tts-1模型将无法正确发声。兼容服务商的模型列表对于“OpenAI 兼容 API”服务商AIRI 会调用其/v1/models接口拉取模型再过滤出 ID 中包含tts的条目作为可选项见 listModels 实现。这意味着兼容服务商的模型列表是动态加载的取决于服务商是否提供/v1/models接口若列表加载失败可按服务商文档在“发声”中手动输入精确的模型 ID手动填写的模型 ID 必须与服务商文档完全一致。排查指南没有声音时先确认已选择该服务商支持的模型和音色。使用兼容服务时请确认其明确支持 OpenAI 语音合成接口。其他常见排查方向综合自官方文档与源码校验逻辑检查模型与音色兼容性音色必须在所选模型的compatibleModels范围内见上文清单核对 Base URL确认地址为绝对地址且以/结尾将 Base URL 恢复为服务商默认值或与服务商官方文档逐字核对核对凭据重新复制 API Key检查是否复制了多余的空格或换行检查额度与权限确认账户已开通对应服务且有可用额度检查网络环境确认网络、代理和防火墙允许访问该服务商测试区显示服务商错误优先检查 API Key、余额和模型是否支持语音合成见 audio.md 常见问题。底层原理一段文本如何变成声音了解 AIRI 的音频流水线有助于理解 TTS 配置背后发生了什么。AIRI 将文本转语音拆分为“文本分块 → 并发请求 → 时序播放”三个阶段核心实现在 speech-pipeline.ts 与 tts-chunker.ts 中。文本分块chunking长文本不会一次性送入 TTS 接口而是由 chunkTtsInput 按标点与词数边界切分成段。其默认策略包括boost默认 2开头几段即使较短也立即合成降低首字延迟minimumWords默认 4与maximumWords默认 12控制单个请求的文本长度硬标点句号、问号、感叹号、换行等作为强切分边界软标点逗号、顿号、引号等作为弱切分边界使用Intl.Segmenter按词切分并对“1.2”这类小数点的误判、...省略号等做了专门处理。此外还支持叙事文本过滤stripNarrative选项把*动作*、旁白等角色扮演叙事从朗读文本中剔除避免 AIRI 把动作描写也读出来。并发与优先级语音流水线createSpeechPipeline允许最多 4 个 TTS 生成任务并发执行ttsMaxConcurrent默认 4并按优先级排序处理多个发言意图intent。每个意图可配置三种行为queue排队等待interrupt更高优先级的意图可打断当前朗读replace直接替换当前意图。这也解释了为何在“发声”测试时多次测试或与实时聊天同时发生时语音播放仍能保持合理的顺序与节奏。相关阅读配置语音输入与输出TTS 与 ASR 的整体配置入口通用配置说明API Key、Base URL、验证流程的通用约定OpenAI 兼容 APIASR/STT同一套兼容机制在语音识别侧的应用openai-audio 服务商实现模型、音色、校验规则的源码依据语音合成流水线 与 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-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考