tts_trans/API.md

# TTS Book Service API 文档

> 基于小米 MiMo TTS 的听书音频转换服务 API 参考

## 概览

| 分类 | 前缀 | 说明 |
|------|------|------|
| 听书 App 接口 | `/api/` | 供听书 App 调用的音频接入接口 |
| 实时 TTS | `/api/tts` | 实时生成并返回音频流 |
| 管理接口 | `/admin/api/` | Web 管理界面使用的 CRUD 接口 |
| 配置文件 | `/httpTts.json` | 听书 App 导入用配置 |

**Base URL**: `http://<your-server>:3333`

---

## 一、实时 TTS 接口

### POST `/api/tts`

实时调用 MiMo TTS 生成音频，直接返回 MP3 二进制流。

> 长文本会自动分段生成并拼接（每段 ≤ 2000 字符，在句末/段落边界智能切分）。

#### 请求格式

支持两种格式：

**1. JSON 格式**（推荐）

```http
POST /api/tts
Content-Type: application/json

{
  "text": "要合成的文本内容",
  "style": "开心",
  "voice": ""
}
```

**2. Form-urlencoded 格式**（兼容百度风格）

```http
POST /api/tts
Content-Type: application/x-www-form-urlencoded

tex=%E8%A6%81%E5%90%88%E6%88%90%E7%9A%84%E6%96%87%E6%9C%AC
```

#### 参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `text` / `tex` | string | ✅ | 要合成的文本（JSON 用 `text`，Form 用 `tex`） |
| `style` | string | ❌ | 说话风格，如 `开心`、`语速慢`、`东北话`、`像个大将军` 等（见风格参考） |
| `voice` | string | ❌ | 音色名称，留空使用默认音色（`mimo_default`） |

#### 响应

- **成功**: `200 OK`，`Content-Type: audio/mpeg`，响应体为 MP3 二进制数据
- **失败**: `400` / `500`，`Content-Type: application/json`

```json
{
  "status": 40000001,
  "message": "text/tex 不能为空"
}
```

#### 示例

```bash
# cURL - JSON 格式
curl -X POST http://localhost:3333/api/tts \
  -H "Content-Type: application/json" \
  -d '{"text": "你好，今天天气真好！", "style": "开心"}' \
  -o output.mp3

# cURL - 带音色指定
curl -X POST http://localhost:3333/api/tts \
  -H "Content-Type: application/json" \
  -d '{"text": "从前有座山，山里有座庙。", "voice": "mimo_male_01"}' \
  -o output.mp3
```

---

## 二、听书 App 音频接入接口

### GET `/api/book/{book_id}`

获取书籍信息及章节列表，供听书 App 调用。

#### 路径参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `book_id` | string | 书籍唯一标识 |

#### 响应

```json
{
  "book_id": "book_9",
  "title": "三体",
  "author": "刘慈欣",
  "chapters": [
    {
      "chapter_id": "chapter_1",
      "app_chapter_id": "chapter1",
      "title": "第一章 疯狂年代",
      "status": "ready",
      "audio_url": "/api/book/book_9/chapter/chapter_1/audio"
    },
    {
      "chapter_id": "chapter_2",
      "app_chapter_id": "chapter2",
      "title": "第二章 寂静的春天",
      "status": "pending",
      "audio_url": null
    }
  ]
}
```

| 字段 | 说明 |
|------|------|
| `status` | 章节音频状态：`pending`(待生成) / `generating`(生成中) / `ready`(就绪) / `error`(失败) |
| `audio_url` | 音频下载地址，仅 `status=ready` 时有值 |

#### 错误响应

```json
{"detail": "书籍 book_9 不存在"}
```
`404 Not Found`

---

### GET `/api/book/{book_id}/chapter/{chapter_id}/audio`

下载章节 MP3 音频文件。

#### 路径参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `book_id` | string | 书籍 ID |
| `chapter_id` | string | 章节 ID |

#### 响应

- **成功**: `200 OK`，`Content-Type: audio/mpeg`，MP3 文件流
- **未生成**: `404`，`{"detail": "音频尚未生成，当前状态: pending"}`
- **不存在**: `404`，`{"detail": "章节不存在"}`

---

## 三、管理接口

### 书籍管理

#### GET `/admin/api/books`

获取所有书籍列表。

```json
[
  {"book_id": "book_9", "title": "三体", "author": "刘慈欣"},
  {"book_id": "book_12", "title": "活着", "author": "余华"}
]
```

#### POST `/admin/api/books`

创建新书籍。

```http
Content-Type: application/json

{
  "book_id": "book_9",
  "title": "三体",
  "author": "刘慈欣"
}
```

| 字段 | 必填 | 说明 |
|------|------|------|
| `book_id` | ✅ | 唯一标识 |
| `title` | ✅ | 书名 |
| `author` | ❌ | 作者 |

**响应**: `{"ok": true, "book_id": "book_9"}`

**错误**: `409 Conflict`（book_id 已存在）、`400`（缺少必填字段）

#### DELETE `/admin/api/books/{book_id}`

删除书籍及其所有章节。

**响应**: `{"ok": true}`

---

### 章节管理

#### GET `/admin/api/books/{book_id}/chapters`

获取书籍下的章节列表。

```json
[
  {
    "chapter_id": "chapter_1",
    "app_chapter_id": "chapter1",
    "title": "第一章 疯狂年代",
    "text_content": "这是章节文本的前200个字符...",
    "text_length": 15000,
    "status": "ready",
    "error_msg": "",
    "has_audio": true
  }
]
```

