基于Qwen3-TTS的本地语音合成服务器，兼容OpenAI Audio API
- 🎯 兼容OpenAI API - 支持
/v1/audio/speech端点，可直接使用OpenAI SDK - 🚀 极低延迟 - 基于Qwen3-TTS的流式架构(尚不支持流式输出)
- 🌍 多语言支持 - 支持10种主要语言（中英日韩德法俄葡西意）
- 🎨 智能音色控制 - 自然语言指令控制情感、语速、韵律
- 🔧 类Ollama架构 - 简洁的CLI工具 + 本地模型管理
- 🐳 易于部署 - 支持Docker一键部署，完全离线运行
# 安装 uv (如果尚未安装)
curl -LsSf https://astral.sh/uv/install.sh | sh
# 克隆仓库
git clone https://github.com/Harrison3-1122/zTTS.git
cd zTTS
# 使用 uv 同步环境并安装依赖
uv sync# 使用 uv 运行 ztts 命令下载标准模型
uv run ztts model pull Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice
# 下载高清模型
uv run ztts model pull Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice
# 下载音色克隆基础模型
uv run ztts model pull Qwen/Qwen3-TTS-12Hz-1.7B-Base# 启动服务器（默认端口8000）
uv run ztts serve
# 自定义端口和模型
uv run ztts serve --port 8080 --model Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoicecurl -X POST http://localhost:8000/v1/audio/speech \
-H "Content-Type: application/json" \
-d '{
"model": "Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice",
"input": "你好，这是一个测试。",
"voice": "alloy",
"response_format": "mp3"
}' \
--output speech.mp3from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8000/v1",
api_key="dummy" # 未启用鉴权时可用任意字符串
)
response = client.audio.speech.create(
model="Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice",
voice="alloy",
input="The quick brown fox jumps over the lazy dog."
)
response.stream_to_file("speech.mp3")import httpx
async with httpx.AsyncClient() as client:
response = await client.post(
"http://localhost:8000/v1/audio/speech",
json={
"model": "Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice",
"input": "Hello, world!",
"voice": "alloy",
"response_format": "mp3",
"speed": 1.0
}
)
with open("output.mp3", "wb") as f:
f.write(response.content)zTTS 自带内置的 Web UI 界面，方便用户直接在浏览器中测试各种模型和音色。
- 位于:
/playground - 功能:
- 实时文本转语音调试
- 内置常用音色预览
- 支持自定义模型 ID
- 各种音频参数（语速、格式等）可视化调节
生成语音音频。
请求参数：
| 参数 | 类型 | 必需 | 说明 |
|---|---|---|---|
model |
string | 是 | 模型ID，如 Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice 或 Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice |
input |
string | 是 | 要转换的文本，最大4096字符 |
voice |
string | 是 | 音色：alloy/echo/fable/onyx/nova/shimmer |
response_format |
string | 否 | 音频格式：mp3/opus/aac/flac/wav/pcm（默认mp3） |
speed |
number | 否 | 语速：0.25-4.0（默认1.0） |
响应：
- Content-Type:
audio/mpeg（或对应格式） - Body: 二进制音频数据
使用Qwen3-TTS原生音色和情感控制。
额外参数：
speaker: Qwen3原生说话人ID（如Vivian/Ryan等）language: 明确指定语言（Chinese/English等）instruct: 情感/风格指令（如"用愤怒的语气说"）
使用自然语言描述生成自定义音色。注意：此接口要求使用 VoiceDesign 后缀的模型。
参数：
instruct: 音色描述（如"年轻女性，温柔甜美"）
提供参考音频进行零样本音色克隆。注意：此接口要求使用 Base 后缀的模型。
参数：
ref_audio: 参考音频，支持音频 URL 或 Base64 Data URI（如data:audio/wav;base64,...）ref_text: 参考音频对应的文本内容（当x_vector_only_mode为false时必填）x_vector_only_mode: 布尔值，设为true则仅提取音色特征，不处理文本对齐（质量略低但不需要提供ref_text）
列出所有可用的模型 ID 及其信息。
获取服务器当前运行状态、已加载的模型列表以及硬件设备信息。
简单的健康检查，返回系统在线状态。
# 启动服务
ztts serve --host 0.0.0.0 --port 8000
# 指定默认模型
ztts serve --model Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice
# 指定设备
ztts serve --device cuda # 或 cpu# 列出本地模型
ztts model list
# 下载模型
ztts model pull Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice
ztts model pull Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice
# 删除模型
ztts model rm Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice# 查看配置
ztts config show
# 设置配置
ztts config set default_model Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice默认使用 .env 或环境变量，前缀为 ZTTS_。
鉴权与限流（可选）：
# 启用鉴权（Authorization: Bearer <key> 或 X-API-Key）
export ZTTS_ENABLE_AUTH=true
export ZTTS_API_KEYS='["key1","key2"]'
# 启用限流（按客户端 IP 统计，每分钟请求数）
export ZTTS_RATE_LIMIT_ENABLED=true
export ZTTS_RATE_LIMIT_RPM=60# 构建镜像
docker build -t ztts:latest .
# 运行容器
docker run -d \
--name ztts \
--gpus all \
-p 8000:8000 \
-v ~/.cache/ztts:/app/models \
ztts:latest
# 使用docker-compose
docker-compose up -dzTTS/
├── ztts/ # 核心包
│ ├── api/ # API层（FastAPI）
│ ├── core/ # 业务逻辑
│ ├── models/ # 模型封装
│ ├── cli/ # CLI工具
│ ├── config/ # 配置管理
│ └── utils/ # 工具模块
├── playground/ # Web UI
├── tests/ # 测试
├── docs/ # 文档
├── examples/ # 示例代码
├── Dockerfile # Docker 构建文件
└── docker-compose.yml # Docker Compose 配置
本项目采用MIT许可证 - 查看LICENSE文件了解详情。
使用 Antigravity 氛围开发🚀🌚