ElevenLabs Toolkit

Programmatic access to all 7 ElevenLabs API capabilities via FastAPI endpoints or standalone Python functions.

When to Use This / When NOT to Use This

Use ElevenLabs when:

- Generating high-quality narration audio for videos, demos, or content (especially with Rachel or a consistent character voice)
Building a voice-enabled app that needs streamed speech in real-time
Transcribing audio files (STT/Scribe)
Generating ambient sound effects or background music from text descriptions
Isolating clean voice from a noisy recording

Do NOT use ElevenLabs when:

- You need fast/cheap TTS with no quality bar — use local TTS instead (see below)
You're offline or the API key isn't available
You're generating large volumes of test audio and don't want to burn character quota

ElevenLabs vs Local TTS (kokoro / chatterbox)

Criteria	ElevenLabs	Local TTS (kokoro/chatterbox)
Voice quality	★★★★★ — natural, expressive	★★★ — good but robotic edges
Cost

Rule of thumb: Use ElevenLabs for anything that will be seen/heard by a user. Use local TTS for drafts, tests, and volume work.

Capabilities

Tool	Endpoint	What It Does
Voices	GET /api/voices	Browse available voices with metadata
TTS

Known Voice IDs

These are confirmed voices used in OpenClaw workflows. Always prefer these over browsing the full list:

Voice	Voice ID	Best For
Rachel	INLINECODE0	Default narration — clear, warm, American English
Adam

Default for all narration tasks: Use Rachel (21m00Tcm4TlvDq8ikWAM) unless explicitly specified otherwise.

To get the full current list from the API:

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

Quick Start

CODEBLOCK1

Audio Output Format

TTS and SFX endpoints return raw audio bytes (not base64, not JSON).

CODEBLOCK2

What you get back from each endpoint:

Endpoint	Response type	How to handle
POST /api/voice/tts	INLINECODE5 (MP3)	Write directly to `.mp3` file
POST /api/voice/sfx

bytes (MP3) | Write directly to .mp3 file |
| POST /api/voice/music | bytes (MP3) | Write directly to .mp3 file |
| POST /api/voice/stt | JSON | {"text": "transcription...", "language": "en"} |
| POST /api/voice/isolate | bytes (MP3) | Write directly to .mp3 file |
| GET /api/voices | JSON | List of {voice_id, name, labels, ...} |

Voice Selection Guide

- English only: Use eleven_turbo_v2_5 — faster, no accent bleed
Multilingual: Use eleven_multilingual_v2 — supports 29 languages
Accent warning: Multilingual model can bleed accents across languages. If an English voice sounds Japanese, switch to turbo.

Quota Management

ElevenLabs charges per character for TTS. Key patterns:

- Cache aggressively — identical text + voice = identical audio
Use prompt-cache skill for SHA-256 dedup before calling TTS
A 6-scene children's story ≈ 2,000 characters
Free tier: 10k chars/month. Starter: 30k. Creator: 100k.

Integration

Copy scripts/elevenlabs_api.py into your FastAPI app and mount the router:

CODEBLOCK3

Set ELEVENLABS_API_KEY in your environment. All endpoints handle errors gracefully with proper HTTP status codes.

What If the FastAPI Server Isn't Running?

The Quick Start examples assume http://localhost:8000 is live. If it's not:

CODEBLOCK4

Or call the ElevenLabs API directly without the FastAPI wrapper — the scripts/elevenlabs_api.py functions are importable standalone:

CODEBLOCK5

Error Handling: API Key and Rate Limits

Missing API key:

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

→ Check ELEVENLABS_API_KEY is set: echo $ELEVENLABS_API_KEY
→ Retrieve from 1Password: INLINECODE26

Rate limited (429):

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

→ Wait and retry with exponential backoff. ElevenLabs rate limits are per-minute on the free/starter tiers.
→ On Creator tier and above, limits are much higher — check your tier in the ElevenLabs dashboard.

Quota exhausted:

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

