edgeTTS 自托管语音合成 API
内容提要
edgeTTS 是轻量级自托管语音合成服务，调用微软 Edge 在线朗读接口，提供 HTTP API 与 Web 工作台，支持流式传输、音色检索和 MP3 导出。长文本按段落、换行、句子智能切片，单次上限 2 万码点，并设有并发与限流保护。项目以单个 Fastify 进程托管前后端，用 Bearer Token 鉴权，官方提供 Docker 镜像，推荐配合反向代理部署。
延伸解读
部署与安全配置要点
edgeTTS 推荐使用 Docker 部署，官方镜像适配 linux/amd64 与 linux/arm64。compose 示例中启用了只读文件系统、丢弃所有能力、禁止提权等安全选项，并默认要求 API_KEY，缺失时容器拒绝启动。服务默认绑定 127.0.0.1:8080，公网部署需通过反向代理提供 HTTPS。注意 Compose 仅透传 environment 中声明的字段，完整参数需参考配置文档。
反向代理必须禁用缓冲
由于合成接口采用流式传输，反向代理若开启响应缓冲会大幅增加首字延迟。Caddy 配置中需对 /api/speech 和 /v1/audio/speech 设置 flush_interval -1；Nginx 则需设置 proxy_buffering off 和 proxy_cache off，并适当延长 proxy_read_timeout。常规路由（Web 工作台、静态资源、健康检查）无需特殊处理。
接口选择与参数限制
OpenAI 兼容接口 /v1/audio/speech 仅接受 model、voice、input、response_format、speed 五个字段，input 上限 4096 个 UTF-16 代码单元，voice 必须为完整 Edge 音色 ID，不支持 alloy 等预设名。原生长文本接口 /api/speech 支持最多 20000 个 Unicode 码点，并可调节语速、音调半音和音量。长文本会按段落、换行、句子、空白优先级切分为每段不超过 300 码点的片段，串行合成并流式回传。
错误处理与限流机制
音频流发送前出错会返回标准 JSON 错误体；传输中途出错则强制中断连接，因此收到 HTTP 200 并不保证音频完整，客户端遇到流截断应废弃未完成音频并重试。常见状态码包括 400（音色无效）、401（鉴权失败）、429（频率限制）、502（上游异常）、503（并发队列满或排队超 30 秒）。默认两条合成接口共享每 10 秒 12 次请求的配额，音色查询为每分钟 60 次，可通过环境变量调整。
Q&A
edgeTTS 是什么？它底层调用的是什么接口？
edgeTTS 是一个轻量级自托管语音合成（TTS）服务，底层调用微软 Edge 的在线朗读接口。它提供开箱即用的 HTTP API 与基于浏览器的 Web 工作台，支持音频流式传输、音色检索、MP3 音频导出，以及最高 20,000 个 Unicode 码点的长文本无缝合成。
edgeTTS 的长文本切片规则是什么？单次合成上限是多少？
两条合成接口均遵循「段落 > 换行 > 句子 > 空白」的优先级规则，将长文本智能切分为每段不超过 300 码点的片段；所有分段共用单一上游连接与单个 HTTP 响应，按序串行合成并流式回传。分段逻辑不篡改原文，纯空白段落自动忽略。单次请求支持最多 20,000 个 Unicode 码点。
edgeTTS 的并发和限流保护是如何设计的？
单进程默认允许最多 4 个活跃合成流，并配备 16 个 FIFO 排队槽位。当队列满员或排队超过 30 秒时，快速失败并返回 503 SERVER_BUSY。单个长文本请求在整个生命周期内仅占用一个并发许可；若客户端中途断开，服务端会立即掐断上游连接并归还许可。两条合成接口默认共享单进程每 10 秒 12 次请求的配额；音色查询接口配额为每分钟 60 次。
如何用 Docker 部署 edgeTTS？需要配置哪些关键环境变量？
官方提供适配 linux/amd64 与 linux/arm64 的预构建 Docker 镜像，推荐使用 Docker 自托管部署。创建部署目录并编写 compose.yaml，关键环境变量包括：API_KEY（必须设置，否则容器拒绝启动）、REQUIRE_API_KEY（默认为 true）、SPEECH_RATE_LIMIT_MAX 与 SPEECH_RATE_LIMIT_WINDOW_MS（用于自定义频控）。服务默认绑定在 127.0.0.1:8080。
edgeTTS 的 OpenAI 兼容接口支持哪些参数？有什么限制？
OpenAI 兼容接口 /v1/audio/speech 仅接受 model、voice、input、response_format、speed 五个字段，传入未知字段将抛出参数错误。model 支持 tts-1（48 kbps MP3）与 tts-1-hd（96 kbps MP3），仅作为码率标识；voice 必须为完整的 Edge 音色 ID，不支持直接映射 alloy 等 OpenAI 原生预设名；input 单次输入上限为 4,096 个 UTF-16 代码单元。
edgeTTS 在反向代理后部署时需要注意什么？
由于合成接口采用流式传输，反向代理必须禁用响应缓冲，否则会导致首字延迟大幅增加。例如 Caddy 配置中需对 /api/speech 和 /v1/audio/speech 路径设置 flush_interval -1；Nginx 配置中需对相应 location 设置 proxy_buffering off 和 proxy_cache off。
edgeTTS 的鉴权方式是什么？API Key 如何传递？
edgeTTS 采用 Bearer Token 进行鉴权。受保护接口均需在 Header 中携带 Token：Authorization: Bearer <API_KEY>，不支持通过 Query 参数传递密钥。Web 工作台输入的 API Key 仅保存在当前页面的运行时内存中，不会写入 localStorage、Cookie 或 URL Query，页面刷新后需重新填入。
edgeTTS 合成过程中出错会怎样？常见错误状态码有哪些？
音频流发送前出错会返回标准 JSON 错误体；音频流传输中途出错则连接强制中断，因此收到 HTTP 200 并不代表音频文件一定完整传输，客户端遇到流截断时应废弃未完成的音频并重试。常见状态码：400 UNKNOWN_VOICE（音色不在缓存列表）、401 UNAUTHORIZED（未提供鉴权头或 API Key 无效）、429 RATE_LIMITED（触发频率限制）、502 UPSTREAM_ERROR（上游微软网络异常或合成失败）、503 SERVER_BUSY（并发队列已满或排队超过 30 秒）。
