TTS语音合成API

本文档引用的文件

tts.controller.ts
tts.service.ts
aliyun.provider.ts
minimax.provider.ts
mock.provider.ts
audio-merger.ts
types/index.ts
config/index.ts
config/models.json
API.md

简介

TTS语音合成模块是AI有声书系统的核心组件，提供高质量的文本转语音服务。该模块支持多种音色提供商，包括阿里云百炼、MiniMax等，并具备智能降级机制，确保在各种网络环境下都能稳定运行。

主要功能特性：

多音色支持：10种不同风格的音色选择
智能参数调节：速度、音调、音量三参数控制
多提供商集成：阿里云、MiniMax、模拟服务
异步生成：支持大文本的异步音频生成
智能降级：API Key缺失时自动使用模拟服务
文件管理：完整的音频文件存储和生命周期管理

项目结构

TTS模块采用清晰的分层架构设计，按照职责分离的原则组织代码：

graph TB
subgraph "TTS模块架构"
Controller[tts.controller.ts<br/>HTTP接口控制器]
Service[tts.service.ts<br/>业务逻辑服务]
subgraph "Provider层"
Aliyun[AliyunTtsProvider<br/>阿里云百炼]
MiniMax[MiniMaxTtsProvider<br/>MiniMax]
Mock[MockTtsProvider<br/>模拟服务]
end
subgraph "工具层"
Merger[AudioMerger<br/>音频合并器]
Config[配置管理]
Types[类型定义]
end
Controller --> Service
Service --> Aliyun
Service --> MiniMax
Service --> Mock
Service --> Merger
Service --> Config
Service --> Types
end

图表来源

tts.controller.ts:1-274
tts.service.ts:1-715

章节来源

tts.controller.ts:1-274
tts.service.ts:1-715

核心组件

音色列表管理

系统提供10种精心挑选的音色，涵盖不同性别和风格：

音色ID	名称	性别	描述
cherry	芊悦	女性	阳光积极、亲切自然
serena	苏瑶	女性	温柔女声
ethan	晨煦	男性	阳光温暖、活力男声
chelsie	千雪	女性	二次元虚拟女友
momo	茉兔	女性	撒娇搞怪
vivian	十三	女性	可爱小暴躁
moon	月白	男性	率性帅气
maia	四月	女性	知性温柔
kai	凯	男性	舒缓放松
nofish	不吃鱼	男性	不会翘舌音

音频参数配置

音色参数通过统一的VoiceParams接口进行管理：

classDiagram
class VoiceParams {
+number speed
+number pitch
+number volume
}
class AliyunTtsProvider {
+synthesize(text, voiceId, params, outputPath) string
-apiKey string
-model string
-voice string
}
class MiniMaxTtsProvider {
+synthesize(text, voiceId, params, outputPath) string
-apiKey string
-createTask(text, voiceId, params) Promise
-queryTask(task_id, task_token) Promise
}
VoiceParams --> AliyunTtsProvider : "配置参数"
VoiceParams --> MiniMaxTtsProvider : "配置参数"

图表来源

types/index.ts:40-44
aliyun.provider.ts:21-29
minimax.provider.ts:237-278

章节来源

types/index.ts:40-44
tts.service.ts:24-36

架构概览

TTS模块采用多提供商架构，支持动态切换和智能降级：

sequenceDiagram
participant Client as 客户端
participant Controller as 控制器
participant Service as 服务层
participant Provider as 供应商
participant Storage as 存储服务
Client->>Controller : POST /api/tts/generate
Controller->>Service : generateAudio(userId, text, voiceId, params)
Service->>Service : getTtsProvider(text, voiceId)
alt 阿里云可用
Service->>Provider : AliyunTtsProvider
Provider-->>Service : 音频文件路径
else MiniMax可用
Service->>Provider : MiniMaxTtsProvider
Provider-->>Service : 音频文件路径
else 模拟服务
Service->>Provider : MockTtsProvider
Provider-->>Service : 占位音频文件
end
Service->>Storage : 上传音频文件
Storage-->>Service : 文件URL
Service-->>Controller : 音频信息
Controller-->>Client : 生成结果
Note over Service,Storage : 异步处理，立即返回任务ID

图表来源

tts.controller.ts:52-127
tts.service.ts:200-280

详细组件分析

音色列表接口（GET /api/tts/voices）

该接口提供可用音色的完整列表，支持客户端音色选择和预览功能。

请求格式

方法：GET
路径：/api/tts/voices
认证：可选

响应结构

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

章节来源

tts.controller.ts:12-21
tts.service.ts:599-602

音频生成接口（POST /api/tts/generate）

异步音频生成接口，支持大文本处理和多种音色提供商。

请求格式

方法：POST
路径：/api/tts/generate
认证：可选
内容类型：application/json

请求参数

{
  "text": "要转换的文本内容",
  "voiceId": "cherry",
  "voiceParams": {
    "speed": 1.0,
    "pitch": 0,
    "volume": 50
  },
  "bookId": "123",
  "chapterTitle": "第一章",
  "ttsProvider": "minimax"
}

响应结构

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

章节来源

tts.controller.ts:52-127
tts.service.ts:200-280

音频参数配置详解

速度参数（speed）

范围：0.5 - 2.0
默认值：1.0
影响：控制语音播放速度
调优建议：
- 0.8-1.2：正常语速范围
- 1.2-1.5：稍快，适合新闻播报
- 1.5以上：快速阅读场景

音调参数（pitch）

范围：-500 - 500
默认值：0
影响：控制声音高低
调优建议：
- -200-200：自然音域
- -500-(-200)：低沉磁性
- 200-500：清脆明亮

