ElevenLabs Python 库

这是 ElevenLabs 的官方 Python SDK。通过几行代码，ElevenLabs 就能为创作者和开发者带来最具吸引力、最丰富且栩栩如生的语音。

📖 API 与文档

请查看 HTTP API 文档。

安装

pip install elevenlabs

使用方法

主要模型

1. Eleven v3 (eleven_v3)

   • 戏剧化的表达和演绎
   • 支持 70 多种语言
   • 适用于自然的多说话人对话场景

2. Eleven Multilingual v2 (eleven_multilingual_v2)

   • 在稳定性、语言多样性和口音准确性方面表现出色
   • 支持 29 种语言
   • 推荐用于大多数使用场景

3. Eleven Flash v2.5 (eleven_flash_v2_5)

   • 超低延迟
   • 支持 32 种语言
   • 模型速度更快，每字符价格降低 50%

4. Eleven Turbo v2.5 (eleven_turbo_v2_5)

   • 在质量和延迟之间取得良好平衡
   • 非常适合对速度要求较高的开发场景
   • 支持 32 种语言

有关这些模型及其他模型的详细信息，请访问 ElevenLabs 模型文档。

from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs
from elevenlabs.play import play

load_dotenv()

elevenlabs = ElevenLabs()

audio = elevenlabs.text_to_speech.convert(
    text="第一步决定了后续的一切。",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_v3",
    output_format="mp3_44100_128",
)

play(audio)

播放

🎧 立即试听！ 想亲自体验我们的语音效果吗？请访问 ElevenLabs Voice Lab，尝试不同的语音、语言和设置。

语音列表

使用 search() 列出所有可用的语音。

from elevenlabs.client import ElevenLabs

elevenlabs = ElevenLabs(
  api_key="YOUR_API_KEY",
)

response = elevenlabs.voices.search()
print(response.voices)

关于语音输出结构的信息，请参阅 ElevenLabs 官方 API 文档中的获取语音接口。

您可以使用自定义设置构建语音对象来个性化语音风格，或者调用 elevenlabs.voices.settings.get("your-voice-id") 来获取该语音的默认设置。

克隆语音

瞬间克隆您的声音。请注意，语音克隆需要 API 密钥，详情见下文。

from elevenlabs.client import ElevenLabs
from elevenlabs.play import play

elevenlabs = ElevenLabs(
  api_key="YOUR_API_KEY",
)

voice = elevenlabs.voices.ivc.create(
    name="Alex",
    description="一位年长的美国男性嗓音，略带沙哑，非常适合新闻播报", # 可选
    files=["./sample_0.mp3", "./sample_1.mp3", "./sample_2.mp3"],
)

流式传输

实时流式传输正在生成的音频。

from elevenlabs import stream
from elevenlabs.client import ElevenLabs

elevenlabs = ElevenLabs(
  api_key="YOUR_API_KEY",
)

audio_stream = elevenlabs.text_to_speech.stream(
    text="这是一次测试",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_multilingual_v2"
)

# 选项 1：在本地播放流式音频
stream(audio_stream)

# 选项 2：手动处理音频字节
for chunk in audio_stream:
    if isinstance(chunk, bytes):
        print(chunk)

异步客户端

如果您希望异步进行 API 调用，请使用 AsyncElevenLabs。

import asyncio

from elevenlabs.client import AsyncElevenLabs

elevenlabs = AsyncElevenLabs(
  api_key="MY_API_KEY"
)

async def print_models() -> None:
    models = await elevenlabs.models.list()
    print(models)

asyncio.run(print_models())

ElevenAgents

使用 ElevenAgents 构建具有实时音频功能的交互式 AI 助手。

基本用法

from elevenlabs.client import ElevenLabs
from elevenlabs.conversational_ai.conversation import Conversation, ClientTools
from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface

elevenlabs = ElevenLabs(
  api_key="YOUR_API_KEY",
)

# 创建用于实时音频输入输出的音频接口
audio_interface = DefaultAudioInterface()

# 创建对话会话
conversation = Conversation(
    client=elevenlabs,
    agent_id="your-agent-id",
    requires_auth=True,
    audio_interface=audio_interface,
)

# 开始会话
conversation.start_session()

# 对话将在后台持续运行，直到您调用：
conversation.end_session()

自定义事件循环支持

