7.4 KiB

Raw Permalink Blame History

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

新增方法:

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 模型到工厂

支持的模型:

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

变更前:

async def generate_sound(...):
    raise NotImplementedError("音效生成功能暂不可用")

变更后:

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

新增配置:

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

文件: server/.env.example

新增环境变量:

ELEVENLABS_API_KEY=
ELEVENLABS_BASE_URL=https://api.elevenlabs.io

6. 依赖管理

文件: server/requirements.txt

新增依赖:

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

技术细节

API 认证

使用 xi-api-key Header 进行认证：

headers = {
    'xi-api-key': settings.ELEVENLABS_API_KEY,
    'Content-Type': 'application/json'
}

音频数据处理

ElevenLabs 返回音频二进制数据，需要上传到 S3：

{
    'audio_data': bytes,  # 原始音频数据
    'audio_url': None,    # 需上传到 S3
    'duration': float,
    'metadata': dict
}

错误处理

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. 列出音色

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. 生成配音

result = await ai_service.generate_voice(
    user_id='user_123',
    text='你好，欢迎使用 Jointo',
    voice_type='EXAVITQu4vr4xnSDxMaL',
    model='eleven_multilingual_v2'
)

3. 生成音效

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

部署步骤

1. 安装依赖

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

2. 配置环境变量

在 .env 文件中添加：

ELEVENLABS_API_KEY=your_api_key_here
ELEVENLABS_BASE_URL=https://api.elevenlabs.io

3. 重启服务

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

测试验证

1. 验证 Provider 创建

from app.services.ai_providers.factory import AIProviderFactory

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

2. 验证音效生成

# 通过 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 端点）
✅ 积分系统（无需修改）

已知限制

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

后续优化

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

变更文件清单

新增文件

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 平台提供专业的音频生成能力。遵循现有架构模式，与积分系统和任务队列无缝集成，代码质量通过诊断检查，无语法错误。

7.4 KiB Raw Permalink Blame History