mirror of
https://github.com/RVC-Boss/GPT-SoVITS.git
synced 2026-07-04 13:01:09 +08:00
735b2e3554
- Add simple_api.py: profile-based API that wraps GPT-SoVITS TTS engine - Add /api/tts endpoint for MVP: accepts ref audio/video, text, optional aux audio - Frontend auto-extracts audio from uploaded video files via Web Audio API - Add emotion presets (neutral/happy/calm/sad/angry) with speed customization - Add test_frontend/index.html with health check, audio playback, and download - Add contract tests (7 tests, all passing) using mock TTS pipeline - Add documentation: simple_api.md (full tutorial), simple_api_quickstart.md - Add startup scripts: go-simple-api.ps1, go-simple-api.bat, open-test-frontend.ps1 - Add soundfile and python-multipart to requirements.txt - Text splitting fixed to cut5 (punctuation-based) per MVP spec
321 lines
6.7 KiB
Markdown
321 lines
6.7 KiB
Markdown
# GPT-SoVITS 简化接口教程
|
||
|
||
本项目原本已经有 `api_v2.py`，但调用时需要传很多 GPT-SoVITS 参数。新增的 `simple_api.py` 是一个中间层，目标是让前端或业务方用更简单的方式调用。
|
||
|
||
当前 MVP 推荐使用：
|
||
|
||
```http
|
||
POST /api/tts
|
||
Content-Type: multipart/form-data
|
||
```
|
||
|
||
适合你的流程：
|
||
|
||
1. 前端从视频中提取音频（或直接上传已裁剪的 3-10 秒音频）。
|
||
2. 用户人工裁剪主参考音频到 3-10 秒。
|
||
3. 前端把主参考音频、要生成的文字、可选辅助音频提交给后端。
|
||
4. 后端调用 GPT-SoVITS 生成音频并返回。
|
||
|
||
## 1. 安装依赖
|
||
|
||
在 GPT-SoVITS 使用的 Python 环境里运行：
|
||
|
||
```bash
|
||
python -m pip install -r requirements.txt
|
||
```
|
||
|
||
本中间层额外需要：
|
||
|
||
- `python-multipart`：用于接收前端上传的音频文件。
|
||
- `soundfile`：用于读取音频信息和校验参考音频时长。
|
||
|
||
这两个依赖已经写入 `requirements.txt`。
|
||
|
||
## 2. 检查配置
|
||
|
||
配置文件：
|
||
|
||
```text
|
||
simple_api.yaml
|
||
```
|
||
|
||
常用配置：
|
||
|
||
```yaml
|
||
server:
|
||
host: 127.0.0.1
|
||
port: 9881
|
||
tts_config: GPT_SoVITS/configs/tts_infer.yaml
|
||
|
||
upload:
|
||
dir: runtime/uploads
|
||
min_ref_seconds: 3
|
||
max_ref_seconds: 10
|
||
max_upload_mb: 80
|
||
```
|
||
|
||
说明：
|
||
|
||
- `server.host`：后端监听地址。
|
||
- `server.port`：后端端口。
|
||
- `server.tts_config`：GPT-SoVITS 推理配置文件。
|
||
- `upload.dir`：临时上传目录。
|
||
- `upload.min_ref_seconds`：主参考音频最短秒数。
|
||
- `upload.max_ref_seconds`：主参考音频最长秒数。
|
||
- `upload.max_upload_mb`：单个上传音频最大体积。
|
||
|
||
当前默认后端地址：
|
||
|
||
```text
|
||
http://127.0.0.1:9881
|
||
```
|
||
|
||
## 3. 启动后端
|
||
|
||
进入项目目录：
|
||
|
||
```powershell
|
||
cd D:\tts\GPT-SoVITS
|
||
```
|
||
|
||
方式一：
|
||
|
||
```powershell
|
||
python simple_api.py -c simple_api.yaml
|
||
```
|
||
|
||
方式二，Windows PowerShell：
|
||
|
||
```powershell
|
||
.\go-simple-api.ps1
|
||
```
|
||
|
||
方式三，Windows 批处理：
|
||
|
||
```bat
|
||
go-simple-api.bat
|
||
```
|
||
|
||
启动成功后，后端会监听：
|
||
|
||
```text
|
||
http://127.0.0.1:9881
|
||
```
|
||
|
||
## 4. 健康检查
|
||
|
||
后端启动后，可以访问：
|
||
|
||
```text
|
||
http://127.0.0.1:9881/health
|
||
```
|
||
|
||
或者命令行测试：
|
||
|
||
```bash
|
||
curl http://127.0.0.1:9881/health
|
||
```
|
||
|
||
返回示例：
|
||
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"tts_config": "GPT_SoVITS/configs/tts_infer.yaml",
|
||
"version": "v2",
|
||
"languages": ["auto", "auto_yue", "en", "zh"]
|
||
}
|
||
```
|
||
|
||
## 5. 打开测试前端
|
||
|
||
后端启动后，推荐直接打开：
|
||
|
||
```text
|
||
http://127.0.0.1:9881/test/
|
||
```
|
||
|
||
这个页面已经挂载在后端服务里，不需要额外启动前端服务。
|
||
|
||
也可以直接打开本地文件：
|
||
|
||
```text
|
||
test_frontend/index.html
|
||
```
|
||
|
||
Windows 下也可以运行：
|
||
|
||
```powershell
|
||
.\open-test-frontend.ps1
|
||
```
|
||
|
||
测试前端里有一个“后端接口地址”输入框。
|
||
|
||
默认值：
|
||
|
||
```text
|
||
http://127.0.0.1:9881/api/tts
|
||
```
|
||
|
||
如果你修改了 `server.host` 或 `server.port`，记得同步修改页面里的接口地址。
|
||
|
||
## 6. MVP 接口
|
||
|
||
接口地址：
|
||
|
||
```http
|
||
POST /api/tts
|
||
```
|
||
|
||
请求类型：
|
||
|
||
```http
|
||
multipart/form-data
|
||
```
|
||
|
||
字段说明：
|
||
|
||
```text
|
||
text 必填。需要生成的文字。
|
||
ref_audio 必填。主参考音频（支持上传视频，前端会自动提取音频），要求 3-10 秒。
|
||
aux_ref_audio 可选。辅助参考音频，可以上传多个。
|
||
prompt_text 可选。主参考音频对应文字，可以留空。
|
||
text_lang 可选。生成文字语言，默认 zh。
|
||
prompt_lang 可选。参考音频语言，默认 zh。即使 prompt_text 为空，也需要传给 GPT-SoVITS 内部。
|
||
format 可选。返回格式，默认 wav。
|
||
emotion 可选。情绪 preset：neutral、happy、calm、sad、angry。
|
||
speed 可选。语速，对应 GPT-SoVITS 的 speed_factor。
|
||
seed 可选。随机种子，默认 -1。
|
||
```
|
||
|
||
## 7. curl 调用示例
|
||
|
||
PowerShell 示例：
|
||
|
||
```powershell
|
||
curl.exe -X POST http://127.0.0.1:9881/api/tts `
|
||
-F "text=你好，欢迎使用这个声音。" `
|
||
-F "ref_audio=@D:\audio\ref.wav" `
|
||
-F "prompt_text=" `
|
||
-F "text_lang=zh" `
|
||
-F "prompt_lang=zh" `
|
||
-F "emotion=neutral" `
|
||
--output output.wav
|
||
```
|
||
|
||
如果有辅助参考音频：
|
||
|
||
```powershell
|
||
curl.exe -X POST http://127.0.0.1:9881/api/tts `
|
||
-F "text=你好，欢迎使用这个声音。" `
|
||
-F "ref_audio=@D:\audio\ref.wav" `
|
||
-F "aux_ref_audio=@D:\audio\aux1.wav" `
|
||
-F "aux_ref_audio=@D:\audio\aux2.wav" `
|
||
-F "prompt_text=" `
|
||
-F "text_lang=zh" `
|
||
-F "prompt_lang=zh" `
|
||
--output output.wav
|
||
```
|
||
|
||
## 8. 重要规则
|
||
|
||
- 主参考音频必须是 3-10 秒。
|
||
- `aux_ref_audio` 是可选项。
|
||
- `prompt_text` 可以为空，但当前主要针对 GPT-SoVITS v2。
|
||
- 如果切到 GPT-SoVITS v3/v4，空 `prompt_text` 会被中间层直接返回 400。
|
||
- 生成文字固定使用 `cut5`，也就是按照标点符号切句。
|
||
- `emotion` 目前是轻量 preset，本质是映射到采样和语速参数；更稳定的情绪控制仍然依赖带情绪的参考音频。
|
||
|
||
## 9. 测试前端使用步骤
|
||
|
||
1. 启动后端。
|
||
2. 打开 `http://127.0.0.1:9881/test/`。
|
||
3. 检查“后端接口地址”是否为：
|
||
|
||
```text
|
||
http://127.0.0.1:9881/api/tts
|
||
```
|
||
|
||
4. 填写“需要生成的文字”。
|
||
5. 上传主参考音频。
|
||
6. 可选上传辅助参考音频。
|
||
7. 可选填写参考音频文字。
|
||
8. 选择语言、情绪、语速。
|
||
9. 点击“生成音频”。
|
||
10. 页面右侧会显示返回结果，可以在线播放和下载。
|
||
|
||
## 10. 其他接口
|
||
|
||
除了 MVP 上传接口，还保留了 profile 调用接口：
|
||
|
||
```http
|
||
GET /voices
|
||
GET /speak?text=hello&voice=default
|
||
POST /speak
|
||
POST /speak/base64
|
||
POST /v1/tts
|
||
POST /admin/reload-config
|
||
POST /admin/weights
|
||
```
|
||
|
||
这些接口适合后续做固定音色 profile，不是当前 MVP 的主流程。
|
||
|
||
## 11. Base64 返回示例
|
||
|
||
```bash
|
||
curl -X POST http://127.0.0.1:9881/speak/base64 ^
|
||
-H "Content-Type: application/json" ^
|
||
-d "{\"text\":\"hello\",\"voice\":\"default\"}"
|
||
```
|
||
|
||
返回格式：
|
||
|
||
```json
|
||
{
|
||
"media_type": "audio/wav",
|
||
"audio_base64": "..."
|
||
}
|
||
```
|
||
|
||
## 12. 添加固定音色 profile
|
||
|
||
如果后续要做固定音色，可以编辑 `simple_api.yaml`：
|
||
|
||
```yaml
|
||
voices:
|
||
default:
|
||
ref_audio_path: reference.wav
|
||
prompt_text: exact transcript
|
||
prompt_lang: zh
|
||
text_lang: zh
|
||
|
||
narrator:
|
||
ref_audio_path: voices/narrator.wav
|
||
prompt_text: exact transcript of narrator.wav
|
||
prompt_lang: zh
|
||
text_lang: zh
|
||
```
|
||
|
||
编辑后调用：
|
||
|
||
```bash
|
||
curl -X POST http://127.0.0.1:9881/admin/reload-config
|
||
```
|
||
|
||
## 13. 契约测试
|
||
|
||
这个测试使用 mock，不会加载 GPT-SoVITS 模型：
|
||
|
||
```bash
|
||
python -m unittest tests.test_simple_api_contract
|
||
```
|
||
|
||
用于确认：
|
||
|
||
- `/api/tts` 路由存在。
|
||
- 上传接口能构造正确参数。
|
||
- 主参考音频 3-10 秒校验正常。
|
||
- 空 `prompt_text` 在 v2 可用。
|
||
- v3/v4 空 `prompt_text` 会返回 400。
|
||
- 临时上传目录会被清理。
|