如何将 ElevenLabs 文本转语音 API 集成到应用中

隆重推出 Eleven v4，这是我们迄今为止最具情感表现力的模型。

探索跳至内容登录注册联系销售登录

要将文本转语音集成到你的应用中，请创建 API 密钥、安装 ElevenLabs SDK、使用指定的音色和模型将文本发送到 TTS 端点，并播放返回的音频。

本指南将用 Python 和 TypeScript 逐步讲解上述每个步骤，演示如何为你选择最佳的 TTS 集成方式，并概述常见错误的修复方法。

How to integrate TTS into your application with ElevenLabs

什么是文本转语音 API？

文本转语音 API 让开发者能够以编程方式将书面文本转换为听起来自然的音频，而无需自行托管 TTS 模型。将 TTS API 集成到应用后，开发者只需向 API 发送请求并接收返回的音频，即可轻松为应用添加语音层。

最优秀的文本转语音 API（例如 ElevenAPI提供的 API）可对最终音频的音效进行精细控制，从选择朗读文本片段的音色，到其传达的情感，均可调节。根据应用的使用场景，你还可以在批处理与流式处理选项之间进行选择，以生成音频样本。

文本转语音 API 请求的工作原理

当你调用 TTS API 时，幕后会执行几个步骤来交付你的音频。

以下是文本转语音 API 请求的工作原理：

你的应用将文本连同所选的音色和模型发送到文本转语音端点。
API 生成语音，并以你请求的输出格式（例如 MP3）返回音频。
你的应用播放音频或将其存储为文件。

另外需要注意，如果你的应用在浏览器中运行，应通过你自己的服务器发送请求，以确保 API 密钥永远不会出现在客户端代码中。

TTS API flow: app sends text, receives audio, then plays or stores it; browser requests use a server.

在开始将 TTS 集成到应用之前所需准备事项的清单

在将文本转语音集成到应用之前，你需要先确保具备以下条件：

一个 ElevenLabs 账户。你可以在几分钟内完成注册。
一个终端和一个代码编辑器。
在你使用的计算机上安装 Python 3 或 Node.js。
一种播放所接收音频的方式。

具备以上所有条件后，你就可以将 TTS 构建到你的应用中了。

Before first request: ElevenLabs account, terminal/editor, Python or Node.js, and audio playback.

如何将文本转语音集成到你的应用中

借助 ElevenAPI，将 TTS API 集成到应用中只需几分钟。如果你已经注册了账户，可以直接跳到下面的步骤。如果还没有，请记得注册以开始使用。

步骤如下：

创建 API 密钥
安装 SDK
发出你的第一个请求
运行它

Four-step guide to integrating ElevenLabs text-to-speech, with a CLI setup option.

下面我们来详细拆解这些步骤。

创建 API 密钥

从 ElevenLabs API 仪表盘获取 API 密钥。点击“Create Key”后，你将能够配置想要设置的 API 类型。对于此用例，请确保 TTS 已启用并具有“Access”权限。

复制 API 密钥，并将其作为环境变量粘贴到 .env 中（或根据应用的架构直接粘贴到应用配置中）。将其存储在 .env 文件中是保持密钥机密、同时允许脚本在运行时加载它的有效方式。

ELEVENLABS_API_KEY=<your_api_key_here>

更希望让你的编码代理来处理设置？将此内容粘贴到你的代理中：npx -y @elevenlabs/cli@latest onboard init。ElevenLabs CLI 会打开浏览器供你登录，将密钥保存到项目的 env 文件，并引导代理完成其余步骤。它需要 Node.js 才能运行 npx。详情请参阅快速入门。

安装 SDK

设置文本转语音 API 时，需要安装两个主要软件包。第一个是 ElevenLabs SDK，它将为你处理 API 调用。第二个是 dotenv，它将从你在第 1 步中配置的 .env 文件加载 API 密钥。

如果你在 CLI 中操作，请查阅我们的 TTS API 文档，你会在那里找到更具体的说明和可用的选项。

以下是针对你的 TTS API，在 Python 和 TypeScript 中安装 SDK 和 dotenv 的方法。

Python

pip install elevenlabs
pip install python-dotenv

TypeScript

npm install @elevenlabs/elevenlabs-js
npm install dotenv

发出你的第一个请求

接下来，创建客户端。客户端是一个封装 ElevenAPI 的对象。根据你使用的编程语言，创建 .py 或 .mts 文件。

有四个主要值会影响输出：

