# TTS API接口

<cite>
**本文引用的文件**
- [tts.controller.ts](file://server/src/modules/tts/tts.controller.ts)
- [tts.service.ts](file://server/src/modules/tts/tts.service.ts)
- [aliyun.provider.ts](file://server/src/modules/tts/aliyun.provider.ts)
- [minimax.provider.ts](file://server/src/modules/tts/minimax.provider.ts)
- [mock.provider.ts](file://server/src/modules/tts/mock.provider.ts)
- [auth.ts](file://server/src/middleware/auth.ts)
- [usageLimit.ts](file://server/src/middleware/usageLimit.ts)
- [subscription.service.ts](file://server/src/modules/subscription/subscription.service.ts)
- [types/index.ts](file://server/src/types/index.ts)
- [config/index.ts](file://server/src/config/index.ts)
- [app.ts](file://server/src/app.ts)
- [audio-merger.ts](file://server/src/modules/tts/audio-merger.ts)
- [API.md](file://docs/API.md)
- [TTS成本分析报告.md](file://docs/TTS成本分析报告.md)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介

TTS（Text-to-Speech）语音合成API是AI有声书生成工具的核心功能模块，提供从文本到高质量音频的完整转换服务。该接口支持多种音色选择、参数调节、异步生成和状态查询等功能，适用于内容创作者、自媒体作者和学习者等各类用户群体。

## 项目结构

TTS模块采用清晰的分层架构设计：

```mermaid
graph TB
subgraph "API层"
Controller[TTS控制器]
end
subgraph "服务层"
Service[TTS服务]
Storage[存储服务]
Queue[队列服务]
end
subgraph "提供商层"
Aliyun[阿里云TTS]
MiniMax[MiniMax TTS]
Mock[模拟TTS]
end
subgraph "基础设施"
DB[(MySQL数据库)]
OSS[(对象存储)]
Redis[(Redis缓存)]
end
Controller --> Service
Service --> Storage
Service --> Queue
Service --> Aliyun
Service --> MiniMax
Service --> Mock
Storage --> OSS
Service --> DB
Service --> Redis
```

**图表来源**
- [tts.controller.ts:1-274](file://server/src/modules/tts/tts.controller.ts#L1-L274)
- [tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)

**章节来源**
- [tts.controller.ts:1-274](file://server/src/modules/tts/tts.controller.ts#L1-L274)
- [tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)

## 核心组件

### 音色管理系统
系统内置10种优质音色，涵盖不同性别和风格：
- **女性音色**：芊悦、苏瑶、千雪、茉兔、十三、四月、不吃鱼
- **男性音色**：晨煦、月白、凯、不吃鱼
- **特殊音色**：二次元虚拟女友、可爱小暴躁、率性帅气、撒娇搞怪

### TTS提供商支持
- **阿里云百炼**：支持HTTP直连模式，适合稳定性和成本控制
- **MiniMax**：支持异步长文本模式，适合高质量音频生成
- **模拟服务**：用于开发测试和占位

### 音频处理管道
- **文本分段**：智能分段算法，避免API限制
- **音频合并**：支持多段音频无缝拼接
- **格式转换**：统一输出MP3格式

**章节来源**
- [tts.service.ts:24-56](file://server/src/modules/tts/tts.service.ts#L24-L56)
- [tts.service.ts:160-190](file://server/src/modules/tts/tts.service.ts#L160-L190)

## 架构概览

```mermaid
sequenceDiagram
participant Client as 客户端
participant API as API网关
participant Auth as 认证中间件
participant TTS as TTS控制器
participant Service as TTS服务
participant Provider as TTS提供商
participant Storage as 存储服务
Client->>API : POST /api/tts/generate
API->>Auth : 验证JWT令牌
Auth-->>API : 用户信息
API->>TTS : 处理生成请求
TTS->>Service : 生成音频
Service->>Provider : 调用TTS API
Provider-->>Service : 返回音频数据
Service->>Storage : 上传音频文件
Storage-->>Service : 返回访问URL
Service-->>TTS : 返回生成结果
TTS-->>Client : 返回音频信息
Note over Client,Storage : 异步生成流程
```

**图表来源**
- [tts.controller.ts:52-127](file://server/src/modules/tts/tts.controller.ts#L52-L127)
- [tts.service.ts:200-280](file://server/src/modules/tts/tts.service.ts#L200-L280)

## 详细组件分析

### 音色列表查询 (/api/tts/voices)

**接口定义**
- **方法**: GET
- **路径**: `/api/tts/voices`
- **认证**: 无需登录

**请求参数**
- 无参数

**响应格式**
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "voices": [
      {
        "id": "cherry",
        "name": "芊悦",
        "gender": "female",
        "description": "阳光积极、亲切自然"
      }
    ]
  }
}
```

**实现细节**
- 返回系统内置的10种音色配置
- 支持音色试听功能
- 音色ID与阿里云音色映射

**章节来源**
- [tts.controller.ts:12-21](file://server/src/modules/tts/tts.controller.ts#L12-L21)
- [tts.service.ts:24-56](file://server/src/modules/tts/tts.service.ts#L24-L56)

### 服务商列表查询 (/api/tts/providers)

**接口定义**
- **方法**: GET
- **路径**: `/api/tts/providers`
- **认证**: 无需登录

**请求参数**
- 无参数

**响应格式**
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "providers": [
      {
        "id": "aliyun",
        "name": "阿里云百炼",
        "enabled": true
      },
      {
        "id": "minimax",
        "name": "MiniMax",
        "enabled": false
      }
    ]
  }
}
```

**实现细节**
- 动态检测API密钥配置
- 返回可用的TTS提供商列表
- 支持提供商状态检测

**章节来源**
- [tts.controller.ts:23-32](file://server/src/modules/tts/tts.controller.ts#L23-L32)
- [tts.service.ts:637-644](file://server/src/modules/tts/tts.service.ts#L637-L644)

### 音频生成 (/api/tts/generate)

**接口定义**
- **方法**: POST
- **路径**: `/api/tts/generate`
- **认证**: 可选认证（支持未登录用户）

**请求参数**
```json
{
  "text": "要转换的文本内容",
  "voiceId": "cherry",
  "voiceParams": {
    "speed": 1.0,
    "pitch": 0,
    "volume": 50
  },
  "bookId": "123",
  "chapterTitle": "第一章",
  "ttsProvider": "aliyun"
}
```

**响应格式**
```json
{
  "code": 0,
  "message": "音频生成任务已创建",
  "data": {
    "audioId": "550e8400-e29b-41d4-a716-446655440000",
    "audioUrl": ""
  }
}
```

**参数验证规则**
- **文本验证**: 必填，长度>0
- **音色验证**: 必填，必须在音色列表中
- **字数限制**: 根据用户会员等级限制
- **提供商验证**: 可选，支持'aliyun'或'minimax'

**配额检查流程**
```mermaid
flowchart TD
Start([开始生成]) --> ValidateText["验证文本参数"]
ValidateText --> CheckUser{"用户已登录?"}
CheckUser --> |是| CheckQuota["检查音频时长配额"]
CheckUser --> |否| SkipQuota["跳过配额检查"]
CheckQuota --> QuotaAllowed{"配额充足?"}
QuotaAllowed --> |否| Reject["拒绝请求"]
QuotaAllowed --> |是| Process["处理生成"]
SkipQuota --> Process
Process --> CreateRecord["创建音频记录"]
CreateRecord --> GenerateAudio["生成音频"]
GenerateAudio --> ConsumeQuota["消耗配额"]
ConsumeQuota --> Success["返回结果"]
Reject --> End([结束])
Success --> End
```

**图表来源**
- [tts.controller.ts:52-127](file://server/src/modules/tts/tts.controller.ts#L52-L127)
- [subscription.service.ts:651-683](file://server/src/modules/subscription/subscription.service.ts#L651-L683)

**实现细节**
- 异步生成模式，立即返回任务ID
- 支持多种TTS提供商自动切换
- 音频时长按150字/分钟估算
- 支持书籍章节关联

**章节来源**
- [tts.controller.ts:52-127](file://server/src/modules/tts/tts.controller.ts#L52-L127)
- [subscription.service.ts:651-683](file://server/src/modules/subscription/subscription.service.ts#L651-L683)

### 状态查询 (/api/tts/status/:audioId)

**接口定义**
- **方法**: GET
- **路径**: `/api/tts/status/:audioId`
- **认证**: 无需登录

**请求参数**
- **路径参数**: audioId - 音频任务ID

**响应格式**
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "status": "processing",
    "audio": {
      "audioUrl": "/uploads/550e8400/output.mp3",
      "audioDuration": 120,
      "audioSize": 1024000
    }
  }
}
```

**状态类型**
- **processing**: 处理中
- **completed**: 已完成
- **failed**: 失败
- **not_found**: 不存在

**实现细节**
- 文件系统状态检测
- 支持僵尸任务识别（超过2分钟无文件）
- 自动清理失败任务

**章节来源**
- [tts.controller.ts:129-143](file://server/src/modules/tts/tts.controller.ts#L129-L143)
- [tts.service.ts:547-597](file://server/src/modules/tts/tts.service.ts#L547-L597)

### 预览生成 (/api/tts/preview)

**接口定义**
- **方法**: POST
- **路径**: `/api/tts/preview`
- **认证**: 无需登录

**请求参数**
```json
{
  "voiceId": "cherry",
  "voiceParams": {
    "speed": 1.0,
    "pitch": 0,
    "volume": 50
  },
  "ttsProvider": "aliyun"
}
```

**响应格式**
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "previewText": "你好，欢迎使用AI有声书",
    "voiceId": "cherry",
    "audioUrl": "/uploads/preview-550e8400/output.mp3"
  }
}
```

**实现细节**
- 使用固定短文本进行音色预览
- 支持音色参数实时调节
- 生成临时预览音频

**章节来源**
- [tts.controller.ts:145-180](file://server/src/modules/tts/tts.controller.ts#L145-L180)
- [tts.service.ts:646-715](file://server/src/modules/tts/tts.service.ts#L646-L715)

### 下载信息获取 (/api/tts/download/:audioId)

**接口定义**
- **方法**: GET
- **路径**: `/api/tts/download/:audioId`
- **认证**: 无需登录

**请求参数**
- **路径参数**: audioId - 音频ID

**响应格式**
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 123,
    "title": "音频标题",
    "audioUrl": "/uploads/550e8400/output.mp3",
    "duration": 120,
    "size": 1024000,
    "downloadUrl": "/uploads/550e8400/output.mp3"
  }
}
```

**实现细节**
- 直接返回音频URL，支持浏览器直接下载
- 支持批量下载（/api/tts/download/batch）
- 限制单次批量下载数量（≤50个）

**章节来源**
- [tts.controller.ts:182-221](file://server/src/modules/tts/tts.controller.ts#L182-L221)
- [tts.controller.ts:223-272](file://server/src/modules/tts/tts.controller.ts#L223-L272)

## 依赖关系分析

```mermaid
graph LR
subgraph "外部依赖"
Aliyun[AWS SDK]
MiniMax[HTTP Client]
FFmpeg[FFmpeg CLI]
Axios[Axios]
end
subgraph "内部模块"
Config[配置管理]
Types[类型定义]
Logger[日志服务]
ErrorHandler[错误处理]
end
TTSController --> TTSProvider
TTSProvider --> Config
TTSProvider --> Types
TTSProvider --> Logger
TTSProvider --> ErrorHandler
TTSProvider --> Aliyun
TTSProvider --> MiniMax
TTSProvider --> FFmpeg
TTSProvider --> Axios
```

**图表来源**
- [tts.service.ts:1-15](file://server/src/modules/tts/tts.service.ts#L1-L15)
- [aliyun.provider.ts:1-152](file://server/src/modules/tts/aliyun.provider.ts#L1-L152)
- [minimax.provider.ts:1-280](file://server/src/modules/tts/minimax.provider.ts#L1-L280)

**章节来源**
- [tts.service.ts:1-15](file://server/src/modules/tts/tts.service.ts#L1-L15)
- [config/index.ts:69-117](file://server/src/config/index.ts#L69-L117)

## 性能考虑

### 并发处理策略
- **MiniMax并发**: 1个并发，避免长时间轮询
- **阿里云并发**: 2个并发，提高处理效率
- **批量生成**: 支持多段音频并行处理

### 缓存机制
- **音色配置缓存**: 减少重复查询
- **提供商状态缓存**: 避免频繁API检测
- **音频文件缓存**: 支持CDN加速

### 资源优化
- **内存管理**: 及时释放音频处理资源
- **磁盘空间**: 定期清理临时文件
- **网络优化**: 连接池复用，超时控制

## 故障排除指南

### 常见错误码
| 错误码 | 说明 | 处理建议 |
|--------|------|----------|
| 400 | 请求参数错误 | 检查必填参数和格式 |
| 401 | 未授权 | 验证JWT令牌有效性 |
| 403 | 禁止访问 | 检查用户权限和配额 |
| 404 | 资源不存在 | 确认音频ID正确性 |
| 500 | 服务器内部错误 | 查看服务日志 |

### 限流策略
- **IP级限流**: 1000请求/小时
- **用户级限流**: 根据会员等级差异化
- **API级限流**: TTS提供商API限制

### 配额检查
```mermaid
flowchart TD
CheckQuota[检查用户配额] --> DailyLimit{每日限制}
DailyLimit --> |超限| DailyError[返回每日限制错误]
DailyLimit --> |未超限| WordLimit{字数限制}
WordLimit --> |超限| WordError[返回字数限制错误]
WordLimit --> |未超限| ProviderCheck[提供商检查]
ProviderCheck --> RateLimit{提供商限额}
RateLimit --> |超限| ProviderError[切换其他提供商]
RateLimit --> |未超限| Allow[允许生成]
```

**图表来源**
- [usageLimit.ts:6-49](file://server/src/middleware/usageLimit.ts#L6-L49)
- [subscription.service.ts:651-683](file://server/src/modules/subscription/subscription.service.ts#L651-L683)

**章节来源**
- [usageLimit.ts:6-49](file://server/src/middleware/usageLimit.ts#L6-L49)
- [subscription.service.ts:651-683](file://server/src/modules/subscription/subscription.service.ts#L651-L683)

## 结论

TTS API接口提供了完整的文本转语音解决方案，具有以下特点：

1. **高可用性**: 多提供商支持和自动切换机制
2. **灵活性**: 支持多种音色和参数调节
3. **可扩展性**: 模块化设计便于功能扩展
4. **易用性**: 简洁的API设计和完善的文档

建议在生产环境中：
- 配置合适的API密钥和限额
- 设置合理的缓存策略
- 监控服务性能和错误率
- 定期备份重要数据

## 附录

### 客户端集成指南

**基本集成步骤**
1. 获取音色列表
2. 选择音色和参数
3. 发送生成请求
4. 轮询状态查询
5. 下载音频文件

**最佳实践建议**
- 实现重试机制处理网络异常
- 使用状态轮询而非阻塞等待
- 合理设置超时时间和重试间隔
- 缓存音色配置减少请求次数

**使用限制**
- 免费用户：每日3次，每次最多5000字
- 月度会员：每日20次，每次最多50000字
- 年度会员：无限次使用

**章节来源**
- [API.md:95-158](file://docs/API.md#L95-L158)
- [types/index.ts:120-124](file://server/src/types/index.ts#L120-L124)