Tutorials

Text to Dialogue quickstart

Learn how to generate immersive dialogue from text.

This guide will show you how to generate immersive, natural-sounding dialogue from text using the Text to Dialogue API.

Keep the total length of all inputs[].text values at or below 2,000 characters per request for reliable generation. Split longer scripts into chunks and stitch the audio client-side.

Using the Text to Dialogue API

1

Create an API key

Create an API key in the dashboard here, which you’ll use to securely access the API.

Store the key as a managed secret and pass it to the SDKs either as a environment variable via an .env file, or directly in your app’s configuration depending on your preference.

.env
ELEVENLABS_API_KEY=<your_api_key_here>
2

Install the SDK

We’ll also use the dotenv library to load our API key from an environment variable.

pip install elevenlabs
pip install python-dotenv
3

Make the API request

Create a new file named example.py or example.mts, depending on your language of choice, and add the following code. Add audio tags inside each text value to guide that speaker’s delivery. The voice_id selects the speaker voice for the same input item.

# example.py
import os
from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs
from elevenlabs.play import play
load_dotenv()
elevenlabs = ElevenLabs(
  api_key=os.getenv("ELEVENLABS_API_KEY"),
)
audio = elevenlabs.text_to_dialogue.convert(
    inputs=[
        {
            "text": "[cheerfully] Hello, how are you?",
            "voice_id": "9BWtsMINqrJLrRacOk9x",
        },
        {
            "text": "[stuttering] I'm... I'm doing well, thank you.",
            "voice_id": "IKne3meq5aSn9XLyUdCD",
        }
    ]
)
play(audio)

Then run it:

python example.py

You should hear the dialogue audio play.

WebSocket streaming

For incremental dialogue over a long-lived connection with Eleven v3 models, follow Realtime Text to Dialogue. To compare this WebSocket with the standard TTS WebSocket, see Text to Speech vs Text to Dialogue WebSockets.

Next steps

Browse voices

Explore 10,000+ voices to assign to each dialogue speaker

Text to Speech

Generate speech from a single voice with the Text to Speech API

API reference

Explore all Text to Dialogue parameters and response formats