audio_codebuddy/.plans/audiobook-v2-ux/docs/api-contracts.md

AI有声书 v2 - API 契约

前后端接口定义。字段名和类型的真理源头。 维护者：devs（添加/变更端点时必须更新）

---

现有 API

书籍相关

方法	路径	描述
GET	/api/books	获取书籍列表
GET	/api/books/:id	获取书籍详情
POST	/api/book-generator/books	创建书籍
POST	/api/book-generator/books/:id/generate	生成内容
POST	/api/book-generator/books/:id/generate-audio	生成音频
POST	/api/book-generator/books/:id/merge-audio	合并音频
POST	/api/book-generator/books/:id/generate-video	生成视频
POST	/api/book-generator/books/:id/publish	发布/取消发布

播放器相关

方法	路径	描述
GET	/api/player/progress	获取播放进度
POST	/api/player/progress	保存播放进度

用户相关

方法	路径	描述
POST	/api/auth/login	登录
GET	/api/user/profile	获取用户信息

---

新增 API（优化项涉及）

OPT-03: 首页最近收听

方法	路径	描述
GET	/api/player/recent	获取用户最近播放记录

Response:

{
  "list": [
    {
      "id": "string",
      "title": "string",
      "coverUrl": "string",
      "progress": 45,
      "updatedAt": "2026-05-07T10:00:00Z"
    }
  ]
}

OPT-08: 一键完整生成

方法	路径	描述
POST	/api/book-generator/books/:id/batch-generate	编排完整生成流程
POST	/api/book-generator/books/:id/batch-generate/cancel	取消生成任务
GET	/api/book-generator/books/:id/batch-generate/status	查询任务状态

Request:

{
  "steps": ["generate_content", "generate_audio", "merge_audio", "generate_video", "merge_video"]
}

Response:

{
  "taskId": "string",
  "bookId": "string",
  "status": "started",
  "steps": ["generate_content", "generate_audio", "merge_audio", "generate_video", "merge_video"]
}

WebSocket 事件: batch_generation_progress - 实时推送生成进度 { taskId, step, progress }

OPT-12: 意见反馈

方法	路径	描述
POST	/api/feedback	提交反馈

Request:

{
  "type": "suggestion|bug|other",
  "title": "string",
  "content": "string",
  "contact": "string",
  "screenshotUrls": ["string"]
}

Response:

{
  "id": "string",
  "status": "submitted"
}

OPT-17: 歌词时间轴

LRC 格式时间戳由 TTS 服务生成，API 响应中新增 lrcLyrics 字段：

{
  "audioUrl": "string",
  "duration": 180,
  "lrcLyrics": "[00:00.00] 第一句歌词\n[00:03.50] 第二句歌词"
}

---

WebSocket 事件

OPT-02: 生成完成推送

事件名	描述	数据
audio_generation_complete	音频生成完成	{ bookId, chapterId, status }
video_generation_complete	视频生成完成	{ bookId, chapterId, status }
batch_generation_progress	批量生成进度	{ taskId, step, progress }