对于涉及上下文传播、资源复用或特定事件循环管理的高级用例，ClientTools 支持自定义 asyncio 事件循环：

import asyncio
from elevenlabs.conversational_ai.conversation import ClientTools

elevenlabs = ElevenLabs(
  api_key="YOUR_API_KEY",
)

async def main():
    # 获取当前事件循环
    custom_loop = asyncio.get_running_loop()

    # 使用自定义循环创建 ClientTools，以避免“不同事件循环”错误
    client_tools = ClientTools(loop=custom_loop)

    # 注册你的工具
    async def get_weather(params):
        location = params.get("location", "Unknown")
        # 你的异步逻辑在这里
        return f"{location} 的天气：晴朗，72°F"

    client_tools.register("get_weather", get_weather, is_async=True)

    # 在对话中使用
    conversation = Conversation(
        client=elevenlabs,
        agent_id="your-agent-id",
        requires_auth=True,
        audio_interface=audio_interface,
        client_tools=client_tools
    )

asyncio.run(main())

自定义事件循环的优势：

• 上下文传播：在异步操作中保持请求范围的状态
• 资源复用：共享现有的异步资源，如 HTTP 会话或数据库连接池
• 循环管理：防止“任务被附加到不同的事件循环”的错误
• 性能：更好地控制异步任务的调度和执行

重要提示： 使用自定义循环时，你需要负责其生命周期。请勿在 ClientTools 仍在使用该循环时关闭它。

工具注册

注册 AI 代理在对话过程中可以调用的自定义工具：

client_tools = ClientTools()

# 同步工具
def calculate_sum(params):
    numbers = params.get("numbers", [])
    return sum(numbers)

# 异步工具
async def fetch_data(params):
    url = params.get("url")
    # 你的异步 HTTP 请求逻辑
    return {"data": "fetched"}

client_tools.register("calculate_sum", calculate_sum, is_async=False)
client_tools.register("fetch_data", fetch_data, is_async=True)

支持的语言

探索 所有模型与语言。

贡献

我们非常重视对本 SDK 的开源贡献，但请注意，此库是通过程序化方式生成的。直接对该库进行的任何修改都需要迁移到我们的生成代码中，否则在下一次生成发布时会被覆盖。欢迎提交 PR 作为概念验证，但我们无法直接合并这些更改。建议您先提交一个问题，与我们讨论后再行动！

另一方面，对 README 的贡献始终受到热烈欢迎！

ElevenLabs Python SDK 快速上手指南

环境准备

• 系统要求：支持 Windows、macOS 和 Linux 系统。
• Python 版本：建议使用 Python 3.8 或更高版本。
• 前置依赖：
  • 已注册 ElevenLabs 账号并获取 API Key。
  • 建议安装 python-dotenv 用于管理环境变量（可选但推荐）：

    pip install python-dotenv
    

• 网络提示：由于 ElevenLabs 服务位于海外，国内开发者可能需要配置代理或使用稳定的网络环境以确保连接顺畅。

安装步骤

使用 pip 直接安装官方 SDK：

pip install elevenlabs

提示：如果下载速度较慢，可使用国内镜像源加速安装：

pip install elevenlabs -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

以下是最简单的文本转语音（Text-to-Speech）示例，将文本转换为音频并播放。

1. 配置 API Key

   在项目根目录创建 .env 文件，填入你的 API Key：

   ELEVENLABS_API_KEY=your_api_key_here
   

2. 运行代码

   from dotenv import load_dotenv
   from elevenlabs.client import ElevenLabs
   from elevenlabs.play import play
   
   # 加载环境变量
   load_dotenv()
   
   # 初始化客户端
   elevenlabs = ElevenLabs()
   
   # 执行文本转语音
   audio = elevenlabs.text_to_speech.convert(
       text="The first move is what sets everything in motion.",
       voice_id="JBFqnCBsd6RMkjVDRZzb",
       model_id="eleven_v3",
       output_format="mp3_44100_128",
   )
   
   # 播放音频
   play(audio)
   

常用模型说明：

• eleven_v3：表现力最强，支持多说话人对话。
• eleven_multilingual_v2：稳定性高，支持 29 种语言，推荐大多数场景使用。
• eleven_flash_v2_5：超低延迟，价格更低。
• eleven_turbo_v2_5：速度与质量的平衡，适合对实时性要求高的开发场景。