> 注意: `text_content` 只返回前 200 个字符用于预览。完整文本需通过 PUT 接口编辑时获取。

#### POST `/admin/api/books/{book_id}/chapters`

创建新章节。

```json
{
  "chapter_id": "chapter_1",
  "app_chapter_id": "chapter1",
  "title": "第一章",
  "text_content": "章节正文内容..."
}
```

| 字段 | 必填 | 说明 |
|------|------|------|
| `chapter_id` | ✅ | 章节唯一标识 |
| `app_chapter_id` | ❌ | 听书 App 中的章节 ID，默认同 chapter_id |
| `title` | ❌ | 章节标题 |
| `text_content` | ❌ | TTS 文本内容 |

#### PUT `/admin/api/books/{book_id}/chapters/{chapter_id}`

更新章节信息（部分更新）。

```json
{
  "text_content": "更新后的文本内容...",
  "title": "新标题"
}
```

所有字段均为可选，只更新传入的字段。

#### DELETE `/admin/api/books/{book_id}/chapters/{chapter_id}`

删除单个章节。

---

### 音频生成

#### POST `/admin/api/books/{book_id}/chapters/{chapter_id}/generate`

为单个章节生成音频。

> 长文本自动分段生成并拼接（每段 ≤ 2000 字符）。

**响应**:

```json
{"ok": true, "status": "ready", "error_msg": ""}
```

或生成失败时：

```json
{"ok": true, "status": "error", "error_msg": "MiMo TTS API 错误: HTTP 502"}
```

#### POST `/admin/api/books/{book_id}/generate-all`

批量生成书籍下所有**未就绪**章节的音频。

> 按顺序逐章生成，可能需要较长时间。

**响应**:

```json
{"ok": true, "total": 5, "chapter_ids": ["ch_1", "ch_2", "ch_3", "ch_4", "ch_5"]}
```

---

### TTS 试听

#### POST `/admin/api/tts/preview`

试听 TTS 效果，返回生成的音频 URL。

```json
{
  "text": "你好，世界！",
  "style": "开心",
  "voice": ""
}
```

| 字段 | 必填 | 说明 |
|------|------|------|
| `text` | ✅ | 试听文本 |
| `style` | ❌ | 说话风格 |
| `voice` | ❌ | 音色名称 |

**响应**:

```json
{"ok": true, "url": "/audio/_preview/a1b2c3d4.mp3"}
```

---

### 配置查看

#### GET `/admin/api/config`

查看当前服务配置。

```json
{
  "endpoint": "https://api.xiaomimimo.com/v1/chat/completions",
  "model": "mimo-v2-audio-tts",
  "voice": "mimo_default",
  "api_key_masked": "sk-mi****",
  "max_chunk_chars": 2000
}
```

---

## 四、配置文件

### GET `/httpTts.json`

提供听书 App 导入用的音频源配置文件（MiMo TTS 单条目）。

用户可直接在听书 App 中通过 URL 导入此配置。

---

## 五、MiMo TTS 风格参考

在 `style` 参数中填写风格关键词，MiMo TTS 支持以下类别：

### 情感类
| 风格 | 示例文本 |
|------|----------|
| 开心 | 今天真是太棒了！|
| 悲伤 | 他默默地离开了... |
| 生气 | 你怎么能这样做！|
| 平静 | 让我们慢慢来。|
| 惊讶 | 什么？这不可能！|
| 温柔 | 没关系，我在这里。|

### 语速类
| 风格 | 效果 |
|------|------|
| 语速慢 | 适合冥想、教学 |
| 语速快 | 适合新闻、解说 |
| 悄悄话 | 轻声细语 |

### 角色类
| 风格 | 效果 |
|------|------|
| 像个大将军 | 威严有力 |
| 像个小孩 | 稚嫩可爱 |
| 孙悟空 | 经典猴王 |
| 像个诗人 | 文艺优雅 |
| 像个老人 | 沧桑稳重 |

### 方言类
| 风格 | 说明 |
|------|------|
| 东北话 | 东北方言 |
| 四川话 | 四川方言 |
| 台湾腔 | 台湾口音 |
| 粤语 | 广东话 |
| 河南话 | 河南方言 |

### 组合使用

风格可以组合，例如：

```json
{
  "text": "今天天气真好",
  "style": "开心 语速快"
}
```

---

## 六、错误码参考

| HTTP 状态码 | status 字段 | 含义 |
|-------------|-------------|------|
| 400 | 40000001 | 请求参数缺失或无效 |
| 404 | - | 资源不存在（书籍/章节/音频文件） |
| 409 | - | 资源冲突（ID 已存在） |
| 500 | 50000002 | 服务端错误（未配置 API Key 等） |
| 502 | - | MiMo TTS API 调用失败 |

---

## 七、文本自动分段机制

当文本超过 **2000 字符**时，服务自动进行智能分段：

### 分段策略

按优先级尝试在以下位置切分：

1. **段落边界** — `\n\n`
2. **换行符** — `\n`
3. **中文句末标点** — `。！？…`
4. **英文句末标点** — `.!?`
5. **分号** — `；;`
6. **逗号** — `，,`
7. **硬切** — 以上都不匹配时按长度截断

### 处理流程

```
原始文本 (10000字)
  → 智能分段 → [段1(1800字), 段2(1950字), 段3(2000字), 段4(1900字), 段5(2350字)]
  → 逐段调用 MiMo TTS → [wav1, wav2, wav3, wav4, wav5]
  → ffmpeg 拼接 → 最终 MP3
```

此过程对用户完全透明，`/api/tts` 和章节音频生成均自动支持。