# TTS API 兼容性报告

**日期**：2026-06-15
**结论**：❌ **不兼容**——需要修改 SDK 适配现有 API

## 问题清单

### 1. URL 路径不匹配

| 我写的（OpenAPI 规范） | 现有实际端点 |
|----------------------|------------|
| `POST /v1/tts/synthesize` | `POST /tts/generate`（异步） |
| `POST /v1/tts/async-synthesize` | `POST /tts/generate` |
| `POST /v1/tts/instruct` | ❌ 不存在 |
| `GET /v1/tts/tasks/{id}` | `GET /tts/status/:audioId` |
| `GET /v1/tts/voices` | `GET /tts/voices` ✅ 兼容 |

### 2. 参数命名格式不匹配

| 我写的（snake_case） | 现有实际（camelCase） |
|---------------------|---------------------|
| `voice_id` | `voiceId` |
| `speed` | `voiceParams.speed`（嵌套对象） |
| `pitch` | `voiceParams.pitch` |
| `volume` | `voiceParams.volume` |
| `text` | `text` ✅ 兼容 |

### 3. 响应格式差异

| 维度 | 我写的（标准） | 现有实际 |
|------|---------------|----------|
| 同步返回 | 直接返回 audio URL | ❌ 现有没有同步端点 |
| 异步返回 | `task_id` | `chapterId, bookId` |
| 状态字段 | `status: pending/processing/completed/failed` | 状态从 book/chapter 表查询 |
| 音频 URL | `audio_url` | `audioUrl` |

### 4. 关键缺失功能

❌ **`POST /v1/tts/synthesize`（同步合成任意文本）不存在**

现有 API 只有：
- `POST /tts/preview` - **音色预览**（固定文本："你好，欢迎使用 AI 有声书"）
- `POST /tts/generate` - **异步生成**（返回 chapterId，需要轮询）

**这意味着**：硬件不能直接"说一句话就播放"——必须先调 `/tts/generate`，然后轮询 `/tts/status/:id` 等待完成。

## 影响

### 智能音箱流程改造

```
原计划（标准 OpenAPI）：
  录音 → ASR → LLM → POST /synthesize（同步）→ 立即返回音频 → 播放
  延迟：800ms

实际情况：
  录音 → ASR → LLM → POST /generate（异步）→ 轮询 /status → 等完成 → 下载 → 播放
  延迟：3-5 秒（包含排队 + 生成时间）
```

### 用户体验下降

- 同步合成：用户说完 → 立即听到回复（自然）
- 异步合成：用户说完 → 等待 3-5 秒 → 听到回复（不自然）

## 解决方案

### 方案 A：扩展现有 API（推荐）

**在 `server/src/modules/tts/tts.controller.ts` 中新增端点**：

```typescript
// 新增：同步合成（任意文本）
router.post('/synthesize', async (ctx) => {
  const { text, voiceId, voiceParams } = ctx.request.body;
  
  // 内部调用 TtsService.generatePreview 或类似方法
  // 但允许传入自定义 text
  
  const result = await TtsService.synthesizeSync(text, voiceId, voiceParams);
  
  ctx.body = {
    code: 0,
    data: {
      audioUrl: result.audioUrl,
      duration: result.duration,
    },
  };
});
```

**需要的 TtsService 方法**（可能需要新增）：
```typescript
// TTS 同步合成（不经过 book/chapter 流程）
async synthesizeSync(text: string, voiceId: string, params: any): Promise<{audioUrl, duration}>
```

### 方案 B：改造硬件 SDK 适配现有 API（立即可用）

**修改 `tts_client.py`**：
- 使用 `/tts/preview`（仅适合音色演示）
- 或使用 `/tts/generate` + 轮询（适合实际合成）

**优点**：立即可用，无需改动后端
**缺点**：延迟高，体验差

### 方案 C：双轨并行

- 短期：方案 B（立即可用）
- 中期：方案 A（扩展 API，提升体验）

## 推荐路径

**Week 1**：方案 B（用现有 API，先跑通智能音箱）
**Week 2**：方案 A（扩展同步合成 API，体验更好）

## SDK 适配代码

修改后的 `tts_client.py` 调用示例：

```python
# 适配现有 API（异步模式 + 轮询）
def synthesize(text, voice_id=None):
    # 1. 提交任务
    response = requests.post(
        f'{TTS_BASE_URL}/tts/generate',
        json={
            'text': text,
            'voiceId': voice_id,
            'voiceParams': {'speed': 1.0, 'pitch': 0, 'volume': 50},
        },
        headers={'Authorization': f'Bearer {TTS_API_KEY}'},
    )
    result = response.json()['data']
    chapter_id = result['chapterId']
    
    # 2. 轮询状态
    while True:
        status_resp = requests.get(
            f'{TTS_BASE_URL}/tts/chapter-status/{chapter_id}',
            headers={'Authorization': f'Bearer {TTS_API_KEY}'},
        )
        status = status_resp.json()['data']
        
        if status['status'] == 'completed':
            return status['audioUrl']
        elif status['status'] == 'failed':
            raise Exception('TTS failed')
        
        time.sleep(1)
```

## 结论

**必须修改**，不能直接用现有 `tts_client.py`。

**下一步**：
1. 我现在帮你修改 `tts_client.py` 适配现有 API
2. 在 `server/` 中新增 `/tts/synthesize` 同步端点
3. 在 `tts_sdk/` 中封装通用接口

要不要我现在帮你：
1. 🔧 **修改 `tts_client.py`** 适配现有 API（立即可用）
2. 🆕 **新增 `/tts/synthesize` 同步端点**（更好的体验）
3. 📦 **抽取通用 TTS SDK**（多个项目复用）