# Changelog: ElevenLabs 音频生成服务集成

**日期**: 2026-02-10  
**类型**: 新功能  
**影响范围**: AI 服务、音频生成

---

## 概述

成功集成 ElevenLabs API，为 Jointo 平台提供专业的音频生成能力，包括文本转语音（TTS）和音效生成功能。

---

## 变更内容

### 1. 新增 ElevenLabs Provider

**文件**: `server/app/services/ai_providers/elevenlabs_provider.py`

**功能**:
- ✅ `list_voices()` - 列出可用音色
- ✅ `generate_voice()` - 文本转语音（TTS）
- ✅ `generate_sound_effect()` - 音效生成
- ✅ 完整的错误处理和日志记录

**特性**:
- 支持多语言 TTS（`eleven_multilingual_v2`）
- 支持音效生成（`eleven_text_to_sound_v2`）
- 音色参数自定义（stability, similarity_boost, style）
- 音效参数控制（duration, prompt_influence, loop）

### 2. 扩展 AI Provider 基类

**文件**: `server/app/services/ai_providers/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 专用方法）"""
```

**设计理念**:
- `generate_sound_effect()` 提供默认实现，调用 `generate_sound()`
- `list_voices()` 默认抛出 `NotImplementedError`
- 保持向后兼容性

### 3. 更新 Provider 工厂

**文件**: `server/app/services/ai_providers/factory.py`

**变更**:
- ✅ 导入 `ElevenLabsProvider`
- ✅ 新增 `ELEVENLABS_MODELS` 列表
- ✅ 注册 ElevenLabs 模型到工厂

**支持的模型**:
```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
]
```

### 4. 重构 AI Service 音效生成

**文件**: `server/app/services/ai_service.py`

**变更前**:
```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` 模型
- 支持自定义 `prompt_influence` 和 `loop` 参数
- 完整的积分系统集成

### 5. 配置管理

**文件**: `server/app/core/config.py`

**新增配置**:
```python
ELEVENLABS_API_KEY: str = ""
ELEVENLABS_BASE_URL: str = "https://api.elevenlabs.io"
```

**文件**: `server/.env.example`

**新增环境变量**:
```bash
ELEVENLABS_API_KEY=
ELEVENLABS_BASE_URL=https://api.elevenlabs.io
```

### 6. 依赖管理

**文件**: `server/requirements.txt`

**新增依赖**:
```txt
elevenlabs==2.35.0  # ElevenLabs 音频生成服务
```

---

## 技术细节

### API 认证

使用 `xi-api-key` Header 进行认证：
```python
headers = {
    'xi-api-key': settings.ELEVENLABS_API_KEY,
    'Content-Type': 'application/json'
}
```

### 音频数据处理

ElevenLabs 返回音频二进制数据，需要上传到 S3：
```python
{
    'audio_data': bytes,  # 原始音频数据
    'audio_url': None,    # 需上传到 S3
    'duration': float,
    'metadata': dict
}
```

### 错误处理

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

---

## 使用示例

### 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
result = await ai_service.generate_voice(
    user_id='user_123',
    text='你好，欢迎使用 Jointo',
    voice_type='EXAVITQu4vr4xnSDxMaL',
    model='eleven_multilingual_v2'
)
```

### 3. 生成音效

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

---

## 部署步骤

### 1. 安装依赖

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

### 2. 配置环境变量

在 `.env` 文件中添加：
```bash
ELEVENLABS_API_KEY=your_api_key_here
ELEVENLABS_BASE_URL=https://api.elevenlabs.io
```

### 3. 重启服务

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

---

## 测试验证

### 1. 验证 Provider 创建

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

# 应该返回 ElevenLabsProvider 实例
provider = AIProviderFactory.create_provider('eleven_text_to_sound_v2')
assert provider.__class__.__name__ == 'ElevenLabsProvider'
```

### 2. 验证音效生成

```python
# 通过 AI Service 测试
result = await ai_service.generate_sound(
    user_id='test_user',
    description='测试音效',
    duration=5
)
assert 'job_id' in result
assert 'task_id' in result
```

---

## 影响范围

### 受影响的组件

- ✅ AI Service (`ai_service.py`)
- ✅ AI Provider 基类 (`base.py`)
- ✅ Provider 工厂 (`factory.py`)
- ✅ 配置管理 (`config.py`)
- ✅ Celery 任务 (`ai_tasks.py` - 已存在 `generate_sound_task`）

### 不受影响的组件

- ✅ 数据库模型（复用现有 `ai_jobs` 表）
- ✅ API 路由（复用现有 `/api/v1/ai/sound` 端点）
- ✅ 积分系统（无需修改）

---

## 已知限制

1. **音频时长限制**: 0.5-30 秒
2. **音频格式**: 默认 MP3，支持 PCM/WAV（需订阅）
3. **音色管理**: 需要手动调用 `list_voices()` 获取
4. **音频时长**: ElevenLabs 不返回音频时长，需解析音频文件

---

## 后续优化

1. **音色缓存**: 缓存 `list_voices()` 结果到 Redis
2. **音频预处理**: 支持格式转换和音量归一化
3. **批量生成**: 支持批量音效生成
4. **音色推荐**: 基于场景推荐合适音色

---

## 相关文档

- [RFC 142: ElevenLabs 集成](../rfcs/142-elevenlabs-integration.md)
- [ElevenLabs API 文档](https://elevenlabs.io/docs/api-reference/introduction)
- [后端架构指南](../guides/backend-architecture.md)

---

## 变更文件清单

### 新增文件
- `server/app/services/ai_providers/elevenlabs_provider.py`
- `docs/server/rfcs/142-elevenlabs-integration.md`
- `docs/server/changelogs/2026-02-10-elevenlabs-integration.md`

### 修改文件
- `server/app/services/ai_providers/base.py`
- `server/app/services/ai_providers/factory.py`
- `server/app/services/ai_service.py`
- `server/app/core/config.py`
- `server/requirements.txt`
- `server/.env.example`

---

## 总结

成功集成 ElevenLabs API，为 Jointo 平台提供专业的音频生成能力。遵循现有架构模式，与积分系统和任务队列无缝集成，代码质量通过诊断检查，无语法错误。