Text to Dialogue quickstart

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

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>

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

pip install elevenlabs
pip install python-dotenv

npm install @elevenlabs/elevenlabs-js
npm install dotenv

Install the ElevenLabs CLI. Homebrew (macOS) and Scoop (Windows) are recommended.

Homebrew (macOS)

brew install elevenlabs/tap/elevenlabs

Scoop (Windows)

scoop bucket add elevenlabs https://github.com/elevenlabs/scoop-bucket
scoop install elevenlabs

npm

npm install -g @elevenlabs/cli

curl

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/elevenlabs/cli/releases/latest/download/elevenlabs-cli-installer.sh | sh

Then authenticate — this opens your browser to authorize the CLI:

elevenlabs auth login

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.pyimport osfrom dotenv import load_dotenvfrom elevenlabs.client import ElevenLabsfrom elevenlabs.play import playload_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)

// example.mtsimport { ElevenLabsClient, play } from "@elevenlabs/elevenlabs-js";import "dotenv/config";const elevenlabs = new ElevenLabsClient();const audio = await elevenlabs.textToDialogue.convert({    inputs: [        {            text: "[cheerfully] Hello, how are you?",            voiceId: "9BWtsMINqrJLrRacOk9x",        },        {            text: "[stuttering] I'm... I'm doing well, thank you.",            voiceId: "IKne3meq5aSn9XLyUdCD",        },    ],});play(audio);

Then run it:

python example.py

npx tsx example.mts

You should hear the dialogue audio play.

Pass the dialogue inputs as a JSON array and save the audio to a file:

elevenlabs text-to-dialogue convert \
  --output dialogue.mp3 \
  --inputs '[
    { "text": "[cheerfully] Hello, how are you?", "voice_id": "9BWtsMINqrJLrRacOk9x" },
    { "text": "[stuttering] I... I am doing well, thank you.", "voice_id": "IKne3meq5aSn9XLyUdCD" }
  ]'

Open dialogue.mp3 to hear the result.

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.

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

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

Explore all Text to Dialogue parameters and response formats