音色 ID：ElevenLabs 的音色库中有超过 17,500 种音色可供选择。选择最能代表你的应用的音色，或根据用例匹配音色。在下面的快速入门代码块中，我们使用的是“George”，其音色 ID 为“JBFqnCBsd6RMkjVDRZzb”
文本：你希望 ElevenAPI TTS 模型转换为音频文件的文本字符串。
模型 ID：你选择用于生成音频的特定模型。在下面的示例中，我们使用了 eleven_v4，但如果我们的某个文本转语音模型更符合你的用例，你也可以选择其中任何一个。例如，你可能会选择 Eleven Flash v2.5 （模型 ID 字段中为 eleven_flash_v2_5），因为它具有低延迟。
输出格式：定义你希望从 TTS API 接收的音频编码。默认情况下，它会提供 mp3，但你也可以切换到 ulaw 或 pcm 等格式。

以下是这些 TTS API 文件在 Python 和 TypeScript 中的样子。下面两个示例都使用 eleven_v4 模型。

Text-to-speech request requires a voice ID, text, model ID, and output format.

Python

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

load_dotenv()

elevenlabs = ElevenLabs(
  api_key=os.getenv("ELEVENLABS_API_KEY"),
)

audio = elevenlabs.text_to_speech.convert(
    text="The first move is what sets everything in motion.",
    voice_id="JBFqnCBsd6RMkjVDRZzb",  # "George" - browse voices at elevenlabs.io/app/voice-library
    model_id="eleven_v4",
    output_format="mp3_44100_128",
)

play(audio)

TypeScript

import { ElevenLabsClient, play } from "@elevenlabs/elevenlabs-js";
import "dotenv/config";

const elevenlabs = new ElevenLabsClient();
const audio = await elevenlabs.textToSpeech.convert(
	"JBFqnCBsd6RMkjVDRZzb", // "George" - browse voices at elevenlabs.io/app/voice-library
	{
		text: "The first move is what sets everything in motion.",
		modelId: "eleven_v4",
		outputFormat: "mp3_44100_128",
	},
);

await play(audio);

cURL

你也可以从任何能发出 HTTP 请求的语言调用该端点。这个 cURL 示例发送相同的文本并将音频保存到文件：

curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb?output_format=mp3_44100_128" --output speech.mp3 \
     -H "xi-api-key: $ELEVENLABS_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
  "text": "The first move is what sets everything in motion.",
  "model_id": "eleven_v4"
}'

运行它

现在你可以运行 TTS API 文件了。根据你使用的是 Python 还是 TypeScript，执行以下命令之一。

Python

python example.py

TypeScript

npx tsx example.mts

你应该能通过扬声器听到音频播放。使用 cURL 示例时，请务必打开 speech.mp3。

TTS 集成常见错误排查

如果首次请求失败，请对照以下潜在错误列表检查收到的状态码。

状态码

含义

处理方法

400 或 404

validation_error、invalid_request 或 not_found：请求无效，或者音色或其他资源不存在

在重试前先修正请求。错误中的 param 字段会指明无效的值。常见原因包括无效的音色 ID（invalid_voice_id，或对不存在的 ID 返回 voice_not_found）、不支持的模型或输出格式，或文本过长（text_too_long）。

401、402 或 403

authentication_error、payment_required 或 authorization_error：API key、额度或访问权限出现问题

对于 401，请检查你的 API key 和 xi-api-key 请求头。对于 402，请添加额度（insufficient_credits）。对于 403，请检查你的套餐是否包含该功能或模型（feature_not_available 或 model_access_denied）。

429

rate_limit_error：你超出了速率限制（rate_limit_exceeded）或并发限制（concurrent_limit_exceeded）

对于速率限制，请使用指数退避进行重试。对于并发限制，请等待当前请求完成后再发送新请求，或升级到并发限制更高的套餐。

500 或 503

internal_error 或 service_unavailable：ElevenLabs 一侧的问题，这种情况应该很少见

请稍候并重试。如果 500 错误持续出现，请联系支持。

如需完整的错误列表，请查看错误参考页面了解详情。

TTS API error guide maps status codes to causes and fixes.

集成文本转语音 API 的优势

为应用添加语音界面，可为用户带来新的交互方式。对某些人来说，这可能是他们使用你的应用的唯一实用方式，例如有视觉障碍的人士。

以下是将 TTS API 集成到应用中的优势：

无障碍性：语音音频提供了一种与你的应用交互的新方式，让那些难以在屏幕上阅读内容的人也能使用。
参与度：朗读和跟听功能让用户在做其他事情的同时获取内容，这正日益成为人们浏览内容的主要方式。
语音优先体验：语音回复为聊天机器人和应用内引导提供了与用户自然对话的方式。
多语言覆盖：Eleven v4 覆盖 90 多种语言，让你的集成能够服务全球受众。

