feat: add POST /tts/preview endpoint for synchronous TTS preview #1496

Merged

auto-approve-bot merged 4 commits from feat/tts-preview-endpoint into develop 2026-08-25 15:21:02 +08:00

Conversation 5 Commits 4 Files Changed 3

+300 -1

xiaoxia commented 2026-08-25 14:50:53 +08:00

Owner

Copy Link

Copy Source

问题

前端 GeneratePage 和 TtsPanel 调用 POST /tts/preview 获取配音预览音频，但后端没有这个路由，返回 404。

修复

• 新增 TTSPreviewRequest schema：text（max 200字）、voice_id（必填）、speed、pitch
• 新增 TTSPreviewResponse schema：audio_url、duration
• 新增 POST /tts/preview 路由，调用 CosyVoiceService.synthesize_speech() 同步合成
• CosyVoiceError → 502，ValueError → 400，校验失败 → 422
• 8 个单元测试全部通过

接口规格

POST /tts/preview
Request: { text: string, voice_id: string, speed?: number, pitch?: number }
Response: { audio_url: string, duration?: number }

验收标准

• POST /tts/preview 返回 200 + audio_url
• text > 200 字返回 422
• voice_id 为空返回 422
• CosyVoice 失败返回 502
• 8 个测试通过

## 问题 前端 GeneratePage 和 TtsPanel 调用 POST /tts/preview 获取配音预览音频，但后端没有这个路由，返回 404。 ## 修复 - 新增 `TTSPreviewRequest` schema：text（max 200字）、voice_id（必填）、speed、pitch - 新增 `TTSPreviewResponse` schema：audio_url、duration - 新增 `POST /tts/preview` 路由，调用 `CosyVoiceService.synthesize_speech()` 同步合成 - CosyVoiceError → 502，ValueError → 400，校验失败 → 422 - 8 个单元测试全部通过 ## 接口规格 ``` POST /tts/preview Request: { text: string, voice_id: string, speed?: number, pitch?: number } Response: { audio_url: string, duration?: number } ``` ## 验收标准 - [x] POST /tts/preview 返回 200 + audio_url - [x] text > 200 字返回 422 - [x] voice_id 为空返回 422 - [x] CosyVoice 失败返回 502 - [x] 8 个测试通过

xiaoxia added 1 commit 2026-08-25 14:50:54 +08:00

feat: add POST /tts/preview endpoint for synchronous TTS preview ... 47525d31f6

- Add TTSPreviewRequest (text max 200 chars, voice_id, speed, pitch)
- Add TTSPreviewResponse (audio_url, duration)
- Implement synchronous preview route using CosyVoiceService.synthesize_speech
- Return 502 on CosyVoiceError, 400 on ValueError
- 8 unit tests covering success, speed param, error handling, validation

gitea-actions bot commented 2026-08-25 14:53:07 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

项目	详情
PR号	#1496
预览链接	https://pr-1496.preview.xiaoxiajianji.com
API环境	staging

💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。

🔄 每次提交新代码后预览环境会自动更新。

🗑️ PR 关闭或合并后，预览环境会自动清理。

🚀 **预览环境已部署** | 项目 | 详情 | |------|------| | PR号 | #1496 | | 预览链接 | [https://pr-1496.preview.xiaoxiajianji.com](https://pr-1496.preview.xiaoxiajianji.com) | | API环境 | staging | > 💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。 > > 🔄 每次提交新代码后预览环境会自动更新。 > > 🗑️ PR 关闭或合并后，预览环境会自动清理。

auto-approve-bot added 1 commit 2026-08-25 14:54:49 +08:00

style: auto-format with black + isort + prettier [skip ci-format-check] dd89614f1c

xiaoxia added 1 commit 2026-08-25 14:59:08 +08:00

fix: use ValidationError instead of broad Exception in TTS preview tests [skip ci-format-check] 3e524c4361

xiaoxia added 1 commit 2026-08-25 15:04:00 +08:00

fix: handle None duration in TTS preview response [skip ci-format-check] 98c0cae1ae

auto-approve-bot commented 2026-08-25 15:10:04 +08:00

Collaborator

Copy Link

Copy Source

【阻塞级判定】

• 是否存在阻塞级问题：否
• 阻塞级问题数量：0 个

📊 审查概览

• 整体评价：有建议
• 建议级问题数量：2 个

🔴 阻塞级问题（必须修复）

无

💡 改进建议（不阻塞合并）

1. [apps/api/app/api/routes/tts.py: 389-391] 参数传递不一致

   • 具体内容：TTSPreviewRequest 中定义了 pitch 字段（音调），但在调用 cosyvoice_service.synthesize_speech 时仅传递了 text, voice_id, speed，忽略了 pitch。虽然 Schema 注释标明“预留”，但保留在请求中却不生效容易造成前端误解。建议：如果服务支持该参数，请补充传递；如果不支持，建议从 Request Schema 中移除，或在代码注释中显式说明该参数被忽略。

