fix(backend): #1897 声音克隆preview接口支持情绪语速参数 #1907

Merged

auto-approve-bot merged 1 commits from fix/1897-voice-clone-preview-emotion-speed-backend into develop 2026-09-14 18:56:53 +08:00

Conversation 2 Commits 1 Files Changed 2

+95 -7

xiaoxia commented 2026-09-14 18:49:26 +08:00

Owner

Copy Link

Copy Source

背景

Issue #1897：声音克隆页增加情绪/语速设置。前端加控件后会传 emotion 和 speed 到 preview 接口，后端需接收并透传。

参考已有 TTS preview 接口（POST /tts/preview）的实现：apps/api/app/api/routes/tts.py 已正确接收 speed/emotion 并透传到 cosyvoice.synthesize_speech。CosyVoice 服务层 synthesize_speech 已原生支持 speed/emotion 参数，无需修改。

改动

• apps/api/app/api/routes/voice_clones.py：GET /voice-clones/{clone_id}/preview 新增两个 query 参数
  • speed: float = 1.0，ge=0.5, le=2.0（FastAPI 自动校验越界返回 422）
  • emotion: str = ""，白名单校验 natural/excited/calm/friendly/空字符串，非法返回 400
  • 透传至 cosyvoice.synthesize_speech(text=..., voice_id=..., format="mp3", speed=speed, emotion=emotion)
  • 缓存策略：仅默认参数（默认试听文本 + speed=1.0 + emotion 空）走缓存；自定义 speed/emotion 实时合成不缓存
  • 新增 except ValueError 返回 400（与 TTS preview 一致，speed 越界等参数错误 cosyvoice 抛 ValueError）
• language 参数不接受（克隆音色语言由训练时确定，合成时不切换，按工单要求不加）
• 其他逻辑（音频格式 mp3、返回方式、就绪态检查、权限校验）保持不变

测试

• tests/unit/test_voice_clone_preview.py：_call_preview helper 扩展支持 speed/emotion 参数
• 新增 4 个测试用例：
  • test_preview_custom_speed_emotion_passed_through：speed/emotion 正确透传到 cosyvoice
  • test_preview_invalid_emotion_rejected：非法 emotion 返回 400
  • test_preview_non_default_speed_no_cache：自定义 speed/emotion 不走缓存
  • test_preview_valueerror_from_cosyvoice_returns_400：cosyvoice 抛 ValueError 返回 400
• 现有 10 个测试保持通过；voice_clone + cosyvoice 相关共 293 个测试全通过

Refs: #1897

## 背景 Issue #1897：声音克隆页增加情绪/语速设置。前端加控件后会传 emotion 和 speed 到 preview 接口，后端需接收并透传。 参考已有 TTS preview 接口（POST /tts/preview）的实现：apps/api/app/api/routes/tts.py 已正确接收 speed/emotion 并透传到 cosyvoice.synthesize_speech。CosyVoice 服务层 synthesize_speech 已原生支持 speed/emotion 参数，无需修改。 ## 改动 - `apps/api/app/api/routes/voice_clones.py`：GET /voice-clones/{clone_id}/preview 新增两个 query 参数 - `speed: float = 1.0`，ge=0.5, le=2.0（FastAPI 自动校验越界返回 422） - `emotion: str = ""`，白名单校验 natural/excited/calm/friendly/空字符串，非法返回 400 - 透传至 `cosyvoice.synthesize_speech(text=..., voice_id=..., format="mp3", speed=speed, emotion=emotion)` - 缓存策略：仅默认参数（默认试听文本 + speed=1.0 + emotion 空）走缓存；自定义 speed/emotion 实时合成不缓存 - 新增 `except ValueError` 返回 400（与 TTS preview 一致，speed 越界等参数错误 cosyvoice 抛 ValueError） - language 参数不接受（克隆音色语言由训练时确定，合成时不切换，按工单要求不加） - 其他逻辑（音频格式 mp3、返回方式、就绪态检查、权限校验）保持不变 ## 测试 - tests/unit/test_voice_clone_preview.py：_call_preview helper 扩展支持 speed/emotion 参数 - 新增 4 个测试用例： - test_preview_custom_speed_emotion_passed_through：speed/emotion 正确透传到 cosyvoice - test_preview_invalid_emotion_rejected：非法 emotion 返回 400 - test_preview_non_default_speed_no_cache：自定义 speed/emotion 不走缓存 - test_preview_valueerror_from_cosyvoice_returns_400：cosyvoice 抛 ValueError 返回 400 - 现有 10 个测试保持通过；voice_clone + cosyvoice 相关共 293 个测试全通过 Refs: #1897

xiaoxia added 1 commit 2026-09-14 18:49:26 +08:00

fix(backend): #1897 声音克隆preview接口支持情绪语速参数 ... ef54a1ce9c

- apps/api/app/api/routes/voice_clones.py: GET /voice-clones/{clone_id}/preview 新增 speed(float, 0.5-2.0, 默认1.0) 和 emotion(str, 默认空, 枚举 natural/excited/calm/friendly) query 参数
- 参数透传到 cosyvoice.synthesize_speech(speed=..., emotion=...)，CosyVoice 服务层已原生支持无需改动
- emotion 白名单校验：不在 natural/excited/calm/friendly/空 范围返回 400
- 缓存仅在默认参数（默认试听文本+speed=1.0+emotion空）时生效，自定义 speed/emotion 不缓存
- 新增 ValueError 异常处理（speed 越界等参数问题 cosyvoice 抛 ValueError），返回 400（与 TTS preview 接口一致）
- 参考 TTS preview 接口（apps/api/app/api/routes/tts.py）的参数接收与透传方式
- 单测：4 个新用例覆盖 speed/emotion 透传、非法 emotion 400、非默认参数不缓存、ValueError→400，293个voice clone/cosyvoice相关测试全通过

gitea-actions bot commented 2026-09-14 18:50:32 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

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

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

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

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

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

auto-approve-bot merged commit 8ad44ad045 into develop 2026-09-14 18:56:53 +08:00

auto-approve-bot deleted branch fix/1897-voice-clone-preview-emotion-speed-backend 2026-09-14 18:56:53 +08:00

gitea-actions bot commented 2026-09-14 18:57:14 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

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

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

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

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot frontend-dev xiaoxia

No Assignees

2 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#1907