audio_codebuddy/hardware-integration/docs/API兼容性报告.md

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 中新增端点：

// 新增：同步合成（任意文本）
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 方法（可能需要新增）：

// 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 调用示例：

# 适配现有 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（多个项目复用）