VoiceStudio v0.5.6：从桌面生成到本地语音 API
如果程序里需要把文字变成语音，可以把 VoiceStudio 看成一套带桌面工作区的本地语音服务：先在界面确认引擎与声音可用，再通过 HTTP 接口提交文字、取得音频。桌面负责模型管理和试听，脚本负责把这一步接进自己的流程。
本文按 v0.5.6 的接口源码和文档整理，目标是在自己的环境中完成一段短语音的调用。下面给出待执行的步骤与检查方法，性能和音质需要在实际设备上验证。
1. 先让桌面环境可用
本版 Windows 发行物是 x64 EXE，Linux x64 有 AppImage、DEB，macOS 有两种架构的包。发布说明注明安装器未签名或临时签名、macOS 未公证，安装时可能出现系统信任提示。Intel Mac 的本地 Python 后端不受支持，需连接其他机器的后端，不能用界面能打开证明本地推理可用。
首次启动若尚无兼容后端，程序等待用户确认 Install local runtime。选择运行环境位置后，安装器检查写入权限与至少九 GiB 的磁盘空间，再安装依赖。模型安装是后续的独立动作，需要额外容量。
Settings → Models 区分 TTS、识别与翻译，文字转语音先准备 TTS 引擎。
进入 Voice cloning，选择保存的声音或准备参考录音，输入一段短文，生成并试听。先把桌面路径跑通，再调用接口：这样如果请求失败，可以判断是程序访问问题，还是模型本身没有准备好。
默认 OmniVoice 的常规 GPU 路径建议六 GB 左右的专用显存。CPU 或小显存设备可以了解 GGUF 路径，选择前同时核对设备支持、模型许可和等待时间。接口调用沿用同一推理后端，硬件要求与桌面生成一致。
2. 确认后端地址
文档中的默认后端地址是本机 3900 端口。如果设置了其他端口或连接远程后端，以应用实际地址为准。以下命令在 Windows PowerShell 使用 curl.exe，避免与旧版 PowerShell 的同名命令混淆。
curl.exe -fS http://127.0.0.1:3900/.well-known/voicestudio-speech
curl.exe -fS http://127.0.0.1:3900/v1/models
curl.exe -fS http://127.0.0.1:3900/v1/audio/voices发现接口返回语音服务能力，模型接口返回客户端可识别的模型信息。它们适合确认请求是否到达后端，但列表里出现模型名，不代表权重已经安装，也不证明这台机器完成过推理。
如果连接被拒绝，先确认 VoiceStudio 仍在运行、运行环境安装已完成，以及地址没有改动。程序通过本地后端提供服务；模型尚在下载时，也不要把等待直接归为 HTTP 接口故障。
3. 提交文字，保存一段 WAV
先把请求体写入 UTF-8 文件，再发送。这样中文文字与引号不必穿过多层命令行转义，后续也能保留输入样本用于排查。
@'
{
"model": "tts-1",
"voice": "default",
"input": "这是一次本地语音接口检查。请确认开头和结尾都能听清。",
"language": "zh",
"response_format": "wav"
}
'@ | Set-Content -Encoding utf8 speech.json
curl.exe -fS http://127.0.0.1:3900/v1/audio/speech `
-H "Content-Type: application/json" `
--data-binary "@speech.json" `
--output demo.wav这里的 tts-1 是兼容名称，会映射到当前语音引擎，并不会因此调用 OpenAI 云端。default 使用引擎默认声音；如果要使用保存的克隆声音，从 /v1/audio/voices 返回列表中找到 type 为 profile、名字对应的条目，将它的 voice_id 填入请求的 voice。更换声音时保持 input 不变，便于比较请求是否按预期选中了声音。
v0.5.6 也接受若干 OpenAI 风格的声音名称，但这些名称映射到本地引擎的默认声音，并不提供同名云端声音。兼容解决的是请求结构与客户端接入，具体声音仍来自 VoiceStudio 的引擎和声音档案。
接口源码把 input 限为最多四千零九十六个字符。长文不能把全文直接塞入这个示例。实际应用需要按句段组织请求并保存顺序，或使用桌面的 Audiobook、Stories 长文工作流，保留章节、人物和导出设置。
4. 检查输出，再接入后续任务
请求成功之后，先用播放器打开 demo.wav，确认从头到尾都有声音，文字没有漏掉，关键发音符合预期。文件存在、扩展名正确和音频能完整播放，是三个不同检查。
上面的 -fS 会在 HTTP 错误时返回失败。遇到失败先查看终端中的状态，不要把遗留文件当作新结果。重新请求前可以换一个输出文件名，或者核对修改时间，避免后续流程误用上一次生成的音频。
需要 MP3 时可以改 response_format。v0.5.6 的发布说明明确修正了音频格式行为；压缩格式需要编码器，缺少编码器会报错。初次排查采用 WAV，能少引入一层格式依赖，再考虑是否转换为适合分发的格式。
把这个接口接进应用时，建议记录文字输入、实际后端地址、模型选择、声音 ID 与输出路径。一次只调整一个影响生成的参数，才能区分发音问题、声音选择问题和设备等待问题。首次加载权重与之后的生成耗时也应分别观察。
5. 智能体接入走 MCP
如果调用方是支持 MCP 的智能体，可以使用后端挂载的 /mcp/ 入口。桌面 Integrations 能导出客户端配置，优先使用应用生成的当前地址，避免手工配置时端口和路径不同步。
MCP 提供生成语音、克隆、转写和列出声音等工具。输出可配置为文件模式，将音频保存到指定边界目录，并返回路径与访问地址，减少把整段音频以 Base64 塞进模型上下文的开销。
文件路径由后端解释。客户端与后端若处在不同机器或容器中，后端返回的路径未必能被客户端直接读取；需要共享目录或使用返回的音频地址。这个区别要在接入播放器或处理工具前解决，不能因为工具返回成功就认定文件在客户端本地。
v0.5.6 修正了部分旧配置使用裸 /mcp 时的连接问题，新配置仍优先使用带末尾斜杠的 /mcp/。接入现有客户端后，先查询健康状态与可用声音，再执行一段短语音，逐步验证配置、模型与文件访问。
6. 从演示进入实际使用
VoiceStudio 应用采用 AGPL-3.0，模型采用独立许可。默认 OmniVoice 预训练权重在项目说明中标为 CC-BY-NC，应用可商业使用不能替代权重的商业使用条件。实际产品接入前，按选中的模型及其相关组件分别核对。
一条值得保留的验证路径是：桌面能生成 → 后端地址能访问 → 短请求成功 → 音频完整播放 → 保存声音可复用 → 最后接入批量流程。每一步都留下一份可检查的输入与输出，后续故障就不必从所有配置一起猜起。
来源与下载
下载链接
进入 VoiceStudio → v0.5.6，按平台和架构选择对应包；模型需在应用内另行准备。