如何将 Text to Speech 集成到你的应用中

To integrate Text to Speech into your applications, create an API key, install the ElevenLabs SDK, send your text to the TTS endpoint with a voice and a model, and play the audio that comes back.

This guide walks through each of those steps in Python and TypeScript, demonstrates how to choose the best TTS integration route for you, and outlines fixes for common mistakes.

What is a Text to Speech API?

A Text to Speech API allows developers to convert written text into natural-sounding audio programmatically, all without the need to host their own TTS model. After integrating a TTS API into an application, developers simply need to send a request to the API and receive the audio back, adding a voice layer to applications with ease.

The best Text to Speech APIs, such as that offered by ElevenAPI, give granular control over how that final audio sounds, spanning from a choice of the voice that speaks a text segment to the emotion that it conveys. Depending on your application’s use case, you’ll also be able to select between batch and streaming processing options to create your audio samples.

How a Text to Speech API request works

When you call a TTS API, a few steps happen behind the scenes to deliver your audio.

Here is how a Text to Speech API request works:

1. Your application sends the text to the Text to Speech endpoint along with the voice and model you chose. 
2. The API generates the speech and returns audio in the output format you requested, such as MP3.
3. Your application plays the audio or stores it as a file. 

One additional note is that if your application runs in a browser, you should send the request through your own server so that your API key never appears in client-side code.

A checklist of what you need before you start integrating TTS into your applications

Before you integrate Text to Speech into your applications, you need to first make sure you have the following:

• An ElevenLabs account. You can sign up in minutes. 
• A terminal and a code editor.
• Python 3 or Node.js installed on the computer you’re working from.
• A way to play the audio you receive.

With all of these in place, you’re now ready to build TTS into your app.

How to integrate Text to Speech into your application

With ElevenAPI, integrating a TTS API into your application should only take a few minutes. If you’ve already signed up for an account, you can jump directly into the steps below. If not, remember to sign up to get started.

The steps are as follows:

1. Create an API key
2. Install the SDK
3. Make your first request
4. Run it

Let’s break those down in more detail.

Create an API key

Retrieve an API key from the ElevenLabs API dashboard. After clicking on ‘Create Key,’ you’ll be able to configure the type of API you want to set up. For this use case, make sure that TTS is enabled with 'Access.'

Copy the API key and paste it as an environment variable in .env (or directly into your app’s configuration, depending on its architecture). Storing it in your .env file is an effective way to keep your key secret while allowing your script to load it at runtime.

Prefer to let your coding agent handle setup? Paste this into your agent: npx -y @elevenlabs/cli@latest onboard init. The ElevenLabs CLI opens your browser so you can sign in, saves the key to your project's env file, and guides the agent through the remaining steps. It needs Node.js for npx. See the quickstart for details.

Install the SDK

There are two main packages that you need to install when setting up a Text to Speech API. The first of these is the ElevenLabs SDK, which will handle the API call for you. The second is dotenv, which will load your API key from the .env file that you configured in step 1.

If you’re working on the CLI, consult our TTS API documentation, where you’ll find more specific instructions and options you can use. 

Here is how to install the SDK and dotenv with both Python and TypeScript for your TTS API.

Python

TypeScript

Make your first request

Next, create the client. The client is an object that wraps ElevenAPI. Create either a .py or a .mts file, depending on the programming language you’re writing in.

There are four main values that will influence the output:

• Voice ID: ElevenLabs has over 17,500 voices in our Voice Library to choose from. Select a voice that best represents your application or match the voice to the use case. In our quickstart code blocks below, we’re using “George”, which has the voice ID “JBFqnCBsd6RMkjVDRZzb”
• Text: The text string that you want the ElevenAPI TTS model to convert into an audio file. 
• Model ID: The specific model that you choose to generate audio. In the example below, we've used eleven_v4, but you can also select any of our Text to Speech models if one of these better fits your use case. For example, you might opt for Eleven Flash v2.5 (eleven_flash_v2_5 in the model ID field) for its low latency.
• Output format: Define the audio encoding you’d like to receive back from the TTS API. By default, this will provide an mp3, but you could switch to formats like ulaw or pcm.

Here is what these TTS API files look like in Python and TypeScript. Both of the examples below use the eleven_v4 model.

Python

TypeScript

cURL

You can also call the endpoint from any language that makes HTTP requests. This cURL example sends the same text and saves the audio to a file:

Run it

Now you’re ready to run the TTS API file. Execute one of the following commands, depending on whether you’re writing in Python or TypeScript.

Python

TypeScript

You should hear the audio play through your speakers. With the cURL example, be sure to open speech.mp3 instead.

Troubleshooting common TTS integration errors

If your first request fails, check the status code you receive against this list of potential errors.

Status

Meaning

What to do

400 or 404

validation_error, invalid_request, or not_found: the request is invalid, or the voice or other resource does not exist

Fix the request before you retry. The param field in the error names the invalid value. Typical causes are an invalid voice ID (invalid_voice_id, or voice_not_found for an ID that does not exist), an unsupported model or output format, or text that is too long (text_too_long).

401, 402, or 403

authentication_error, payment_required, or authorization_error: a problem with your API key, your credits, or your access

For a 401, check your API key and the xi-api-key header. For a 402, add credits (insufficient_credits). For a 403, check that your plan includes the feature or model (feature_not_available or model_access_denied).

429

rate_limit_error: you exceeded the rate limit (rate_limit_exceeded) or the concurrency limit (concurrent_limit_exceeded)

For a rate limit, retry with exponential backoff. For a concurrency limit, wait for your current requests to finish before sending new ones, or move to a plan with a higher concurrency limit.

500 or 503

internal_error or service_unavailable: a problem on the ElevenLabs side, which should be rare

Wait a moment and retry. Contact support if a 500 persists.

For a full list of errors, check the Errors reference page for details. 

Benefits of integrating Text to Speech API

Adding a speech interface to your application brings a new surface for users to interact with. For some, that may be their only practical way to use with your application, such as individuals with visual impairments.

Here are the benefits of integrating a TTS API into your application:

• Accessibility: Spoken audio offers a new way of interacting with your application, making it available to those who cannot easily read it on a screen.
• Engagement: Read-aloud and listen-along features let users take in content while they do something else, which is increasingly a main way people browse.
• Voice-first experiences: Spoken replies give chatbots and in-app guides a natural way to talk back to users.
• Multilingual reach: Eleven v4 covers 90+ languages, allowing your integration to serve audiences around the world.

Especially considering how easy it is to set up, integrating a TTS API into your application is a powerful way of making your application more interactive and expressive.

Choosing the right integration route and model

While ElevenAPI is one of the fastest and easiest ways to add voice to an application, there are several other routes that you can choose depending on your needs.

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

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

An API key and an SDK or HTTP request

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

An embed or a CMS plugin

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

32

eleven_multilingual_v2

Stable, high-fidelity narration

29

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.

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