# RFC 142: ElevenLabs 音频生成服务集成

**状态**: ✅ 已实施  
**创建日期**: 2026-02-10  
**作者**: AI Assistant  
**类型**: 新功能

---

## 概述

集成 ElevenLabs API，为 Jointo 平台提供专业的音频生成能力，包括：
1. **文本转语音（TTS）**：高质量多语言配音生成
2. **音效生成**：基于文本描述生成环境音效
3. **音色管理**：列出和选择可用音色

---

## 动机

### 当前问题
- AIHubMix 仅支持 TTS，不支持专业音效生成
- `generate_sound()` 方法抛出 `NotImplementedError`
- 缺乏音色管理功能

### 解决方案
- 引入 ElevenLabs 作为专业音频生成服务
- 遵循现有 Provider 架构模式
- 与积分系统和任务队列无缝集成

---

## 技术设计

### 1. 架构设计

```
server/app/services/ai_providers/
├── base.py                    # ✅ 扩展基类
├── elevenlabs_provider.py     # ✅ 新增 ElevenLabs Provider
├── factory.py                 # ✅ 注册 ElevenLabs 模型
├── aihubmix_provider.py       # 保持不变
└── mock_provider.py           # 保持不变
```

### 2. 核心组件

#### 2.1 基类扩展（base.py）

新增方法：
```python
async def generate_sound_effect(
    self,
    text: str,
    duration_seconds: Optional[float] = None,
    prompt_influence: float = 0.3,
    **kwargs
) -> Dict[str, Any]:
    """生成音效（ElevenLabs 专用方法）"""
    
async def list_voices(self) -> Dict[str, Any]:
    """列出可用音色（TTS 专用方法）"""
```

#### 2.2 ElevenLabs Provider（elevenlabs_provider.py）

**核心功能**：
1. **音色列表**：`list_voices()` - 获取所有可用音色
2. **文本转语音**：`generate_voice()` - 高质量 TTS
3. **音效生成**：`generate_sound_effect()` - 环境音效生成

**API 集成**：
- 认证：`xi-api-key` Header
- 端点：
  - `GET /v1/voices` - 音色列表
  - `POST /v1/text-to-speech/{voice_id}` - TTS
  - `POST /v1/sound-generation` - 音效生成

**返回格式**：
```python
{
    'audio_data': bytes,  # 原始音频数据
    'audio_url': None,    # 需上传到 S3
    'duration': float,
    'metadata': dict
}
```

#### 2.3 工厂注册（factory.py）

新增模型列表：
```python
ELEVENLABS_MODELS = [
    'eleven_multilingual_v2',  # 多语言 TTS v2
    'eleven_turbo_v2',         # 快速 TTS v2
    'eleven_turbo_v2_5',       # 快速 TTS v2.5
    'eleven_monolingual_v1',   # 单语言 TTS v1
    'eleven_text_to_sound_v2', # 音效生成 v2
]
```

### 3. AI Service 更新

#### 3.1 generate_sound() 方法重构

**变更前**：
```python
async def generate_sound(...):
    raise NotImplementedError("音效生成功能暂不可用")
```

**变更后**：
```python
async def generate_sound(...):
    # 1. 验证用户和项目
    # 2. 检查配额
    # 3. 计算积分
    # 4. 预扣积分
    # 5. 创建任务
    # 6. 提交 Celery 任务
    return {'job_id': ..., 'task_id': ..., 'status': 'pending'}
```

**默认模型**：`eleven_text_to_sound_v2`

### 4. 配置管理

#### 4.1 环境变量（config.py）

```python
ELEVENLABS_API_KEY: str = ""
ELEVENLABS_BASE_URL: str = "https://api.elevenlabs.io"
```

#### 4.2 .env 配置

```bash
# ElevenLabs 音频生成服务
ELEVENLABS_API_KEY=your_api_key_here
ELEVENLABS_BASE_URL=https://api.elevenlabs.io
```

### 5. 依赖管理

#### requirements.txt

```txt
elevenlabs==2.35.0  # ElevenLabs 音频生成服务
```

---

## API 使用示例

### 1. 列出音色

```python
from app.services.ai_providers.factory import AIProviderFactory

provider = AIProviderFactory.create_provider('eleven_multilingual_v2')
voices = await provider.list_voices()

# 返回格式
{
    'voices': [
        {
            'voice_id': 'EXAVITQu4vr4xnSDxMaL',
            'name': 'Sarah',
            'category': 'premade',
            'labels': {'accent': 'american', 'age': 'young'}
        },
        ...
    ]
}
```

### 2. 生成配音

```python
# 通过 AI Service
result = await ai_service.generate_voice(
    user_id='user_123',
    text='你好，欢迎使用 Jointo',
    voice_type='EXAVITQu4vr4xnSDxMaL',  # 音色 ID
    model='eleven_multilingual_v2',
    project_id='project_456'
)

# 返回
{
    'job_id': 'uuid',
    'task_id': 'celery_task_id',
    'status': 'pending',
    'estimated_credits': 10
}
```