2. [apps/api/app/api/routes/tts.py: 378] 同步阻塞调用潜在性能风险

   • 具体内容：preview_tts 是一个同步函数（def），而 synthesize_speech 通常涉及网络 I/O 调用 TTS 服务。在高并发场景下，同步阻塞会耗尽线程池。建议：如果 CosyVoiceService 提供了异步接口（async def），建议将路由改为 async def 并使用 await；如果服务仅支持同步，建议使用 run_in_executor 在后台线程池中运行以避免阻塞事件循环。

3. [apps/api/app/api/routes/tts.py: 398] 错误信息可能泄露敏感信息

   • 具体内容：在捕获 CosyVoiceError 时，直接将异常信息 f"TTS 合成失败: {e}" 返回给客户端。如果上游异常堆栈中包含内部路径、第三方 API Key 或其他调试信息，这将导致信息泄露。建议：记录完整的异常日志到服务器端，仅向客户端返回友好的通用错误码或简化的错误描述。

✅ 良好实践

• 边界条件处理：在返回 duration 时使用了 result.duration if result.duration and result.duration > 0 else None，有效过滤了无效的时长数据（如 0 或负数）。
• 参数校验完善：利用 Pydantic 对 text 长度（200字限制）、voice_id 和 speed 范围进行了严格约束，防止了恶意或非法输入。
• 测试覆盖全面：单元测试覆盖了成功路径、自定义参数、以及各类异常（502, 400, 422）场景，验证了鲁棒性。

---

_{🤖 由 AI 代码审查机器人自动生成 | 2026-08-25 07:10:04 | 模型:}

### 【阻塞级判定】 - 是否存在阻塞级问题：否 - 阻塞级问题数量：0 个 ### 📊 审查概览 - 整体评价：有建议 - 建议级问题数量：2 个 ### 🔴 阻塞级问题（必须修复） 无 ### 💡 改进建议（不阻塞合并） 1. **[apps/api/app/api/routes/tts.py: 389-391] 参数传递不一致** - 具体内容：`TTSPreviewRequest` 中定义了 `pitch` 字段（音调），但在调用 `cosyvoice_service.synthesize_speech` 时仅传递了 `text`, `voice_id`, `speed`，忽略了 `pitch`。虽然 Schema 注释标明“预留”，但保留在请求中却不生效容易造成前端误解。建议：如果服务支持该参数，请补充传递；如果不支持，建议从 Request Schema 中移除，或在代码注释中显式说明该参数被忽略。 2. **[apps/api/app/api/routes/tts.py: 378] 同步阻塞调用潜在性能风险** - 具体内容：`preview_tts` 是一个同步函数（`def`），而 `synthesize_speech` 通常涉及网络 I/O 调用 TTS 服务。在高并发场景下，同步阻塞会耗尽线程池。建议：如果 `CosyVoiceService` 提供了异步接口（`async def`），建议将路由改为 `async def` 并使用 `await`；如果服务仅支持同步，建议使用 `run_in_executor` 在后台线程池中运行以避免阻塞事件循环。 3. **[apps/api/app/api/routes/tts.py: 398] 错误信息可能泄露敏感信息** - 具体内容：在捕获 `CosyVoiceError` 时，直接将异常信息 `f"TTS 合成失败: {e}"` 返回给客户端。如果上游异常堆栈中包含内部路径、第三方 API Key 或其他调试信息，这将导致信息泄露。建议：记录完整的异常日志到服务器端，仅向客户端返回友好的通用错误码或简化的错误描述。 ### ✅ 良好实践 - **边界条件处理**：在返回 `duration` 时使用了 `result.duration if result.duration and result.duration > 0 else None`，有效过滤了无效的时长数据（如 0 或负数）。 - **参数校验完善**：利用 Pydantic 对 `text` 长度（200字限制）、`voice_id` 和 `speed` 范围进行了严格约束，防止了恶意或非法输入。 - **测试覆盖全面**：单元测试覆盖了成功路径、自定义参数、以及各类异常（502, 400, 422）场景，验证了鲁棒性。 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-08-25 07:10:04 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

auto-approve-bot approved these changes 2026-08-25 15:15:33 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot approved these changes 2026-08-25 15:15:33 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot merged commit a1ddcb6ff6 into develop 2026-08-25 15:21:02 +08:00

auto-approve-bot deleted branch feat/tts-preview-endpoint 2026-08-25 15:21:03 +08:00

gitea-actions bot commented 2026-08-25 15:22:11 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

PR #1496 已关闭或合并，对应的预览环境已被清理。

如有需要，可以重新打开 PR 来重新生成预览环境。

🗑️ **预览环境已清理** PR #1496 已关闭或合并，对应的预览环境已被清理。 > 如有需要，可以重新打开 PR 来重新生成预览环境。

Sign in to join this conversation.

Reviewers

No Reviewers

auto-approve-bot

Labels

Clear labels

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot xiaoxia

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#1496