tts_trans/README.md

# 🎙️ TTS Proxy Service

小米 MiMo TTS 音频转换代理服务，提供实时 TTS 接口和 Web 管理界面。

## 架构

```
听书 App / curl ──HTTP──▶ 本服务 ──API──▶ 小米 MiMo TTS
                         │
                         ├── 智能文本分段（>2000字自动切分拼接）
                         ├── TTS 自动重试（5xx 错误最多重试 3 次）
                         └── MP3 缓存
```

## 快速启动

```bash
# 1. 配置 API Key
cp .env.example .env
# 编辑 .env 填入 MIMO_API_KEY

# 2. 启动
docker compose up -d

# 3. 访问
# 管理界面: http://your-server:3333
# TTS 接口: http://your-server:3333/api/tts
```

## 核心功能

### POST `/api/tts` — 实时 TTS

文本进 → MP3 出。支持 JSON 和 Form 两种格式，长文本自动分段拼接。

```bash
# JSON 格式
curl -X POST http://localhost:3333/api/tts \
  -H "Content-Type: application/json" \
  -d '{"text": "你好世界", "style": "开心", "voice": ""}' \
  -o output.mp3

# Form 格式（百度兼容）
curl -X POST http://localhost:3333/api/tts \
  -d "tex=你好世界" \
  -o output.mp3
```

### GET `/health` — 健康检查

### 管理接口（需 Bearer Token）

| 接口 | 方法 | 说明 |
|------|------|------|
| `/admin/api/preview` | POST | TTS 试听，返回音频 URL |
| `/admin/api/config` | GET | 查看当前配置 |

## 接入听书 App

在 App 中配置 TTS 音频源：

- **URL**: `http://your-server:3333/api/tts`
- **Method**: POST
- **Body**: `{"text": "{{speakText}}"}`
- **Content-Type**: `audio/mpeg`

App 模板变量：`{{speakText}}`（文本）、`{{speakSpeed}}`（语速 5-50）

> App 只能动态传文本。voice/style 需在 JSON body 中写死，或通过其他客户端调用时传入。

## 环境变量

| 变量 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
| `MIMO_API_KEY` | ✅ | - | MiMo TTS API Key |
| `MIMO_API_ENDPOINT` | ❌ | `https://api.xiaomimimo.com/v1/chat/completions` | API 地址 |
| `MIMO_TTS_MODEL` | ❌ | `mimo-v2-tts` | 模型名称 |
| `MIMO_VOICE` | ❌ | `mimo_default` | 默认音色 |
| `API_TOKEN` | ❌ | - | 管理接口 Bearer Token（留空则不鉴权） |

## MiMo TTS 风格参考

| 类别 | 示例 |
|------|------|
| 情感 | 开心 / 悲伤 / 生气 / 平静 |
| 语速 | 语速慢 / 语速快 / 悄悄话 |
| 角色 | 像个大将军 / 像个小孩 / 孙悟空 |
| 方言 | 东北话 / 四川话 / 台湾腔 / 粤语 |

## 不使用 Docker

```bash
pip install -r requirements.txt
# 系统需安装 ffmpeg
export MIMO_API_KEY=your_key
cd app && python main.py
```