### 3. 生成音效

```python
# 通过 AI Service
result = await ai_service.generate_sound(
    user_id='user_123',
    description='海浪拍打沙滩的声音',
    duration=10,
    model='eleven_text_to_sound_v2',
    prompt_influence=0.5,
    loop=False
)

# 返回
{
    'job_id': 'uuid',
    'task_id': 'celery_task_id',
    'status': 'pending',
    'estimated_credits': 15
}
```

---

## 数据流

### 音效生成流程

```
用户请求
  ↓
AI Service.generate_sound()
  ↓
1. 验证用户/项目
2. 检查配额
3. 计算积分（Credit Service）
4. 预扣积分
5. 创建 AIJob 记录
  ↓
Celery Task (generate_sound_task)
  ↓
ElevenLabs Provider.generate_sound_effect()
  ↓
ElevenLabs API
  ↓
返回音频二进制数据
  ↓
上传到 S3（File Storage Service）
  ↓
更新 AIJob 状态和结果
  ↓
用户获取音频 URL
```

---

## 错误处理

### 1. API 错误

```python
try:
    response = await client.post(url, ...)
    response.raise_for_status()
except httpx.HTTPStatusError as e:
    logger.error("ElevenLabs API 错误: status=%d", e.response.status_code)
    raise ValidationError(f"音效生成失败: {e.response.text}")
```

### 2. 配置缺失

```python
if not self.api_key:
    raise ValidationError("ELEVENLABS_API_KEY 未配置")
```

### 3. 参数验证

```python
if duration_seconds is not None:
    if not (0.5 <= duration_seconds <= 30):
        raise ValidationError("duration_seconds 必须在 0.5-30 秒之间")
```

---

## 测试策略

### 1. 单元测试

```python
# tests/unit/services/test_elevenlabs_provider.py
async def test_list_voices():
    provider = ElevenLabsProvider('eleven_multilingual_v2')
    voices = await provider.list_voices()
    assert 'voices' in voices
    assert len(voices['voices']) > 0

async def test_generate_sound_effect():
    provider = ElevenLabsProvider('eleven_text_to_sound_v2')
    result = await provider.generate_sound_effect(
        text='海浪声',
        duration_seconds=5.0
    )
    assert 'audio_data' in result
    assert len(result['audio_data']) > 0
```

### 2. 集成测试

```python
# tests/integration/test_ai_sound_generation.py
async def test_generate_sound_with_credits(client, test_user):
    response = await client.post(
        '/api/v1/ai/sound',
        json={
            'description': '雨声',
            'duration': 10,
            'model': 'eleven_text_to_sound_v2'
        },
        headers={'Authorization': f'Bearer {test_user.token}'}
    )
    assert response.status_code == 200
    assert 'job_id' in response.json()
```

---

## 部署清单

### 1. 环境变量配置

- [ ] 添加 `ELEVENLABS_API_KEY` 到生产环境
- [ ] 验证 `ELEVENLABS_BASE_URL` 配置

### 2. 依赖安装

```bash
docker exec jointo-server-app pip install elevenlabs==1.18.2
```

### 3. 数据库迁移

无需迁移（复用现有 `ai_jobs` 表）

### 4. 服务重启

```bash
docker-compose restart jointo-server-app
docker-compose restart jointo-server-celery-ai
```

---

## 监控指标

### 1. 关键指标

- ElevenLabs API 调用成功率
- 音效生成平均耗时
- 音频文件大小分布
- 积分消耗统计

### 2. 日志监控

```python
logger.info("成功生成音效: text=%s, duration=%s, audio_size=%d bytes", ...)
logger.error("ElevenLabs API 错误: status=%d, response=%s", ...)
```

---

## 未来优化

### 1. 音色缓存

- 缓存 `list_voices()` 结果到 Redis（TTL: 1 小时）
- 减少 API 调用次数

### 2. 音频预处理

- 支持音频格式转换（MP3 → WAV）
- 支持音量归一化

### 3. 批量生成

- 支持批量音效生成
- 优化积分消耗

### 4. 音色推荐

- 基于场景推荐合适音色
- 用户音色偏好记录

---

## 参考资料

- [ElevenLabs API 文档](https://elevenlabs.io/docs/api-reference/introduction)
- [ElevenLabs Python SDK](https://github.com/elevenlabs/elevenlabs-python)
- [音效生成 API](https://elevenlabs.io/docs/api-reference/text-to-sound-effects/convert)

---

## 变更记录

| 日期 | 版本 | 变更内容 | 作者 |
|------|------|---------|------|
| 2026-02-10 | 1.0.0 | 初始版本 | AI Assistant |