# 音效生成功能明确不支持

**日期**: 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 文档](https://docs.aihubmix.com/cn/api/TTS)：

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

## 实施方案

### 方案选择

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

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

### 代码修改

#### 1. AIHubMixProvider

```python
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 层

```python
@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 响应

### 请求

```bash
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"
}
```

### 响应

```json
{
  "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 更友好

## 测试验证

### 测试用例

```python
# 测试音效生成 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 结构，便于未来扩展
- 文档完善：清晰说明功能限制和解决方案