wicos/eetts repository overview

⁠eetts

eetts 是一个面向自托管场景的轻量级 Edge TTS HTTP 服务。它将 Microsoft Edge 的在线文本转语音能力封装为简单的 REST API，可用于家庭语音助手、聊天机器人、自动化流程和其他需要生成 MP3 语音的服务。

它默认提供中文语音，支持 Docker 一键部署、Bearer/API Key 鉴权、请求校验、超时与重试、并发保护及临时文件自动清理。项目重点是小而稳定，适合在 NAS、小主机或普通云服务器上长期运行。

⁠主要特性

• 简单的 GET /tts 与 POST /tts 接口，直接返回 MP3 音频。
• 默认使用 zh-CN-XiaoxiaoNeural，并可通过 /voices 查询可用语音。
• 支持 Bearer Token 和 X-API-Key；旧版 query/body token 仍可兼容。
• 对文本长度、语速、音量和音调进行严格校验。
• 内置上游超时、指数退避重试和并发限制，避免请求堆积拖垮实例。
• 每个请求使用独立文件名，响应完成后立即清理，并定期清除异常退出遗留文件。
• 非 root 容器、健康检查、多架构镜像和固定生产依赖。
• 支持 linux/amd64 与 linux/arm64。

⁠快速开始

先生成一个足够长的随机 Token，然后启动容器：

docker run -d \
  --name eetts \
  --restart unless-stopped \
  -p 8000:8000 \
  -e TOKEN='replace-with-a-long-random-token' \
  wicos/eetts:latest

容器启动后可以访问：

• 健康检查：http://localhost:8000/healthz
• OpenAPI 文档：http://localhost:8000/docs
• ReDoc 文档：http://localhost:8000/redoc

生产环境建议使用固定版本，例如 wicos/eetts:1.1.0，以避免升级时自动切换到行为有变化的新版本。

⁠API 使用

⁠生成语音

推荐使用 Bearer Token：

curl --get -o speech.mp3 \
  -H 'Authorization: Bearer replace-with-a-long-random-token' \
  --data-urlencode 'text=你好，世界' \
  --data-urlencode 'voice=zh-CN-XiaoxiaoNeural' \
  --data-urlencode 'rate=-10' \
  http://localhost:8000/tts

POST JSON 示例：

curl -o speech.mp3 \
  -H 'X-API-Key: replace-with-a-long-random-token' \
  -H 'Content-Type: application/json' \
  -d '{"text":"你好，世界","voice":"zh-CN-XiaoxiaoNeural","rate":0,"volume":0,"pitch":0}' \
  http://localhost:8000/tts

⁠查询语音列表

curl \
  -H 'Authorization: Bearer replace-with-a-long-random-token' \
  http://localhost:8000/voices

⁠接口概览

/tts 支持以下参数：

为兼容旧客户端，?token=... 和 JSON 中的 token 字段仍然可用。新部署应优先使用请求头，避免 Token 出现在访问日志和浏览器历史中。

⁠Docker 镜像标签

同一版本出现多个标签是有意设计的，它们当前指向同一个镜像摘要，但升级策略不同：

例如当前 1.1 和 1.1.0 内容相同；未来发布 1.1.1 时，1.1 会更新，而 1.1.0 不会变化。

⁠配置

⁠本地开发

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt
TOKEN=development-only OUTPUT_DIR=./output uvicorn eetts:app --reload

运行检查：

ruff check .
pytest -q
docker build -t eetts:local .

⁠发布维护

Publish Docker image 工作流为 GitHub v* 标签构建并推送多架构镜像。仓库需要配置：

• Secret DOCKERHUB_USERNAME：Docker Hub 登录用户名。
• Secret DOCKERHUB_TOKEN：具有写权限的 Docker Hub Personal Access Token。
• Variable DOCKERHUB_IMAGE：完整镜像名称，例如 wicos/eetts。

Sync Docker Hub description 工作流会将本 README 同步到 Docker Hub 项目主页。发布新版本时，需要更新 eetts.py 中的 VERSION 和 CHANGELOG.md⁠。CI 成功后，发布工作流会创建相应的 Git 标签和 GitHub Release，并请求 Docker 镜像构建。

⁠License

MIT⁠