尤其考虑到设置如此简单，将 TTS API 集成到你的应用中是一种强大方式，能让你的应用更具交互性和表现力。

选择合适的集成方式和模型

虽然 ElevenAPI 是为应用添加语音最快、最简单的方式之一，但你还可以根据自身需求选择其他几种方式。

Here are a few different TTS integration methods to choose from:

Route

Best for

What you need

Browser speech synthesis (Web Speech API)

Simple browser prototypes that use the voices locally

Browser code only

A Text to Speech API

Apps where you want consistent, high-quality voices and control over the output

An API key and an SDK or HTTP request

Audio Native

Integrating speech into articles or webpages, as is done for TIME.

An embed or a CMS plugin

ElevenAgents

Two-way voice conversations

An agent configured in the platform

If you opt for ElevenAPI, you’ll also need to choose which model to include in your request. Here is a quick guide to the available ElevenLabs TTS models:

Model

Best for

Languages

eleven_v4

The most expressive speech

90+

eleven_flash_v2_5

Real-time use, agents, and high-volume work

eleven_multilingual_v2

Stable, high-fidelity narration

You can also select from over 17,500 voices in our Voice Library. Simply swap out the example ID in a code snippet with the one you’d prefer.

Integration routes matched to use cases: Web Speech, TTS API, Audio Native, and ElevenAgents.

Common use cases of a Text to Speech API in an application

Once your first request works, the same call can power numerous features.

Here are some examples of using a TTS API in an application:

In-app reading: Send the text in chunks and play the audio in order. For more information, read through our API batching integration guide.
Audio chatbot replies: Pass each of your chatbot's responses through the API and stream the audio back to the user for a more interactive experience.
Phone systems: Request the ulaw_8000 output format for telephony. Follow our Twilio TTS integration guide for more information.

If you’re looking to build voice agents that hold two-way conversations, ElevenAgents is built for the job. You configure and deploy an agent in the platform instead of assembling the entire speech pipeline yourself. Explore ElevenAgents to learn more.

Build TTS API into your applications with ElevenAPI

Integrating Text to Speech comes down to four main steps: create an API key, install the SDK, make your first request, and then run it. The same call works in TypeScript, Python, or any other language that can make an HTTP request. You’re also able to choose the model and voice that fit your application.

If you’re ready to build TTS into your applications, sign up to make your first request with ElevenAPI today or learn more about the Text to Speech API.

FAQ

A TTS application is software that has a text to speech model built into it or connected via API calls. It allows text to be converted into spoken audio.

To implement TTS, create an API key, send your text via a request, and play the audio that comes back. We break down this process in more detail in both Python and TypeScript in the article above.

The fastest way to build TTS into your applications is by using a coding agent setup in the ElevenLabs quickstart pages. The CLI will sign you in, save your key, install the SDK, and even add example code to your project.

ElevenLabs has a free plan that you can use to get started with ElevenAPI. Check the pricing page for more details.

Eleven v4 supports 90+ languages. Eleven Flash v2.5 supports 32, while Multilingual v2 supports 29.

Written by

Man smiling, wearing a checkered shirt against a plain background.

Jack Limebear

Growth Marketing

View profile

Jack Limebear is on the Growth team, acting as a content writer and strategist across the blog and insights pages. Before ElevenLabs, he spent over a decade leading content strategy for organizations ranging from fast-growing SaaS startups to Fortune 500 companies. He holds a Master's degree in English Literature from the University of Cambridge.

如何将 ElevenLabs 文本转语音 API 集成到应用中

主题

标签

正文 · AI 翻译

什么是文本转语音 API？

文本转语音 API 请求的工作原理

在开始将 TTS 集成到应用之前所需准备事项的清单

如何将文本转语音集成到你的应用中

创建 API 密钥

安装 SDK

Python

TypeScript

发出你的第一个请求

Python

TypeScript

cURL

运行它

Python

TypeScript

TTS 集成常见错误排查

集成文本转语音 API 的优势

选择合适的集成方式和模型

Common use cases of a Text to Speech API in an application

Build TTS API into your applications with ElevenAPI

FAQ

Similar articles

Best text to speech SDKs for building conversational AI experiences

How to integrate text to speech with conversational AI using Python

Voice cloning API: How it works and what to look for

AI dubbing API: How to dub audio and video at scale