API 参考 #
概述 #
ElevenLabs 提供完整的 REST API 和 WebSocket API，支持文本转语音、语音管理、实时对话等功能。
text
┌─────────────────────────────────────────────────────────────┐
│ API 架构 │
├─────────────────────────────────────────────────────────────┤
│ │
│ Base URL: https://api.elevenlabs.io/v1 │
│ │
│ 认证方式： │
│ ├── API Key (Header: xi-api-key) │
│ └── Bearer Token (Header: Authorization) │
│ │
│ 响应格式： │
│ ├── JSON (元数据) │
│ └── Binary (音频数据) │
│ │
└─────────────────────────────────────────────────────────────┘
认证 #
API Key 认证 #
bash
# 使用 xi-api-key Header
curl -H "xi-api-key: your_api_key" \
https://api.elevenlabs.io/v1/voices
# 使用 Bearer Token
curl -H "Authorization: Bearer your_api_key" \
https://api.elevenlabs.io/v1/voices
SDK 认证 #
python
from elevenlabs import ElevenLabs
client = ElevenLabs(api_key="your_api_key")
javascript
import { ElevenLabsClient } from "elevenlabs";
const client = new ElevenLabsClient({
apiKey: process.env.ELEVENLABS_API_KEY,
});
文本转语音 API #
POST /text-to-speech/ #
生成语音音频。
请求
bash
POST /v1/text-to-speech/{voice_id}
Content-Type: application/json
xi-api-key: your_api_key
{
"text": "Hello, world!",
"model_id": "eleven_multilingual_v2",
"voice_settings": {
"stability": 0.5,
"similarity_boost": 0.75,
"style": 0.0,
"use_speaker_boost": false
},
"output_format": "mp3_44100_128"
}
参数
text
┌─────────────────────────────────────────────────────────────┐
│ 请求参数 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 路径参数： │
│ └── voice_id (string, required) - 语音 ID │
│ │
│ 请求体： │
│ ├── text (string, required) - 要转换的文本 │
│ ├── model_id (string) - 模型 ID │
│ ├── voice_settings (object) - 语音设置 │
│ │ ├── stability (float) - 稳定性 0.0-1.0 │
│ │ ├── similarity_boost (float) - 相似度增强 0.0-1.0 │
│ │ ├── style (float) - 风格 0.0-1.0 │
│ │ └── use_speaker_boost (boolean) - 说话者增强 │
│ ├── output_format (string) - 输出格式 │
│ └── language_code (string) - 语言代码 │
│ │
└─────────────────────────────────────────────────────────────┘
响应
text
成功：200 OK
Content-Type: audio/mpeg
Body: 二进制音频数据
错误：4xx/5xx
Content-Type: application/json
{
"detail": {
"status": "error",
"message": "Error description"
}
}
POST /text-to-speech/{voice_id}/stream #
流式生成语音音频。
请求
bash
POST /v1/text-to-speech/{voice_id}/stream
Content-Type: application/json
xi-api-key: your_api_key
{
"text": "Long text content...",
"model_id": "eleven_multilingual_v2",
"voice_settings": {
"stability": 0.5,
"similarity_boost": 0.75
},
"output_format": "mp3_44100_128"
}
响应
text
成功：200 OK
Content-Type: audio/mpeg
Transfer-Encoding: chunked
Body: 流式二进制音频数据
语音管理 API #
GET /voices #
获取所有语音列表。
请求
bash
GET /v1/voices
xi-api-key: your_api_key
响应
json
{
"voices": [
{
"voice_id": "JBFqnCBsd6RMkjVDRZzb",
"name": "Rachel",
"samples": [],
"category": "premade",
"labels": {
"gender": "female",
"accent": "american"
},
"description": null
}
]
}
GET /voices/ #
获取单个语音详情。
请求
bash
GET /v1/voices/{voice_id}
xi-api-key: your_api_key
响应
json
{
"voice_id": "JBFqnCBsd6RMkjVDRZzb",
"name": "Rachel",
"samples": [],
"category": "premade",
"labels": {
"gender": "female",
"accent": "american"
},
"description": null,
"preview_url": "https://...",
"settings": {
"stability": 0.5,
"similarity_boost": 0.75
}
}
POST /voices/add #
添加新语音（克隆）。
请求
bash
POST /v1/voices/add
Content-Type: multipart/form-data
xi-api-key: your_api_key
files: [audio_file.mp3]
name: "My Voice"
description: "Custom cloned voice"
labels: {"gender": "male"}
响应
json
{
"voice_id": "new_voice_id",
"name": "My Voice",
"category": "cloned"
}
POST /voices/{voice_id}/edit #
编辑语音。
请求
bash
POST /v1/voices/{voice_id}/edit
Content-Type: multipart/form-data
xi-api-key: your_api_key
name: "Updated Name"
description: "Updated description"
files: [new_audio.mp3]
DELETE /voices/ #
删除语音。
请求
bash
DELETE /v1/voices/{voice_id}
xi-api-key: your_api_key
响应
text
200 OK
{
"status": "ok"
}
模型 API #
GET /models #
获取可用模型列表。
请求
bash
GET /v1/models
xi-api-key: your_api_key
响应
json
{
"models": [
{
"model_id": "eleven_multilingual_v2",
"name": "Eleven Multilingual v2",
"can_be_finetuned": false,
"can_do_text_to_speech": true,
"can_do_voice_conversion": false,
"can_use_style": true,
"can_use_speaker_boost": true,
"serves_provided_models": null,
"token_cost_factor": 1.0,
"description": "Latest multilingual model",
"languages": [
{"language_id": "en", "name": "English"},
{"language_id": "zh", "name": "Chinese"}
]
}
]
}
用户 API #
GET /user #
获取用户信息。
请求
bash
GET /v1/user
xi-api-key: your_api_key
响应
json
{
"subscription": {
"tier": "starter",
"character_count": 5000,
"character_limit": 10000,
"can_extend_character_limit": true,
"allowed_to_extend_character_limit": true,
"voice_limit": 3,
"max_voice_add_edits": 10,
"voice_add_edit_counter": 2
},
"is_new_user": false
}
GET /user/subscription #
获取订阅信息。
请求
bash
GET /v1/user/subscription
xi-api-key: your_api_key
响应
json
{
"tier": "starter",
"character_count": 5000,
"character_limit": 10000,
"voice_limit": 3,
"next_character_count_reset_unix": 1712345678
}
历史记录 API #
GET /history #
获取生成历史。
请求
bash
GET /v1/history?pageSize=10
xi-api-key: your_api_key
响应
json
{
"history": [
{
"history_item_id": "item_id",
"voice_id": "voice_id",
"voice_name": "Rachel",
"text": "Generated text",
"date_unix": 1712345678,
"character_count_from_request": 15,
"content_type": "audio/mpeg",
"state": "complete",
"settings": {
"stability": 0.5,
"similarity_boost": 0.75
}
}
],
"last_history_item_id": "last_item_id",
"has_more": true
}
GET /history/ #
获取历史项详情。
请求
bash
GET /v1/history/{history_item_id}
xi-api-key: your_api_key
GET /history/{history_item_id}/audio #
下载历史项音频。
请求
bash
GET /v1/history/{history_item_id}/audio
xi-api-key: your_api_key
响应
text
200 OK
Content-Type: audio/mpeg
Body: 二进制音频数据
DELETE /history/ #
删除历史项。
请求
bash
DELETE /v1/history/{history_item_id}
xi-api-key: your_api_key
WebSocket API #
实时语音流 #
连接
text
wss://api.elevenlabs.io/v1/text-to-speech/{model_id}/stream-input
认证
json
{
"text": " ",
"voice_settings": {
"stability": 0.5,
"similarity_boost": 0.75
},
"xi_api_key": "your_api_key"
}
发送文本
json
{
"text": "Hello, this is a test.",
"flush": true
}
接收音频
text
Binary audio chunks
关闭连接
json
{
"text": ""
}
错误处理 #
HTTP 状态码 #
text
┌─────────────────────────────────────────────────────────────┐
│ 状态码说明 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 2xx 成功： │
│ ├── 200 OK - 请求成功 │
│ └── 201 Created - 资源创建成功 │
│ │
│ 4xx 客户端错误： │
│ ├── 400 Bad Request - 请求参数错误 │
│ ├── 401 Unauthorized - 认证失败 │
│ ├── 403 Forbidden - 权限不足 │
│ ├── 404 Not Found - 资源不存在 │
│ ├── 422 Unprocessable Entity - 内容违规 │
│ └── 429 Too Many Requests - 请求过于频繁 │
│ │
│ 5xx 服务器错误： │
│ ├── 500 Internal Server Error - 服务器错误 │
│ ├── 502 Bad Gateway - 网关错误 │
│ └── 503 Service Unavailable - 服务不可用 │
│ │
└─────────────────────────────────────────────────────────────┘
错误响应格式 #
json
{
"detail": {
"status": "invalid_api_key",
"message": "Invalid API key provided"
}
}
错误类型 #
text
┌─────────────────────────────────────────────────────────────┐
│ 错误类型 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 认证错误： │
│ ├── invalid_api_key - API Key 无效 │
│ └── unauthorized - 未授权 │
│ │
│ 配额错误： │
│ ├── quota_exceeded - 配额用尽 │
│ └── character_limit_exceeded - 字符限制超出 │
│ │
│ 内容错误： │
│ ├── content_violation - 内容违规 │
│ └── text_too_long - 文本过长 │
│ │
│ 资源错误： │
│ ├── voice_not_found - 语音不存在 │
│ └── model_not_found - 模型不存在 │
│ │
└─────────────────────────────────────────────────────────────┘
速率限制 #
限制说明 #
text
┌─────────────────────────────────────────────────────────────┐
│ 速率限制 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 免费计划： │
│ ├── 3 请求/秒 │
│ └── 受限并发 │
│ │
│ Starter 计划： │
│ ├── 5 请求/秒 │
│ └── 2 并发 │
│ │
│ Creator 计划： │
│ ├── 10 请求/秒 │
│ └── 5 并发 │
│ │
│ Pro 计划： │
│ ├── 20 请求/秒 │
│ └── 10 并发 │
│ │
│ Enterprise： │
│ └── 自定义限制 │
│ │
└─────────────────────────────────────────────────────────────┘
响应头 #
text
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1712345678
SDK 使用示例 #
Python #
python
from elevenlabs import ElevenLabs, APIError, RateLimitError
client = ElevenLabs(api_key="your_api_key")
try:
audio = client.text_to_speech.convert(
text="Hello, world!",
voice_id="JBFqnCBsd6RMkjVDRZzb",
model_id="eleven_multilingual_v2"
)
with open("output.mp3", "wb") as f:
for chunk in audio:
f.write(chunk)
except RateLimitError as e:
print(f"Rate limit exceeded: {e}")
except APIError as e:
print(f"API error: {e}")
Node.js #
javascript
import { ElevenLabsClient } from "elevenlabs";
const client = new ElevenLabsClient({
apiKey: process.env.ELEVENLABS_API_KEY,
});
async function generateSpeech() {
try {
const audio = await client.textToSpeech.convert({
text: "Hello, world!",
voiceId: "JBFqnCBsd6RMkjVDRZzb",
modelId: "eleven_multilingual_v2",
});
const chunks = [];
for await (const chunk of audio) {
chunks.push(chunk);
}
return Buffer.concat(chunks);
} catch (error) {
console.error("Error:", error.message);
throw error;
}
}
下一步 #
- SDK 使用 - 详细 SDK 文档
- WebSocket 实时语音 - 实时语音通信
- 最佳实践 - 开发最佳实践
最后更新：2026-04-05