ElevenLabs 工具包

通过 FastAPI 接口或独立 Python 函数，以编程方式访问全部 7 项 ElevenLabs API 功能。

何时使用此工具包 / 何时不应使用此工具包

在以下场景中使用 ElevenLabs：

• 为视频、演示文稿或内容生成高质量旁白音频（尤其推荐使用 Rachel 或其他保持一致的角色音色）
• 构建需要实时流式语音输出的语音交互型应用
• 对音频文件执行语音转文字（STT/Scribe）
• 根据文本描述生成环境音效或背景音乐
• 从嘈杂录音中分离出清晰的人声

请勿在以下场景中使用 ElevenLabs：

• 您需要快速/低成本且对音质无要求的 TTS —— 请改用 本地 TTS（见下文）
• 您处于离线状态，或无法获取 API 密钥
• 您正在批量生成大量测试音频，且不希望消耗角色配额

ElevenLabs vs 本地 TTS（kokoro / chatterbox）

经验法则：凡面向终端用户展示/播放的内容，请使用 ElevenLabs；草稿、测试及高吞吐量任务，请使用本地 TTS。

功能列表

已知音色 ID

以下为 OpenClaw 工作流中已验证可用的音色。请优先使用这些 ID，而非调用 API 获取完整列表：

所有旁白任务的默认音色：除非明确指定其他音色，否则一律使用 Rachel（21m00Tcm4TlvDq8ikWAM）。

如需通过 API 获取当前完整音色列表：

curl -s -H "xi-api-key: $ELEVENLABS_API_KEY" https://api.elevenlabs.io/v1/voices | python3 -m json.tool

快速上手

import httpx

BASE = "http://localhost:8000"  # 您的 FastAPI 应用地址
KEY = os.environ["ELEVENLABS_API_KEY"]

# 获取音色列表
voices = httpx.get(f"{BASE}/api/voices").json()

# 生成语音
audio = httpx.post(f"{BASE}/api/voice/tts", json={
    "text": "Hello world",
    "voice_id": voices[0]["voice_id"],
    "model_id": "eleven_multilingual_v2"
}).content  # 返回原始音频字节

# 生成音效
sfx = httpx.post(f"{BASE}/api/voice/sfx", json={
    "prompt": "ocean waves on a quiet beach at night"
}).content

音频输出格式

TTS 和 SFX 接口返回原始音频字节（非 base64 编码，也非 JSON 格式）。

# 正确：.content 即为字节流
audio_bytes = response.content  # 类型：bytes

# 保存为文件
with open("output.mp3", "wb") as f:
    f.write(audio_bytes)

# 默认输出格式为 MP3
# 文件大小估算：标准质量下，每分钟语音约 1 MB

各接口返回内容说明：

音色选择指南

• 仅英文场景：使用 eleven_turbo_v2_5 — 更快，且无跨语言口音混杂问题
• 多语言场景：使用 eleven_multilingual_v2 — 支持 29 种语言
• 口音注意事项：多语言模型可能在不同语言间产生口音混杂。若英文音色听上去带有日语口音，请切换至 turbo 模型。

配额管理

ElevenLabs 对 TTS 按字符计费。关键实践建议：

• 积极缓存 — 相同文本 + 相同音色 = 相同音频输出
• 使用 prompt-cache 技能，在调用 TTS 前通过 SHA-256 去重
• 一篇 6 场景儿童故事 ≈ 2,000 字符
• 免费版：每月 10k 字符；入门版：30k；创作者版：100k。

集成方式

将 scripts/elevenlabs_api.py 复制到您的 FastAPI 应用中，并挂载路由：

from elevenlabs_api import router
app.include_router(router)

在环境中设置 ELEVENLABS_API_KEY。所有接口均具备完善的错误处理能力，并返回标准 HTTP 状态码。

若 FastAPI 服务未运行怎么办？

快速上手示例默认假设 http://localhost:8000 已就绪。若服务未启动：

# 调用前检查服务是否在线
import httpx

try:
    httpx.get("http://localhost:8000/health", timeout=2.0)
except httpx.ConnectError:
    # 服务未运行 — 先启动它
    import subprocess
    subprocess.Popen(["uvicorn", "elevenlabs_api:app", "--port", "8000"])
    import time; time.sleep(2)  # 留出端口绑定时间

或绕过 FastAPI 封装，直接调用 ElevenLabs 原生 API — scripts/elevenlabs_api.py 中的函数可作为独立模块导入：

from elevenlabs_api import generate_tts  # 若该模块导出了独立函数

错误处理：API 密钥与速率限制

缺失 API 密钥：

httpx.HTTPStatusError: 401 Unauthorized
{"detail": {"status": "unauthorized", "message": "Invalid API key"}}

→ 检查 ELEVENLABS_API_KEY 是否已设置：echo $ELEVENLABS_API_KEY
→ 从 1Password 获取密钥：op read "op://OpenClaw/ElevenLabs API Credentials/credential"

触发速率限制（429）：

{"detail": {"status": "too_many_requests", "message": "Too many requests"}}

→ 等待后重试，并采用指数退避策略。ElevenLabs 免费版/入门版的速率限制按分钟计算。
→ 创作者版及以上版本限制大幅提高 — 请登录 ElevenLabs 控制台查看您的订阅等级。

配额耗尽：

{"detail": {"status": "quota_exceeded", "message": "Quota exceeded"}}

→ 当月字符配额已用完。请等待每月重置，或升级订阅等级。
→ 查看当前用量：curl -s -H "xi-api-key: $KEY" https://api.elevenlabs.io/v1/user/subscription

相关文件

• scripts/elevenlabs_api.py — 包含全部 7 个接口的 FastAPI 路由实现

常见错误

1. 将字节响应误当作 JSON 处理

   • ❌ 对 TTS 请求调用 response.json() → 触发 JSONDecodeError
   • ✅ 使用 response.content 获取原始字节，再写入 .mp3 文件

2. 使用错误的音色 ID

   • ElevenLabs 音色 ID 是不可读的字符串，而非音色名称
   • ❌ "voice_id": "Rachel" → 返回 404 或错误音色
   • ✅ "voice_id": "21m00Tcm4TlvDq8ikWAM"（Rachel 的真实 ID）

3. 未启用缓存即批量调用 TTS

   • 相同文本 + 相同音色始终生成相同音频 — 请避免重复生成已缓存结果
   • 否则将不必要地消耗字符配额

4. 对纯英文内容使用多语言模型

   • eleven_multilingual_v2 在纯英文场景下更慢，且易出现口音失真
   • 纯英文任务请使用 eleven_turbo_v2_5

5. 调用前未确认 FastAPI 服务已运行

   • 若忽略本地服务依赖，httpx.ConnectError 错误信息较难理解
   • 建议在调用接口前增加健康检查或自动启服逻辑

安全说明

本技能采用的部分模式可能被自动化安全扫描器标记：

• base64：用于媒体类 API 响应中音频/二进制数据的编码（行业通用实践）
• UploadFile：FastAPI 内置的文件上传参数，用于 STT/人声分离等接口
• "system prompt"：指代理指令配置，不涉及提示注入攻击