oh-my-pi 的 tts 语音合成工具本地 Kokoro-82M、xAI Grok Voice 与 DeepInfra 三后端全解析【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi导读tts是 oh-my-pi⌥ Coding agent with the IDE wired in内置的写权限自定义工具它接收一段文本合成语音音频文件并写入指定路径。本指南以 docs/tools/tts.md 为骨架结合 packages/coding-agent/src/tools/tts.ts、本地语音目录、设置 Schema 与单元测试完整讲解tts的启用方式、六个输入参数、providers.tts后端路由local/xai/deepinfra/auto、输出与错误契约以及本地 WAV 与云端 MP3 的编解码差异。读完你将能够按需选择合成后端、正确配置语音与采样参数并理解每条调用背后的源码级行为。工具定位与启用条件tts是一个通过 SDK 注入的自定义工具custom tool其声明位于 packages/coding-agent/src/tools/tts.ts入口配套实现散落在本地语音目录packages/coding-agent/src/tts/models.ts本地 Worker 客户端packages/coding-agent/src/tts/tts-client.ts会话注入packages/coding-agent/src/sdk.tsspeechgen.enabled开关与内置工具不同该工具默认不注册只有当speechgen.enabledtrue时 SDK 才会将其注入工具列表。源码依据在 sdk.tsif (settings.get(speechgen.enabled)) { customTools.push(ttsTool as unknown as CustomTool); }对应的设置定义在 packages/coding-agent/src/config/settings-schema.tsspeechgen.enabled: { type: boolean, default: false, ui: { tab: tools, group: Available Tools, label: Speech Generation, description: Enable the tts tool for on-device (Kokoro) or xAI Grok Voice speech-file synthesis, }, },也就是说在设置Settings UI 的 Tools → Available Tools → Speech Generation中开启该项或等价地在配置中写入speechgen.enabled trueAgent 才会拿到tts工具。输入参数Inputstts的参数 Schema 定义在 tts.ts由oh-my-pi/omptype的type()声明字段类型必填说明textstring是待合成的文本长度必须为1..15000个字符voice_idstring否语音 ID。xAI 后端默认eve本地后端改由tts.localVoice设置决定DeepInfra 仅在显式传入时转发语音 ID 与模型相关未传则用服务端默认值languagestring否xAI 的语言提示默认enoutput_pathstring是目标文件路径相对会话工作目录session cwd解析sample_ratenumber.integer否xAI 采样率覆盖本地与 DeepInfra 后端忽略bit_ratenumber.integer否xAI MP3 比特率覆盖WAV 及本地/DeepInfra 后端忽略两个值得注意的 Schema 设计点text的约束写成1 string 15000常量XAI_MAX_TEXT_LENGTH 15_000与 xAI 侧保持一致tts.ts。voice_id是可选的且未加枚举限制。源码注释说明了原因xAI 除了内置语音还接受自定义 voice ID因此 Schema 不做 enum 约束内置列表只用于驱动工具描述tts.ts。output_path会在执行阶段通过resolveToCwd(params.output_path, cwd)解析到会话工作目录下的绝对路径并将展示路径换算为相对 cwd 的形式tts.ts。后端路由providers.tts 四种取值后端选择由设置providers.tts控制枚举值为auto/local/xai/deepinfra默认auto定义于 settings-schema.ts。路由决策逻辑被抽成纯函数resolveTtsBackend便于单测export function resolveTtsBackend(opts: { preference: string; wantsMp3: boolean; hasXaiCreds: boolean }): TtsBackend { if (opts.preference xai) return xai; if (opts.preference deepinfra) return deepinfra; if (opts.preference local) return local; if (opts.wantsMp3 opts.hasXaiCreds) return xai; return local; }见 tts.ts路由语义local始终使用本地设备端后端Kokoro-82M纯离线。xai始终使用 xAI Grok Voice缺少凭据时返回错误结果。deepinfra始终使用 DeepInfra 的 OpenAI 兼容语音端点缺少凭据时返回错误结果。auto优先本地但当请求的是 MP3 且存在 xAI 凭据时路由到 xAI——因为只有云端路径能产出 MP3本地后端不打包 MP3 编码器宁可改道云服务也不把请求的容器偷偷替换成 WAV。关于凭据探测还有一个细节只有当preference不是显式的local/deepinfra时才会去解析 xAI 凭据hasXaiCreds的求值分支见 tts.ts避免无谓的凭据查找开销。单元测试 packages/coding-agent/test/tts/tts-backend.test.ts 覆盖了这些分支显式deepinfra优先于 codec 与 xAI 凭据auto.mp3 有 xAI 凭据 →xaiauto无 MP3 需求或有 MP3 但无凭据 → 一律local。各后端行为对比Modes / Variants后端合成方式输出容器忽略的参数local完全设备端 Kokoro-82M模型权重就绪后无任何云端调用恒为 WAV/PCM16voice_id、language、sample_rate、bit_rate全部忽略xaixAI Grok Voice 云端合成baseURL/ttsMP3 或 WAV无deepinfraDeepInfra OpenAI 兼容/audio/speechhexgrad/Kokoro-82MMP3 或 WAVsample_rate、bit_rateauto本地优先MP3 请求且存在 xAI 凭据时走云端随路由而定随路由而定完整调用流程FlowSDK 仅在speechgen.enabled为 true 时注入tts工具。output_path相对会话 cwd 解析编解码由路径后缀大小写不敏感推断以.wav结尾表示 WAV其余一律按 MP3 处理tts.ts。读取providers.tts默认auto决定路由local/xai/deepinfra/auto。本地合成忽略单次调用的voice_id、language、sample_rate、bit_rate使用设置tts.localModel与tts.localVoice通过共享的 ONNX 小模型 Worker 调用 Kokoro-82Mkokoro-js把 Float32 PCM 编码为 PCM16 WAV 后落盘。xAI 合成解析 Grok Voice 凭据 → 调用baseURL/tts→ 将云端返回的字节直接写入文件。仅当 WAV 容器、采样率或 MP3 比特率与 xAI 默认值不一致时payload 才会显式携带output_format对齐 Hermes 的tts_tool.py行为见 tts.ts。DeepInfra 合成解析 DeepInfra API Key → POST{ model, input, response_format, voice? }到https://api.deepinfra.com/v1/openai/audio/speech模型固定为hexgrad/Kokoro-82M→ 字节直接写盘voice仅在调用方显式设置voice_id时才转发。本地后端Kokoro-82M 与语音目录模型注册表本地语音目录 packages/coding-agent/src/tts/models.ts 定义了TtsLocalModelSpec与TtsLocalVoiceSpec两个核心接口注册表当前只有一个模型键keyHugging Face 仓库默认精度采样率默认语音kokoroonnx-community/Kokoro-82M-v1.0-ONNXq824000 Hzaf_heartdtype默认q8约 100 MB 权重CPU 推理较快可通过providers.tinyModelDtype/PI_TINY_DTYPE覆盖。本地模型通过kokoro-js的KokoroTTS.from_pretrained加载运行在与其余 tiny-model 栈相同的huggingface/transformersonnxruntime运行时之上并打包 Kokoro 所需的 misaki/espeak 音素器见 models.ts 注释。关键设计一个模型覆盖全部语音/口音语言选择等价于语音选择无需额外下载。内置语音目录Kokoro 自带约 28 个语音项目精选了 12 个较高评级的美式/英式 × 女声/男声af_heartA 级为默认美式女声af_heart默认、af_bella、af_nicole、af_aoede、af_kore、af_sarah美式男声am_michael、am_fenrir、am_puck英式女声bf_emma英式男声bm_george、bm_fable完整列表见 models.ts。语音切换完全在设备端进行权重缓存后切换语音无需任何网络请求。本地合成实现细节本地路径由synthesizeLocal实现tts.ts模型键从tts.localModel读取仅当命中注册表时才采用否则回退默认kokoro语音从tts.localVoice读取未设置时回退af_heart。通过ttsClient.synthesize(modelKey, text, { voice, signal })请求 WorkerWorker 返回{ pcm: Float32Array, sampleRate }。本地输出恒为 WAVresolveLocalWavPath会把非.wav的目标路径改写成同目录同名.wav例如speech.mp3→speech.wav并在结果文本中明确说明替代。函数实现见 tts.ts。WAV 封装由 packages/coding-agent/src/tts/wav.ts 的encodeWav完成不依赖外部编码器手写 44 字节 RIFF/WAVE 头 小端有符号 16 位采样量化前先 clamp 到 [-1, 1] 防止越界回绕。本地 Worker 客户端packages/coding-agent/src/tts/tts-client.ts 的TtsClient管理本地合成懒启动 Worker#ensureWorker()首次请求时通过隐藏子命令__omp_worker_tts拉起子进程createTtsSubprocess支持引用计数ref/unref——空闲 Worker 被unref以免阻塞进程退出存在在途请求时才ref#syncWorkerRef。synthesize单次合成接受AbortSignal取消时 Promise 以null收尾。synthesizeStream流式合成会话push/end喂入完整可读片段chunks逐段产出音频供播放/演讲链路使用。downloadModel显式下载模型支持onProgress进度回调。单次工具调用的本地合成单发执行、不输出流式进度不触发onUpdate与文档一致。云端后端xAI Grok Voice 与 DeepInfraxAI 后端常量默认值voiceeve、languageen、sample rate24000、bit rate128000tts.ts非.wav路径请求 MP3。内置语音描述中列出ara、eve、leo、rex、sal同时接受自定义 voice IDtts.ts。凭据resolveXAIHttpCredentials(ctx.modelRegistry)解析 Grok Voice 凭据失败时返回错误文本No xAI credentials. Run /login → xAI Grok OAuth (SuperGrok or X Premium) or set XAI_API_KEY.。output_format仅在偏离默认时发送请求 WAV、或采样率 ≠ 24000、或 MP3 且比特率 ≠ 128000tts.ts。DeepInfra 后端端点https://api.deepinfra.com/v1/openai/audio/speech默认模型hexgrad/Kokoro-82Mtts.ts。payload 形如{ model, input, response_format, voice? }response_format取wav或mp3voice仅在调用方设置voice_id时加入否则使用服务端默认语音语音 ID 与模型相关见 tts.ts。凭据getApiKeyForProvider(deepinfra, sessionId)缺失时返回No DeepInfra credentials. Run /login → DeepInfra or set DEEPINFRA_API_KEY.。共享的云端请求管道两条云端路径共用postSpeechRequesttts.tsBearer 认证Authorization: Bearer key JSON body User-Agent。60 秒超时护栏AbortSignal.timeout(60_000)与调用方信号合并AbortSignal.any。HTTP 非 2xx 时把 provider 详情截断到前 300 字符并包装为ProviderHttpError最终映射为错误字符串其他异常原样抛出。输出契约Outputs成功时返回标准AgentToolResultcontent[0].type textcontent[0].text形如Saved bytes bytes to path (voicevoice, codeccodec, backendbackend...)——本地后端会附带采样率替换容器时还会追加 No local MP3 encoder is bundled, so WAV (PCM16) was written instead of the requested container. 的说明details { bytes, voiceId, codec, backend }其中voiceId本地为模型键/语音如kokoro/af_heartDeepInfra 未设voice_id时为default。错误情形xAI 或 DeepInfra 缺凭据、云端 HTTP 失败、本地 Worker 返回null返回isError: true仅含一个文本块且不带details其余异常调用方取消、60 秒云端超时、文件写入错误、本地 Worker 抛错则向上传播不会被包装成isError结果——这是消费方需要注意的边界。副作用、限制与错误速查Side Effects文件系统写入output_path本地合成收到非 WAV 目标时改写到同目录.wav兄弟路径。网络xAI 后端调用配置的 Grok Voice HTTP 端点DeepInfra 调用api.deepinfra.com本地后端仅可能在首次时通过 tiny-model 栈下载/缓存模型权重。会话状态读取 cwd、模型注册表以及设置providers.tts、tts.localModel、tts.localVoice。后台任务/取消云端调用有 60 秒超时本地合成接收调用方 abort 信号。流式/更新合成是单发执行不发送onUpdate进度事件。Limits Caps文本 Schema 上限1..15_000个 JavaScript 字符串字符。xAI 默认voiceeve、languageen、sample rate24000、bit rate128000非.wav路径请求 MP3。DeepInfra 默认模型hexgrad/Kokoro-82M未设voice_id时采用服务端默认语音。xAI 内置语音ara、eve、leo、rex、sal接受自定义 voice ID。本地默认模型kokoroonnx-community/Kokoro-82M-v1.0-ONNXq8默认语音af_heart。Errors 一览场景行为缺少 xAI 凭据isError: trueNo xAI credentials. Run /login → xAI Grok OAuth (SuperGrok or X Premium) or set XAI_API_KEY.缺少 DeepInfra 凭据isError: trueNo DeepInfra credentials. Run /login → DeepInfra or set DEEPINFRA_API_KEY.云端 HTTP 失败isError: truexAI TTS|DeepInfra TTS failed (status): detaildetail 最多 300 字符本地 Worker 返回nullisError: true提示模型键可能是 Worker 不可用或模型下载中断调用方取消 / 60s 超时 / 写盘错误 / Worker 抛错直接向上传播不包装成isError关键注意事项Notes本地 MP3 有意不内置请求speech.mp3时本地后端会写入speech.wav并在工具结果里明确说明替代行为只有auto xAI 凭据存在时MP3 请求才会被路由到云端真正产出 MP3。voice_id与language是 xAI payload 字段本地语音选择来自设置tts.localVoice因此模型调用无需在每次调用时枚举本地语音 ID这是把语音选择放在配置层而非参数层的设计考量docs/tools/tts.md Notes 段。快速上手配置建议想让 Agent 能生成语音文件第一步开启speechgen.enabled true默认关闭追求零成本、离线、隐私优先 →providers.tts local仅需确保首次运行时能从 tiny-model 栈拉取onnx-community/Kokoro-82M-v1.0-ONNXq8权重之后完全本地合成输出 WAV/PCM16需要 MP3 容器或更高音质 → 配置 xAI Grok OAuthSuperGrok / X Premium或XAI_API_KEY或设置DEEPINFRA_API_KEY走 DeepInfra只想按需使用、不想手动选后端 → 保持providers.tts auto本地优先、必要时自动借道 xAI 产出 MP3本地音色偏好通过tts.localVoice在af_heart等 12 个精选语音中挑选设置 UI 位于 Providers → Services。以上所有行为均可对照源码验证路由逻辑见 tts.ts 与测试 tts-backend.test.ts本地模型与语音见 models.tsWorker 客户端见 tts-client.tsWAV 编码见 wav.ts设置项见 settings-schema.ts。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 oh-my-pi 的 tts 语音合成工具：本地 Kokoro-82M、xAI Grok Voice 与 DeepInfra 三后端全解析
oh-my-pi 的 tts 语音合成工具本地 Kokoro-82M、xAI Grok Voice 与 DeepInfra 三后端全解析【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi导读tts是 oh-my-pi⌥ Coding agent with the IDE wired in内置的写权限自定义工具它接收一段文本合成语音音频文件并写入指定路径。本指南以 docs/tools/tts.md 为骨架结合 packages/coding-agent/src/tools/tts.ts、本地语音目录、设置 Schema 与单元测试完整讲解tts的启用方式、六个输入参数、providers.tts后端路由local/xai/deepinfra/auto、输出与错误契约以及本地 WAV 与云端 MP3 的编解码差异。读完你将能够按需选择合成后端、正确配置语音与采样参数并理解每条调用背后的源码级行为。工具定位与启用条件tts是一个通过 SDK 注入的自定义工具custom tool其声明位于 packages/coding-agent/src/tools/tts.ts入口配套实现散落在本地语音目录packages/coding-agent/src/tts/models.ts本地 Worker 客户端packages/coding-agent/src/tts/tts-client.ts会话注入packages/coding-agent/src/sdk.tsspeechgen.enabled开关与内置工具不同该工具默认不注册只有当speechgen.enabledtrue时 SDK 才会将其注入工具列表。源码依据在 sdk.tsif (settings.get(speechgen.enabled)) { customTools.push(ttsTool as unknown as CustomTool); }对应的设置定义在 packages/coding-agent/src/config/settings-schema.tsspeechgen.enabled: { type: boolean, default: false, ui: { tab: tools, group: Available Tools, label: Speech Generation, description: Enable the tts tool for on-device (Kokoro) or xAI Grok Voice speech-file synthesis, }, },也就是说在设置Settings UI 的 Tools → Available Tools → Speech Generation中开启该项或等价地在配置中写入speechgen.enabled trueAgent 才会拿到tts工具。输入参数Inputstts的参数 Schema 定义在 tts.ts由oh-my-pi/omptype的type()声明字段类型必填说明textstring是待合成的文本长度必须为1..15000个字符voice_idstring否语音 ID。xAI 后端默认eve本地后端改由tts.localVoice设置决定DeepInfra 仅在显式传入时转发语音 ID 与模型相关未传则用服务端默认值languagestring否xAI 的语言提示默认enoutput_pathstring是目标文件路径相对会话工作目录session cwd解析sample_ratenumber.integer否xAI 采样率覆盖本地与 DeepInfra 后端忽略bit_ratenumber.integer否xAI MP3 比特率覆盖WAV 及本地/DeepInfra 后端忽略两个值得注意的 Schema 设计点text的约束写成1 string 15000常量XAI_MAX_TEXT_LENGTH 15_000与 xAI 侧保持一致tts.ts。voice_id是可选的且未加枚举限制。源码注释说明了原因xAI 除了内置语音还接受自定义 voice ID因此 Schema 不做 enum 约束内置列表只用于驱动工具描述tts.ts。output_path会在执行阶段通过resolveToCwd(params.output_path, cwd)解析到会话工作目录下的绝对路径并将展示路径换算为相对 cwd 的形式tts.ts。后端路由providers.tts 四种取值后端选择由设置providers.tts控制枚举值为auto/local/xai/deepinfra默认auto定义于 settings-schema.ts。路由决策逻辑被抽成纯函数resolveTtsBackend便于单测export function resolveTtsBackend(opts: { preference: string; wantsMp3: boolean; hasXaiCreds: boolean }): TtsBackend { if (opts.preference xai) return xai; if (opts.preference deepinfra) return deepinfra; if (opts.preference local) return local; if (opts.wantsMp3 opts.hasXaiCreds) return xai; return local; }见 tts.ts路由语义local始终使用本地设备端后端Kokoro-82M纯离线。xai始终使用 xAI Grok Voice缺少凭据时返回错误结果。deepinfra始终使用 DeepInfra 的 OpenAI 兼容语音端点缺少凭据时返回错误结果。auto优先本地但当请求的是 MP3 且存在 xAI 凭据时路由到 xAI——因为只有云端路径能产出 MP3本地后端不打包 MP3 编码器宁可改道云服务也不把请求的容器偷偷替换成 WAV。关于凭据探测还有一个细节只有当preference不是显式的local/deepinfra时才会去解析 xAI 凭据hasXaiCreds的求值分支见 tts.ts避免无谓的凭据查找开销。单元测试 packages/coding-agent/test/tts/tts-backend.test.ts 覆盖了这些分支显式deepinfra优先于 codec 与 xAI 凭据auto.mp3 有 xAI 凭据 →xaiauto无 MP3 需求或有 MP3 但无凭据 → 一律local。各后端行为对比Modes / Variants后端合成方式输出容器忽略的参数local完全设备端 Kokoro-82M模型权重就绪后无任何云端调用恒为 WAV/PCM16voice_id、language、sample_rate、bit_rate全部忽略xaixAI Grok Voice 云端合成baseURL/ttsMP3 或 WAV无deepinfraDeepInfra OpenAI 兼容/audio/speechhexgrad/Kokoro-82MMP3 或 WAVsample_rate、bit_rateauto本地优先MP3 请求且存在 xAI 凭据时走云端随路由而定随路由而定完整调用流程FlowSDK 仅在speechgen.enabled为 true 时注入tts工具。output_path相对会话 cwd 解析编解码由路径后缀大小写不敏感推断以.wav结尾表示 WAV其余一律按 MP3 处理tts.ts。读取providers.tts默认auto决定路由local/xai/deepinfra/auto。本地合成忽略单次调用的voice_id、language、sample_rate、bit_rate使用设置tts.localModel与tts.localVoice通过共享的 ONNX 小模型 Worker 调用 Kokoro-82Mkokoro-js把 Float32 PCM 编码为 PCM16 WAV 后落盘。xAI 合成解析 Grok Voice 凭据 → 调用baseURL/tts→ 将云端返回的字节直接写入文件。仅当 WAV 容器、采样率或 MP3 比特率与 xAI 默认值不一致时payload 才会显式携带output_format对齐 Hermes 的tts_tool.py行为见 tts.ts。DeepInfra 合成解析 DeepInfra API Key → POST{ model, input, response_format, voice? }到https://api.deepinfra.com/v1/openai/audio/speech模型固定为hexgrad/Kokoro-82M→ 字节直接写盘voice仅在调用方显式设置voice_id时才转发。本地后端Kokoro-82M 与语音目录模型注册表本地语音目录 packages/coding-agent/src/tts/models.ts 定义了TtsLocalModelSpec与TtsLocalVoiceSpec两个核心接口注册表当前只有一个模型键keyHugging Face 仓库默认精度采样率默认语音kokoroonnx-community/Kokoro-82M-v1.0-ONNXq824000 Hzaf_heartdtype默认q8约 100 MB 权重CPU 推理较快可通过providers.tinyModelDtype/PI_TINY_DTYPE覆盖。本地模型通过kokoro-js的KokoroTTS.from_pretrained加载运行在与其余 tiny-model 栈相同的huggingface/transformersonnxruntime运行时之上并打包 Kokoro 所需的 misaki/espeak 音素器见 models.ts 注释。关键设计一个模型覆盖全部语音/口音语言选择等价于语音选择无需额外下载。内置语音目录Kokoro 自带约 28 个语音项目精选了 12 个较高评级的美式/英式 × 女声/男声af_heartA 级为默认美式女声af_heart默认、af_bella、af_nicole、af_aoede、af_kore、af_sarah美式男声am_michael、am_fenrir、am_puck英式女声bf_emma英式男声bm_george、bm_fable完整列表见 models.ts。语音切换完全在设备端进行权重缓存后切换语音无需任何网络请求。本地合成实现细节本地路径由synthesizeLocal实现tts.ts模型键从tts.localModel读取仅当命中注册表时才采用否则回退默认kokoro语音从tts.localVoice读取未设置时回退af_heart。通过ttsClient.synthesize(modelKey, text, { voice, signal })请求 WorkerWorker 返回{ pcm: Float32Array, sampleRate }。本地输出恒为 WAVresolveLocalWavPath会把非.wav的目标路径改写成同目录同名.wav例如speech.mp3→speech.wav并在结果文本中明确说明替代。函数实现见 tts.ts。WAV 封装由 packages/coding-agent/src/tts/wav.ts 的encodeWav完成不依赖外部编码器手写 44 字节 RIFF/WAVE 头 小端有符号 16 位采样量化前先 clamp 到 [-1, 1] 防止越界回绕。本地 Worker 客户端packages/coding-agent/src/tts/tts-client.ts 的TtsClient管理本地合成懒启动 Worker#ensureWorker()首次请求时通过隐藏子命令__omp_worker_tts拉起子进程createTtsSubprocess支持引用计数ref/unref——空闲 Worker 被unref以免阻塞进程退出存在在途请求时才ref#syncWorkerRef。synthesize单次合成接受AbortSignal取消时 Promise 以null收尾。synthesizeStream流式合成会话push/end喂入完整可读片段chunks逐段产出音频供播放/演讲链路使用。downloadModel显式下载模型支持onProgress进度回调。单次工具调用的本地合成单发执行、不输出流式进度不触发onUpdate与文档一致。云端后端xAI Grok Voice 与 DeepInfraxAI 后端常量默认值voiceeve、languageen、sample rate24000、bit rate128000tts.ts非.wav路径请求 MP3。内置语音描述中列出ara、eve、leo、rex、sal同时接受自定义 voice IDtts.ts。凭据resolveXAIHttpCredentials(ctx.modelRegistry)解析 Grok Voice 凭据失败时返回错误文本No xAI credentials. Run /login → xAI Grok OAuth (SuperGrok or X Premium) or set XAI_API_KEY.。output_format仅在偏离默认时发送请求 WAV、或采样率 ≠ 24000、或 MP3 且比特率 ≠ 128000tts.ts。DeepInfra 后端端点https://api.deepinfra.com/v1/openai/audio/speech默认模型hexgrad/Kokoro-82Mtts.ts。payload 形如{ model, input, response_format, voice? }response_format取wav或mp3voice仅在调用方设置voice_id时加入否则使用服务端默认语音语音 ID 与模型相关见 tts.ts。凭据getApiKeyForProvider(deepinfra, sessionId)缺失时返回No DeepInfra credentials. Run /login → DeepInfra or set DEEPINFRA_API_KEY.。共享的云端请求管道两条云端路径共用postSpeechRequesttts.tsBearer 认证Authorization: Bearer key JSON body User-Agent。60 秒超时护栏AbortSignal.timeout(60_000)与调用方信号合并AbortSignal.any。HTTP 非 2xx 时把 provider 详情截断到前 300 字符并包装为ProviderHttpError最终映射为错误字符串其他异常原样抛出。输出契约Outputs成功时返回标准AgentToolResultcontent[0].type textcontent[0].text形如Saved bytes bytes to path (voicevoice, codeccodec, backendbackend...)——本地后端会附带采样率替换容器时还会追加 No local MP3 encoder is bundled, so WAV (PCM16) was written instead of the requested container. 的说明details { bytes, voiceId, codec, backend }其中voiceId本地为模型键/语音如kokoro/af_heartDeepInfra 未设voice_id时为default。错误情形xAI 或 DeepInfra 缺凭据、云端 HTTP 失败、本地 Worker 返回null返回isError: true仅含一个文本块且不带details其余异常调用方取消、60 秒云端超时、文件写入错误、本地 Worker 抛错则向上传播不会被包装成isError结果——这是消费方需要注意的边界。副作用、限制与错误速查Side Effects文件系统写入output_path本地合成收到非 WAV 目标时改写到同目录.wav兄弟路径。网络xAI 后端调用配置的 Grok Voice HTTP 端点DeepInfra 调用api.deepinfra.com本地后端仅可能在首次时通过 tiny-model 栈下载/缓存模型权重。会话状态读取 cwd、模型注册表以及设置providers.tts、tts.localModel、tts.localVoice。后台任务/取消云端调用有 60 秒超时本地合成接收调用方 abort 信号。流式/更新合成是单发执行不发送onUpdate进度事件。Limits Caps文本 Schema 上限1..15_000个 JavaScript 字符串字符。xAI 默认voiceeve、languageen、sample rate24000、bit rate128000非.wav路径请求 MP3。DeepInfra 默认模型hexgrad/Kokoro-82M未设voice_id时采用服务端默认语音。xAI 内置语音ara、eve、leo、rex、sal接受自定义 voice ID。本地默认模型kokoroonnx-community/Kokoro-82M-v1.0-ONNXq8默认语音af_heart。Errors 一览场景行为缺少 xAI 凭据isError: trueNo xAI credentials. Run /login → xAI Grok OAuth (SuperGrok or X Premium) or set XAI_API_KEY.缺少 DeepInfra 凭据isError: trueNo DeepInfra credentials. Run /login → DeepInfra or set DEEPINFRA_API_KEY.云端 HTTP 失败isError: truexAI TTS|DeepInfra TTS failed (status): detaildetail 最多 300 字符本地 Worker 返回nullisError: true提示模型键可能是 Worker 不可用或模型下载中断调用方取消 / 60s 超时 / 写盘错误 / Worker 抛错直接向上传播不包装成isError关键注意事项Notes本地 MP3 有意不内置请求speech.mp3时本地后端会写入speech.wav并在工具结果里明确说明替代行为只有auto xAI 凭据存在时MP3 请求才会被路由到云端真正产出 MP3。voice_id与language是 xAI payload 字段本地语音选择来自设置tts.localVoice因此模型调用无需在每次调用时枚举本地语音 ID这是把语音选择放在配置层而非参数层的设计考量docs/tools/tts.md Notes 段。快速上手配置建议想让 Agent 能生成语音文件第一步开启speechgen.enabled true默认关闭追求零成本、离线、隐私优先 →providers.tts local仅需确保首次运行时能从 tiny-model 栈拉取onnx-community/Kokoro-82M-v1.0-ONNXq8权重之后完全本地合成输出 WAV/PCM16需要 MP3 容器或更高音质 → 配置 xAI Grok OAuthSuperGrok / X Premium或XAI_API_KEY或设置DEEPINFRA_API_KEY走 DeepInfra只想按需使用、不想手动选后端 → 保持providers.tts auto本地优先、必要时自动借道 xAI 产出 MP3本地音色偏好通过tts.localVoice在af_heart等 12 个精选语音中挑选设置 UI 位于 Providers → Services。以上所有行为均可对照源码验证路由逻辑见 tts.ts 与测试 tts-backend.test.ts本地模型与语音见 models.tsWorker 客户端见 tts-client.tsWAV 编码见 wav.ts设置项见 settings-schema.ts。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考