→ Character quota for the month is used up. Either wait for monthly reset or upgrade tier.
→ Check current usage: curl -s -H "xi-api-key: $KEY" https://api.elevenlabs.io/v1/user/subscription

Files

- scripts/elevenlabs_api.py — FastAPI router with all 7 endpoints

Common Mistakes

1. Treating the response as JSON when it's bytes

- ❌ response.json() on a TTS call → JSONDecodeError - ✅ response.content → raw bytes, then write to INLINECODE32

2. Using the wrong voice ID

- ElevenLabs voice IDs are opaque strings, not names - ❌ "voice_id": "Rachel" → 404 or wrong voice - ✅ "voice_id": "21m00Tcm4TlvDq8ikWAM" (Rachel's actual ID)

3. Calling TTS for large batches without caching

- Identical text+voice always produces identical audio — don't re-generate what's already cached - Burns character quota unnecessarily

4. Using multilingual model for English-only content

- eleven_multilingual_v2 is slower and can produce accent artifacts on English-only text - Use eleven_turbo_v2_5 for English-only work

5. Not checking the FastAPI server is running before calling

- httpx.ConnectError is confusing if you forget the local server dependency - Add a health check or start-server step before calling endpoints

Security Notes

This skill uses patterns that may trigger automated security scanners:

- base64: Used for encoding audio/binary data in API responses (standard practice for media APIs)
UploadFile: FastAPI's built-in file upload parameter for STT/voice isolation endpoints
"system prompt": Refers to configuring agent instructions, not prompt injection

ElevenLabs 工具包

通过 FastAPI 端点或独立 Python 函数，以编程方式访问所有 7 项 ElevenLabs API 功能。

何时使用 / 何时不使用

使用 ElevenLabs 的场景：

- 为视频、演示或内容生成高质量旁白音频（尤其是使用 Rachel 或一致的语音角色）
构建需要实时流式语音的语音应用
转录音频文件（语音转文字/听写）
根据文本描述生成环境音效或背景音乐
从嘈杂录音中分离纯净人声

不使用 ElevenLabs 的场景：

- 需要快速/廉价且对质量无要求的文本转语音——改用本地文本转语音（见下文）
处于离线状态或无法获取 API 密钥
生成大量测试音频且不想消耗字符配额

ElevenLabs 与本地文本转语音（kokoro / chatterbox）对比

标准	ElevenLabs	本地文本转语音（kokoro/chatterbox）
语音质量	★★★★★ — 自然、富有表现力	★★★ — 不错但带有机械感
成本

经验法则： 任何用户会看到/听到的内容使用 ElevenLabs。草稿、测试和批量处理使用本地文本转语音。

功能

工具	端点	功能说明
语音	GET /api/voices	浏览可用语音及其元数据
文本转语音

已知语音 ID

以下是在 OpenClaw 工作流中确认使用的语音。优先使用这些而非浏览完整列表：

语音	语音 ID	最佳用途
Rachel	21m00Tcm4TlvDq8ikWAM	默认旁白 — 清晰、温暖、美式英语
Adam

所有旁白任务的默认设置： 除非明确指定，否则使用 Rachel（21m00Tcm4TlvDq8ikWAM）。

要从 API 获取当前完整列表：
bash
curl -s -H xi-api-key: $ELEVENLABSAPIKEY https://api.elevenlabs.io/v1/voices | python3 -m json.tool

快速开始

python
import httpx

BASE = http://localhost:8000 # 你的 FastAPI 应用
KEY = os.environ[ELEVENLABSAPIKEY]

获取语音

voices = httpx.get(f{BASE}/api/voices).json()

生成语音

audio = httpx.post(f{BASE}/api/voice/tts, json={ text: 你好世界, voiceid: voices[0][voiceid], modelid: elevenmultilingual_v2 }).content # 返回原始音频字节

生成音效

sfx = httpx.post(f{BASE}/api/voice/sfx, json={ prompt: 夜晚安静海滩上的海浪声 }).content

音频输出格式

文本转语音和音效端点返回原始音频字节（非 base64，非 JSON）。

python

正确：.content 返回字节

audio_bytes = response.content # 类型：bytes

保存到文件

with open(output.mp3, wb) as f: f.write(audio_bytes)

文件格式默认为 MP3

文件大小估算：标准质量下每分钟语音约 1 MB

每个端点返回的内容：

端点	响应类型	处理方式
POST /api/voice/tts	bytes (MP3)	直接写入 .mp3 文件
POST /api/voice/sfx

bytes (MP3) | 直接写入 .mp3 文件 |
| POST /api/voice/music | bytes (MP3) | 直接写入 .mp3 文件 |
| POST /api/voice/stt | JSON | {text: 转录内容..., language: en} |
| POST /api/voice/isolate | bytes (MP3) | 直接写入 .mp3 文件 |
| GET /api/voices | JSON | {voice_id, name, labels, ...} 列表 |

语音选择指南

- 仅英语： 使用 eleventurbov25 — 更快，无口音干扰
多语言： 使用 elevenmultilingual_v2 — 支持 29 种语言
口音警告： 多语言模型可能导致口音在不同语言间混淆。如果英语语音听起来像日语，请切换为 turbo。

配额管理

ElevenLabs 按字符数对文本转语音收费。关键模式：

- 积极缓存 — 相同文本 + 语音 = 相同音频
在调用文本转语音前使用 prompt-cache 技能进行 SHA-256 去重
一个 6 场景的儿童故事 ≈ 2,000 字符
免费套餐：每月 10k 字符。入门套餐：30k。创作者套餐：100k。

集成

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

python
from elevenlabs_api import router
app.include_router(router)

在环境中设置 ELEVENLABSAPIKEY。所有端点都能优雅地处理错误并返回适当的 HTTP 状态码。

如果 FastAPI 服务器未运行怎么办？

快速开始示例假设 http://localhost:8000 正在运行。如果未运行：

python

在调用前检查服务器是否启动

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) # 给它一点时间绑定

