docs/v1.0/server/changelogs/2026-01-31-sound-generation-not-implemented.md

音效生成功能明确不支持

日期: 2026-01-31
类型: 功能说明 / API 改进
影响范围: AI Service, API 层

背景

在测试音效生成功能时发现，AIHubMix 不支持环境音效生成。AIHubMix 仅提供 TTS（文本转语音）功能，无法根据描述生成环境声音（如海浪、风声、鸟叫等）。

问题分析

TTS vs 音效生成

功能	输入	输出	AIHubMix 支持
TTS（配音）	文本	语音朗读	✅ 支持
音效生成	描述	环境声音	❌ 不支持

示例：

• TTS: "Hello, this is a test" → 语音朗读这段文字
• 音效: "Ocean waves crashing on a beach" → 海浪声音效

AIHubMix TTS API

根据 AIHubMix TTS 文档：

• 支持模型：tts-1, tts-1-hd, gpt-4o-mini-tts, gemini-2.5-flash-preview-tts
• 功能：将文本转换为语音
• 不支持：根据描述生成环境音效

实施方案

方案选择

选择了方案 3：保留 API，返回 501 Not Implemented

优点：

• 用户立即得到明确反馈
• 不消耗积分
• 不创建无效任务
• 为未来集成其他 Provider 预留空间

代码修改

1. AIHubMixProvider

async def generate_sound(
    self,
    description: str,
    duration: int = 5,
    **kwargs
) -> Dict[str, Any]:
    """AIHubMix 不支持音效生成
    
    注意：AIHubMix 仅支持 TTS（文本转语音），不支持环境音效生成。
    如需音效生成功能，请考虑集成以下 Provider：
    - ElevenLabs Sound Effects
    - Stability AI Stable Audio
    """
    logger.warning("AIHubMix 不支持音效生成功能")
    raise NotImplementedError(
        "音效生成功能暂不可用。AIHubMix 仅支持 TTS（文本转语音），"
        "不支持环境音效生成。请联系管理员集成专业音效生成服务。"
    )

2. API 层

@router.post("/generate-sound", response_model=ApiResponse[AIJobResponse])
async def generate_sound(
    request: GenerateSoundRequest,
    current_user: User = Depends(get_current_user),
    db: AsyncSession = Depends(get_session)
):
    """生成音效
    
    注意：当前 AI Provider 不支持音效生成功能
    """
    try:
        result = await service.generate_sound(...)
        return success_response(data=result)
    except NotImplementedError as e:
        logger.warning("音效生成功能不可用: user_id=%s, error=%s", current_user.user_id, str(e))
        raise HTTPException(
            status_code=status.HTTP_501_NOT_IMPLEMENTED,
            detail=str(e)
        )
    # ... 其他异常处理

API 响应

请求

POST /api/v1/ai/generate-sound
Authorization: Bearer <token>
Content-Type: application/json

{
  "description": "Ocean waves crashing on a beach with seagulls",
  "duration": 5,
  "sound_type": "nature"
}

响应

{
  "success": false,
  "message": "音效生成功能暂不可用。AIHubMix 仅支持 TTS（文本转语音），不支持环境音效生成。请联系管理员集成专业音效生成服务。",
  "code": 501
}

HTTP 状态码: 501 Not Implemented

用户体验

优点

1. 明确反馈：用户立即知道功能不可用
2. 不扣积分：不会预扣用户积分
3. 清晰说明：错误信息解释了原因和解决方案
4. 保留 API：未来可以无缝集成其他 Provider

错误信息

音效生成功能暂不可用。AIHubMix 仅支持 TTS（文本转语音），
不支持环境音效生成。请联系管理员集成专业音效生成服务。

未来计划

短期（已完成）

• ✅ API 返回 501 Not Implemented
• ✅ 提供清晰的错误信息
• ✅ 更新文档

中期

集成专业音效生成 Provider：

1. ElevenLabs Sound Effects

   • 高质量音效生成
   • 支持多种音效类型
   • API 文档：https://elevenlabs.io/docs/api-reference/sound-generation

2. Stability AI Stable Audio

   • 开源音效生成模型
   • 支持自定义训练
   • 文档：https://stability.ai/stable-audio

3. AudioCraft (Meta)

   • Meta 开源音效生成
   • 支持音乐和音效
   • GitHub：https://github.com/facebookresearch/audiocraft

长期

• 等待 AIHubMix 支持音效生成 API（如果有计划）
• 或保持使用第三方专业服务

相关文件

修改的文件

• server/app/services/ai_providers/aihubmix_provider.py - 更新 generate_sound() 方法
• server/app/api/v1/ai.py - 添加 NotImplementedError 异常处理
• server/app/services/ai_service.py - 添加注释说明
• docs/server/changelogs/2026-01-31-ai-功能测试总结.md - 更新测试结果

测试脚本

• server/scripts/test_ai_sound_generation_e2e.py - 音效生成测试（返回 501）

技术细节

HTTP 状态码选择

选择 501 Not Implemented 而不是 404 Not Found 或 400 Bad Request：

• 501 Not Implemented：服务器不支持该功能 ✅
• 404 Not Found：资源不存在 ❌
• 400 Bad Request：请求参数错误 ❌
• 503 Service Unavailable：服务暂时不可用 ❌

为什么不删除 API

保留 API 端点的原因：

1. 向后兼容：前端可能已经集成了该 API
2. 数据库结构：ai_jobs 表已经支持音效任务类型
3. 未来扩展：可以无缝集成其他 Provider
4. 清晰反馈：返回 501 比删除 API 更友好

测试验证

测试用例

# 测试音效生成 API
response = await client.post(
    "/api/v1/ai/generate-sound",
    json={
        "description": "Ocean waves",
        "duration": 5
    },
    headers={"Authorization": f"Bearer {token}"}
)

assert response.status_code == 501
assert "暂不可用" in response.json()["message"]
assert "TTS" in response.json()["message"]

预期结果

• ✅ 返回 501 状态码
• ✅ 错误信息清晰
• ✅ 不扣除积分
• ✅ 不创建任务记录

总结

通过明确音效生成功能不支持，避免了用户困惑和无效任务创建。同时为未来集成专业音效生成服务预留了空间。

关键改进：

• 用户体验：立即得到明确反馈
• 系统稳定性：不创建无效任务
• 可维护性：保留 API 结构，便于未来扩展
• 文档完善：清晰说明功能限制和解决方案