音量参数（volume）

范围：0 - 100
默认值：50
影响：控制音频响度
调优建议：
- 30-70：标准音量
- 70以上：响亮场景
- 30以下：轻声细语

音色提供商集成

阿里云百炼（DashScope）

适用场景：高质量中文语音合成
特点：支持指令模型，参数控制精确
配置要求：需要有效的API Key

MiniMax

适用场景：异步长文本处理
特点：支持长文本一次性合成
配置要求：需要有效的API Key

模拟服务

适用场景：开发调试和演示
特点：无需外部API，快速响应
限制：质量较低，仅作占位

章节来源

tts.service.ts:160-190
aliyun.provider.ts:21-150
minimax.provider.ts:53-278

音频文件存储与管理

存储位置

本地路径：{项目根目录}/uploads/{audioId}/output.mp3
访问方式：通过/uploads/{audioId}/output.mp3访问
生命周期：生成后长期保存，支持重复访问

文件结构

uploads/
├── 550e8400-e29b-41d4-a716-446655440000/
│   ├── segment_0.mp3
│   ├── segment_1.mp3
│   └── output.mp3
└── b42de876-f54c-42e5-b827-557766551100/
    └── output.mp3

生命周期管理

生成阶段：创建临时目录，保存分段音频
合并阶段：合并所有分段为完整音频
上传阶段：上传到存储服务，生成永久URL
清理阶段：保留必要文件，定期清理临时文件

章节来源

tts.service.ts:218-225
audio-merger.ts:11-36

依赖关系分析

TTS模块的依赖关系呈现清晰的单向依赖结构：

graph TD
subgraph "外部依赖"
Axios[Axios HTTP库]
FS[文件系统]
Path[路径处理]
Child[子进程]
end
subgraph "核心模块"
Controller[tts.controller.ts]
Service[tts.service.ts]
Types[types/index.ts]
Config[config/index.ts]
end
subgraph "Provider实现"
Aliyun[aliyun.provider.ts]
MiniMax[minimax.provider.ts]
Mock[mock.provider.ts]
end
subgraph "工具组件"
Merger[audio-merger.ts]
Models[config/models.json]
end
Controller --> Service
Service --> Types
Service --> Config
Service --> Merger
Service --> Aliyun
Service --> MiniMax
Service --> Mock
Service --> Models
Aliyun --> Axios
MiniMax --> Axios
Mock --> Child
Service --> FS
Service --> Path
Merger --> FS
Merger --> Child

图表来源

tts.controller.ts:1-10
tts.service.ts:1-15

章节来源

tts.service.ts:1-25

性能考虑

并发处理

分段并发：默认并发2个分段同时生成
长文本处理：MiniMax支持单次异步处理
重试机制：提供指数退避重试，避免服务过载

缓存策略

配置缓存：模型配置一次性加载
音色映射：音色ID到提供商音色的映射缓存
日志文件：统一的日志文件记录，便于性能监控

内存管理

流式处理：大型音频文件采用流式下载
分段处理：避免大文本一次性加载内存
及时清理：生成完成后及时释放资源

故障排除指南

常见错误及解决方案

1. API Key配置错误

症状：服务调用失败，返回401或403错误 解决方案：

检查.env文件中的API Key配置
验证API Key的有效性和权限
确认网络连接正常

2. 速率限制

症状：请求被拒绝，返回429状态码 解决方案：

实现指数退避重试
降低请求频率
考虑升级服务套餐

3. 网络超时

症状：请求超时，服务不可用 解决方案：

增加超时时间配置
检查网络连接稳定性
考虑使用CDN加速

4. 音频生成失败

症状：生成任务失败，文件损坏 解决方案：

检查磁盘空间充足
验证FFmpeg安装正确
查看日志文件定位具体错误

调试工具

日志文件

位置：tts-debug.log
内容：详细的生成过程日志
用途：问题诊断和性能分析

状态检查

# 检查服务状态
curl -X GET http://localhost:3000/api/tts/test-db

# 获取音色列表
curl -X GET http://localhost:3000/api/tts/voices

# 检查提供商状态
curl -X GET http://localhost:3000/api/tts/providers

章节来源

tts.service.ts:16-22
tts.controller.ts:34-50

结论

TTS语音合成模块通过精心设计的架构和完善的错误处理机制，为AI有声书系统提供了稳定可靠的语音合成服务。模块的主要优势包括：

多提供商支持：灵活的提供商选择和自动降级机制
智能参数控制：精确的音色参数调节能力
异步处理：高效的长文本处理和并发控制
完整生命周期管理：从生成到存储的全流程管理
完善的错误处理：多层次的错误检测和恢复机制

通过合理的配置和调优，该模块能够满足不同场景下的语音合成需求，为用户提供优质的AI有声书体验。

TTS语音合成API.md 13 KB Vēsture Neapstrādāts

TTS语音合成API

目录

简介

项目结构

核心组件

音色列表管理

音频参数配置

架构概览

详细组件分析

音色列表接口（GET /api/tts/voices）

音频生成接口（POST /api/tts/generate）

音频参数配置详解

速度参数（speed）

音调参数（pitch）

音量参数（volume）

音色提供商集成

阿里云百炼（DashScope）

MiniMax

模拟服务

音频文件存储与管理

存储位置

文件结构

生命周期管理

依赖关系分析

性能考虑

并发处理

缓存策略

内存管理

故障排除指南

常见错误及解决方案

1. API Key配置错误

2. 速率限制

3. 网络超时

4. 音频生成失败

调试工具

日志文件

状态检查

结论

TTS语音合成API.md 13 KB

Vēsture Neapstrādāts