或者直接调用 ElevenLabs API 而不使用 FastAPI 包装器 — scripts/elevenlabs_api.py 中的函数可以独立导入：

python
from elevenlabsapi import generatetts # 如果模块暴露了独立函数

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

缺少 API 密钥：

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

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

速率限制（429）：
json
{detail: {status: toomanyrequests, message: Too many requests}}

→ 等待并使用指数退避重试。免费/入门套餐的 ElevenLabs 速率限制按分钟计算。
→ 创作者及以上套餐的限制更高 — 在 ElevenLabs 控制面板中查看你的套餐。

配额耗尽：
json
{detail: {status: quota_exceeded, message: Quota exceeded}}

→ 当月字符配额已用完。等待月度重置或升级套餐。
→ 检查当前使用情况：curl

ElevenLabs工具集

ElevenLabs工具集

ElevenLabs Toolkit

When to Use This / When NOT to Use This

ElevenLabs vs Local TTS (kokoro / chatterbox)

Capabilities

Known Voice IDs

Quick Start

Audio Output Format

Voice Selection Guide

Quota Management

Integration

What If the FastAPI Server Isn't Running?

Error Handling: API Key and Rate Limits

Files

Common Mistakes

Security Notes

ElevenLabs 工具包

何时使用 / 何时不使用

ElevenLabs 与本地文本转语音（kokoro / chatterbox）对比

功能

已知语音 ID

快速开始

获取语音

生成语音

生成音效

音频输出格式

正确：.content 返回字节

保存到文件

文件格式默认为 MP3

文件大小估算：标准质量下每分钟语音约 1 MB

语音选择指南

配额管理

集成

如果 FastAPI 服务器未运行怎么办？

在调用前检查服务器是否启动

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

标签

通过对话安装

方式一：安装 SkillHub 和技能

方式二：设置 SkillHub 为优先技能安装源

通过命令行安装

下载

相关推荐

self-improvement

self-improvement

self-improvement

self-improvement