DiaMoE-TTS — IPA to Speech API

输入 IPA 音标，返回 MP3 语音。基于 espeak-ng 引擎，支持中文普通话、粤语、英语等多种语言。

快速开始

1. 安装 espeak-ng

系统	安装方式
Windows	下载安装 espeak-ng，默认路径 C:\Program Files\eSpeak NG\
Mac	brew install espeak-ng
Linux	sudo apt install espeak-ng 或 sudo yum install espeak-ng

2. 安装 Python 依赖

pip install -r requirements.txt

如需 MP3 输出，还需安装 ffmpeg（下载）。仅需 WAV 可跳过。

3. 启动服务

python api_server.py --host 0.0.0.0 --port 8000

Windows 用户可双击 run_api.bat

服务启动后访问 http://localhost:8000/health 确认运行正常。

---

API 接口

健康检查

GET /health

返回：

{"ok": true, "engine": "espeak-ng"}

---

IPA 转语音（核心接口）

POST /api/v1/tts/ipa
Content-Type: application/json

请求参数

参数	类型	必填	默认值	说明
ipa	string	是	—	IPA 音标 / 拼音文本
voice	string	否	"zh"	语音语言
speed	int	否	140	语速 80–450
output_format	string	否	"mp3"	"wav" 或 "mp3"

voice 可选值

值	语言
zh / cmn	普通话
cmn-latn-pinyin	普通话（拼音输入）
yue	粤语
en	英语
en-us	美式英语
ja	日语
ko	韩语
其他	运行 espeak-ng --voices 查看全部

IPA 输入格式

支持以下三种输入方式（效果相同）：

方式一：标准 IPA + 五度调值

{"ipa": "n i˨˩˦ x au˨˩˦"}

方式二：简化 IPA（无声调）

{"ipa": "ni xau"}

方式三：拼音 + 数字声调

{"ipa": "ni3 hao3"}

返回

{
  "audio_path": "/path/to/outputs/api/abc123.mp3",
  "audio_url": "/api/v1/audio/abc123.mp3",
  "output_format": "mp3",
  "sample_rate": 22050,
  "ipa_input": "n i˨˩˦ x au˨˩˦",
  "espeak_input": "[[n i x au]]",
  "voice": "zh",
  "speed": 140
}

---

下载音频

GET /api/v1/audio/{filename}

返回 audio_url 中提供的 {filename} 即可下载。

---

调用示例

curl

# 普通话 "你好"
curl -X POST http://localhost:8000/api/v1/tts/ipa \
  -H "Content-Type: application/json" \
  -d '{"ipa": "ni3 hao3"}'

# 粤语 "你好"
curl -X POST http://localhost:8000/api/v1/tts/ipa \
  -H "Content-Type: application/json" \
  -d '{"ipa": "nei5 hou2", "voice": "yue"}'

# 英语 "Hello world"
curl -X POST http://localhost:8000/api/v1/tts/ipa \
  -H "Content-Type: application/json" \
  -d '{"ipa": "h@l@U w3:ld", "voice": "en"}'

Python

import requests

# 调用接口
resp = requests.post("http://localhost:8000/api/v1/tts/ipa", json={
    "ipa": "n i˨˩˦ x au˨˩˦",
    "voice": "zh",
    "speed": 140,
    "output_format": "mp3",
})
data = resp.json()

# 下载音频
audio = requests.get(f"http://localhost:8000{data['audio_url']}")
with open("output.mp3", "wb") as f:
    f.write(audio.content)

命令行测试工具

# 直接指定 IPA
python test_api.py --ipa "ni3 hao3"

# 交互式输入
python test_api.py

# 指定输出和语音
python test_api.py --ipa "hello" --voice en --output hello.mp3

---

项目结构

├── api_server.py      # API 服务主文件
├── test_api.py        # 命令行测试客户端
├── run_api.bat        # Windows 一键启动
├── run_api.sh         # Linux/Mac 一键启动
├── requirements.txt   # Python 依赖
└── outputs/api/       # 生成的音频文件目录

---

环境变量

变量	说明
ESPEAK_NG_PATH	espeak-ng 可执行文件路径（非默认路径时设置）

---

FAQ

Q: 报错 "espeak-ng not found"？ A: 先安装 espeak-ng，或设置 ESPEAK_NG_PATH 环境变量指向 exe 文件。

Q: MP3 输出报错？ A: 需要安装 ffmpeg 并添加到系统 PATH。或改用 "output_format": "wav"。

Q: 音质如何？ A: espeak-ng 是共振峰合成器，音质类似机器人，但发音清晰可辨。适合语音学研究、辅助阅读等场景。