AIRI 接入 OpenAI 兼容 TTS 语音合成Provider 配置、校验机制与实战排查【免费下载链接】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 或任意OpenAI 兼容语音服务接入为语音合成Text-to-SpeechProvider涵盖 API Key 获取、Base URL 与模型 ID 填写、语速调整、配置校验机制以及在语音合成模块中选择模型与音色并完成 Test Voice 验证的全流程。读完本文你将掌握一套可复现的 OpenAI 兼容 TTS 接入方案并能借助源码级原理定位无声音校验失败等常见问题。为什么选用 OpenAI 兼容 TTSAIRI 的语音合成模块内置了两种可对接 OpenAI 生态的 Provider官方OpenAIopenai-audio-speech与OpenAI Compatibleopenai-compatible-audio-speech。两者均实现 OpenAI 语音合成接口唯一的区别是官方 Provider 内置默认 Base URLhttps://api.openai.com/v1/而 OpenAI Compatible Provider 需要你手动填写完整的 API 根地址。一个必须强调的前提是仅当你的语音服务商明确声明实现了 OpenAI 语音 API 时才适合使用 OpenAI Compatible Provider。API 地址以/v1结尾、或密钥以sk-开头都不能保证服务真正兼容。接入后若请求失败问题往往出在接口不完全兼容而非 AIRI 配置错误。从源码看OpenAI Compatible 语音 Provider 与官方 OpenAI 语音 Provider 共用同一套createAudioProvider实现见 packages/stage-ui/src/libs/providers/providers/openai-audio/index.ts最终都是通过createOpenAI(apiKey, baseUrl)构造客户端并调用 OpenAI 的/v1/audio/speech接口生成音频。这意味着只要目标服务遵循 OpenAI 的 create-speech 规范接入路径就是一致的。第一步获取 API Key在开始配置前先从你的语音服务商处获取凭证登录所选服务商的管理控制台。在API Key或开发者设置页面创建 API Key。复制密钥并妥善保存。API Key 安全要求不要将 API Key 提交到仓库、放入截图或发送给任何人。密钥一旦泄露立即在服务商控制台撤销它并重新创建。AIRI 在配置表单中会将 API Key 字段标记为type: password见 openai-audio/index.ts 中的createAudioConfigSchema输入时不会明文回显。第二步在 AIRI 中配置 OpenAI 兼容 Provider打开设置 → 服务商 → 语音合成 → OpenAI Compatible进入配置页对应页面实现为 packages/stage-pages/src/pages/settings/providers/speech/openai-compatible-audio-speech.vue完成以下字段配置项说明默认值 / 取值范围API Key服务商签发的密钥必填无默认值Base URL服务商文档给出的完整 API 根地址无默认值兼容 Provider 不内置Model使用的 TTS 模型 ID页面默认tts-1Voice音色 ID页面默认alloySpeed语速默认1.0可调范围0.5~2.0步长0.01关于 Base URL 的关键细节这是最常见的配置误区使用 OpenAI 官方服务时应选择独立的OpenAIProvideropenai-audio-speech其 Base URL 有默认值https://api.openai.com/v1/源码常量OPENAI_BASE_URL见 openai-audio/index.ts。使用兼容服务时选择OpenAI CompatibleProvider。它的baseUrl配置项默认值为空字符串需要你按服务商文档填写完整的 API 根地址如https://your-provider.example.com/v1/。源码中的normalizeBaseUrl函数openai-audio/index.ts会在创建客户端前规范化地址去掉首尾空白并保证以/结尾例如https://example.com/v1会被补全为https://example.com/v1/避免拼 URL 时出现双斜杠或缺斜杠问题。此外配置校验器要求 Base URL 必须是包含 schemehttp://或https://的绝对 URL并建议以/结尾见下方配置校验一节否则会直接提示错误。模型与音色的选择逻辑模型列表兼容 Provider 会调用listModelsopenai-audio/index.ts请求GET {baseUrl}/models并对返回结果做model.id.toLowerCase().includes(tts)过滤只把名称中带tts的模型展示出来。如果你的服务商模型命名不含tts字样它不会出现在下拉列表里但仍可通过手动输入模型 ID 使用。音色列表由于 OpenAI 语音 API 本身不提供 voice-list 端点兼容 Provider 的listVoices返回空数组。因此 AIRI 会在运行时把你在语音合成模块中填入的音色 ID 直接包装为一个 VoiceInfo 对象见 packages/stage-ui/src/stores/modules/speech.ts即兼容场景下音色 ID 完全由你手动指定。官方 OpenAI 的音色参考源码内置了官方音色清单TTS-1/TTS-1-HD 支持alloy、ash、coral、echo、fable、onyx、nova、sage、shimmergpt-4o-mini-tts额外支持ballad、verse、marin、cedar见 openai-audio/index.ts。兼容服务若实现同样的 create-speech 接口音色 ID 通常也可沿用这套命名。第三步理解配置校验机制保存 Provider 时AIRI 会对配置做多级校验。校验器实现在 packages/stage-ui/src/libs/providers/validators/openai-compatible.tsOpenAI Compatible 语音 Provider 使用其中的配置校验与连通性校验逻辑见 openai-audio/index.ts。校验按顺序执行配置校验check-config检查 API Key 是否为空、Base URL 是否为空并用new URL()解析 Base URL 是否为绝对地址openai-compatible.ts。这能在发出任何网络请求前拦截明显错误的填写。连通性校验check-connectivity向{baseUrl}/models发起带Authorization: Bearer apiKey的 GET 请求10 秒超时仅当返回 5xx 或网络错误时判定失败openai-compatible.ts。它验证的是地址可达 凭证被接受不保证具体 TTS 接口可用。模型列表校验check-model-list拉取模型列表并确认非空。配置页中校验失败会显示红色错误横幅其中包含继续 AnywaycontinueAnyway按钮允许在明知校验未通过的情况下强制保存见 openai-compatible-audio-speech.vue。如果你的服务商模型命名不包含tts、或/models接口不可用导致校验报错可借助此按钮继续配置但务必确认真实语音请求可用。第四步在语音合成模块中完成选择与验证Provider 保存后还需在模块层完成绑定才能生效。打开设置 → 模块 → 语音合成对应页面为 packages/stage-pages/src/pages/settings/modules/speech.vue在提供者下拉中选择已配置的OpenAI Compatible。选择模型若已通过/models拉取到则直接可选否则手动输入。输入音色 ID。输入一段测试文本点击Test Voice。语音合成的实际调用链路为speechStore.speech()→generateSpeech()见 packages/stage-ui/src/stores/modules/speech.ts请求体包含input文本、voice音色 ID、model及语速等附加参数。若测试音频能正常播放说明 Provider 已正确配置若 AIRI 报错则按错误信息依次检查凭证错误401/403API Key 无效或权限不足重新签发并更新。模型错误404/400模型 ID 拼写错误或该服务商不支持该模型。地址错误网络错误/404Base URL 填错、缺少 scheme、或未以/v1根路径结尾对照服务商文档核对。问题排查与常见坑症状可能原因与处理测试无声音所选模型、音色不为该服务商支持在语音合成模块确认模型与音色 ID 拼写若音色列表为空属正常现象OpenAI 无 voice-list 端点需手动输入服务商支持的音色 ID校验报Base URL is not absoluteBase URL 缺少http://或https://前缀补全 scheme校验报Connectivity check failed服务不可达或凭证不被接受确认{baseUrl}/models可访问、API Key 正确模型下拉为空服务商/models返回的模型名不含tts或该端点不可用改为手动输入模型 ID音频生成慢/超时部分兼容服务实现的不是标准 create-speech 接口确认服务商文档明确声明OpenAI 语音 API 兼容总结AIRI 的 OpenAI 兼容 TTS 接入遵循服务商发 Key → Provider 填配置 → 模块选模型音色 → Test Voice 验证四步流程。核心要点有三其一兼容 Provider 不内置 Base URL务必填写完整 API 根地址其二音色列表在兼容场景下为空音色 ID 需手动输入其三配置校验只保证地址可达 凭证有效最终能否发声取决于服务商是否真正实现 OpenAI 语音合成接口。相关实现可直接查阅 openai-audio/index.ts、validators/openai-compatible.ts 与 speech.ts 三个源码文件。【免费下载链接】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），仅供参考 AIRI 接入 OpenAI 兼容 TTS 语音合成：Provider 配置、校验机制与实战排查
AIRI 接入 OpenAI 兼容 TTS 语音合成Provider 配置、校验机制与实战排查【免费下载链接】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 或任意OpenAI 兼容语音服务接入为语音合成Text-to-SpeechProvider涵盖 API Key 获取、Base URL 与模型 ID 填写、语速调整、配置校验机制以及在语音合成模块中选择模型与音色并完成 Test Voice 验证的全流程。读完本文你将掌握一套可复现的 OpenAI 兼容 TTS 接入方案并能借助源码级原理定位无声音校验失败等常见问题。为什么选用 OpenAI 兼容 TTSAIRI 的语音合成模块内置了两种可对接 OpenAI 生态的 Provider官方OpenAIopenai-audio-speech与OpenAI Compatibleopenai-compatible-audio-speech。两者均实现 OpenAI 语音合成接口唯一的区别是官方 Provider 内置默认 Base URLhttps://api.openai.com/v1/而 OpenAI Compatible Provider 需要你手动填写完整的 API 根地址。一个必须强调的前提是仅当你的语音服务商明确声明实现了 OpenAI 语音 API 时才适合使用 OpenAI Compatible Provider。API 地址以/v1结尾、或密钥以sk-开头都不能保证服务真正兼容。接入后若请求失败问题往往出在接口不完全兼容而非 AIRI 配置错误。从源码看OpenAI Compatible 语音 Provider 与官方 OpenAI 语音 Provider 共用同一套createAudioProvider实现见 packages/stage-ui/src/libs/providers/providers/openai-audio/index.ts最终都是通过createOpenAI(apiKey, baseUrl)构造客户端并调用 OpenAI 的/v1/audio/speech接口生成音频。这意味着只要目标服务遵循 OpenAI 的 create-speech 规范接入路径就是一致的。第一步获取 API Key在开始配置前先从你的语音服务商处获取凭证登录所选服务商的管理控制台。在API Key或开发者设置页面创建 API Key。复制密钥并妥善保存。API Key 安全要求不要将 API Key 提交到仓库、放入截图或发送给任何人。密钥一旦泄露立即在服务商控制台撤销它并重新创建。AIRI 在配置表单中会将 API Key 字段标记为type: password见 openai-audio/index.ts 中的createAudioConfigSchema输入时不会明文回显。第二步在 AIRI 中配置 OpenAI 兼容 Provider打开设置 → 服务商 → 语音合成 → OpenAI Compatible进入配置页对应页面实现为 packages/stage-pages/src/pages/settings/providers/speech/openai-compatible-audio-speech.vue完成以下字段配置项说明默认值 / 取值范围API Key服务商签发的密钥必填无默认值Base URL服务商文档给出的完整 API 根地址无默认值兼容 Provider 不内置Model使用的 TTS 模型 ID页面默认tts-1Voice音色 ID页面默认alloySpeed语速默认1.0可调范围0.5~2.0步长0.01关于 Base URL 的关键细节这是最常见的配置误区使用 OpenAI 官方服务时应选择独立的OpenAIProvideropenai-audio-speech其 Base URL 有默认值https://api.openai.com/v1/源码常量OPENAI_BASE_URL见 openai-audio/index.ts。使用兼容服务时选择OpenAI CompatibleProvider。它的baseUrl配置项默认值为空字符串需要你按服务商文档填写完整的 API 根地址如https://your-provider.example.com/v1/。源码中的normalizeBaseUrl函数openai-audio/index.ts会在创建客户端前规范化地址去掉首尾空白并保证以/结尾例如https://example.com/v1会被补全为https://example.com/v1/避免拼 URL 时出现双斜杠或缺斜杠问题。此外配置校验器要求 Base URL 必须是包含 schemehttp://或https://的绝对 URL并建议以/结尾见下方配置校验一节否则会直接提示错误。模型与音色的选择逻辑模型列表兼容 Provider 会调用listModelsopenai-audio/index.ts请求GET {baseUrl}/models并对返回结果做model.id.toLowerCase().includes(tts)过滤只把名称中带tts的模型展示出来。如果你的服务商模型命名不含tts字样它不会出现在下拉列表里但仍可通过手动输入模型 ID 使用。音色列表由于 OpenAI 语音 API 本身不提供 voice-list 端点兼容 Provider 的listVoices返回空数组。因此 AIRI 会在运行时把你在语音合成模块中填入的音色 ID 直接包装为一个 VoiceInfo 对象见 packages/stage-ui/src/stores/modules/speech.ts即兼容场景下音色 ID 完全由你手动指定。官方 OpenAI 的音色参考源码内置了官方音色清单TTS-1/TTS-1-HD 支持alloy、ash、coral、echo、fable、onyx、nova、sage、shimmergpt-4o-mini-tts额外支持ballad、verse、marin、cedar见 openai-audio/index.ts。兼容服务若实现同样的 create-speech 接口音色 ID 通常也可沿用这套命名。第三步理解配置校验机制保存 Provider 时AIRI 会对配置做多级校验。校验器实现在 packages/stage-ui/src/libs/providers/validators/openai-compatible.tsOpenAI Compatible 语音 Provider 使用其中的配置校验与连通性校验逻辑见 openai-audio/index.ts。校验按顺序执行配置校验check-config检查 API Key 是否为空、Base URL 是否为空并用new URL()解析 Base URL 是否为绝对地址openai-compatible.ts。这能在发出任何网络请求前拦截明显错误的填写。连通性校验check-connectivity向{baseUrl}/models发起带Authorization: Bearer apiKey的 GET 请求10 秒超时仅当返回 5xx 或网络错误时判定失败openai-compatible.ts。它验证的是地址可达 凭证被接受不保证具体 TTS 接口可用。模型列表校验check-model-list拉取模型列表并确认非空。配置页中校验失败会显示红色错误横幅其中包含继续 AnywaycontinueAnyway按钮允许在明知校验未通过的情况下强制保存见 openai-compatible-audio-speech.vue。如果你的服务商模型命名不包含tts、或/models接口不可用导致校验报错可借助此按钮继续配置但务必确认真实语音请求可用。第四步在语音合成模块中完成选择与验证Provider 保存后还需在模块层完成绑定才能生效。打开设置 → 模块 → 语音合成对应页面为 packages/stage-pages/src/pages/settings/modules/speech.vue在提供者下拉中选择已配置的OpenAI Compatible。选择模型若已通过/models拉取到则直接可选否则手动输入。输入音色 ID。输入一段测试文本点击Test Voice。语音合成的实际调用链路为speechStore.speech()→generateSpeech()见 packages/stage-ui/src/stores/modules/speech.ts请求体包含input文本、voice音色 ID、model及语速等附加参数。若测试音频能正常播放说明 Provider 已正确配置若 AIRI 报错则按错误信息依次检查凭证错误401/403API Key 无效或权限不足重新签发并更新。模型错误404/400模型 ID 拼写错误或该服务商不支持该模型。地址错误网络错误/404Base URL 填错、缺少 scheme、或未以/v1根路径结尾对照服务商文档核对。问题排查与常见坑症状可能原因与处理测试无声音所选模型、音色不为该服务商支持在语音合成模块确认模型与音色 ID 拼写若音色列表为空属正常现象OpenAI 无 voice-list 端点需手动输入服务商支持的音色 ID校验报Base URL is not absoluteBase URL 缺少http://或https://前缀补全 scheme校验报Connectivity check failed服务不可达或凭证不被接受确认{baseUrl}/models可访问、API Key 正确模型下拉为空服务商/models返回的模型名不含tts或该端点不可用改为手动输入模型 ID音频生成慢/超时部分兼容服务实现的不是标准 create-speech 接口确认服务商文档明确声明OpenAI 语音 API 兼容总结AIRI 的 OpenAI 兼容 TTS 接入遵循服务商发 Key → Provider 填配置 → 模块选模型音色 → Test Voice 验证四步流程。核心要点有三其一兼容 Provider 不内置 Base URL务必填写完整 API 根地址其二音色列表在兼容场景下为空音色 ID 需手动输入其三配置校验只保证地址可达 凭证有效最终能否发声取决于服务商是否真正实现 OpenAI 语音合成接口。相关实现可直接查阅 openai-audio/index.ts、validators/openai-compatible.ts 与 speech.ts 三个源码文件。【免费下载链接】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），仅供参考