Skip to main content

​
Overview

The text_to_dialogue client converts a list of text and voice ID pairs into natural-sounding dialogue with multiple voices. Perfect for creating conversations, audiobooks with multiple characters, or podcasts.

​
convert()

Generate dialogue from text and voice pairs.

​
Method Signature

client.text_to_dialogue.convert(
    inputs: Sequence[DialogueInput],
    output_format: Optional[TextToDialogueConvertRequestOutputFormat] = None,
    model_id: Optional[str] = None,
    language_code: Optional[str] = None,
    settings: Optional[ModelSettingsResponseModel] = None,
    pronunciation_dictionary_locators: Optional[Sequence[PronunciationDictionaryVersionLocator]] = None,
    seed: Optional[int] = None,
    apply_text_normalization: Optional[str] = None,
    request_options: Optional[RequestOptions] = None
) -> Iterator[bytes]

​
Parameters

​
inputs
Sequence[DialogueInput]
required
A list of dialogue inputs, each containing text and a voice ID. Maximum of 10 unique voice IDs.Each DialogueInput has:
  • text (str): The text to convert to speech
  • voice_id (str): The voice ID to use for this text
​
output_format
TextToDialogueConvertRequestOutputFormat
Output format of the generated audio. Formatted as codec_sample_rate_bitrate.Examples:
  • mp3_22050_32 - MP3 with 22.05kHz sample rate at 32kbps
  • mp3_44100_192 - MP3 with 44.1kHz at 192kbps (requires Creator tier+)
  • pcm_44100 - PCM with 44.1kHz (requires Pro tier+)
  • wav_44100 - WAV with 44.1kHz (requires Pro tier+)
​
model_id
str
The ID of the TTS model to use for generation.
​
language_code
str
Language code for the text. Auto-detected if not specified.
​
settings
ModelSettingsResponseModel
Model-specific settings for voice generation.
​
pronunciation_dictionary_locators
Sequence[PronunciationDictionaryVersionLocator]
Pronunciation dictionaries to use for custom pronunciations.
​
seed
int
Random seed for deterministic generation.
​
apply_text_normalization
str
Whether to apply text normalization. Options: “auto”, “on”, “off”.
​
request_options
RequestOptions
Request-specific configuration.

​
Returns

Iterator[bytes] - Streaming audio data containing the complete dialogue.

​
Example

from elevenlabs import ElevenLabs
from elevenlabs.types import DialogueInput

client = ElevenLabs(api_key="YOUR_API_KEY")

# Create a dialogue between two characters
dialogue = [
    DialogueInput(
        text="Hello! How are you doing today?",
        voice_id="21m00Tcm4TlvDq8ikWAM"  # Rachel
    ),
    DialogueInput(
        text="I'm doing great, thanks for asking!",
        voice_id="AZnzlk1XvdvUeBnXmlld"  # Domi
    ),
    DialogueInput(
        text="That's wonderful to hear!",
        voice_id="21m00Tcm4TlvDq8ikWAM"  # Rachel
    )
]

# Generate the dialogue
audio = client.text_to_dialogue.convert(
    inputs=dialogue,
    model_id="eleven_multilingual_v2"
)

# Save to file
with open("dialogue.mp3", "wb") as f:
    for chunk in audio:
        f.write(chunk)

​
convert_with_timestamps()

Generate dialogue with timestamp information for each segment. 
audio_with_timestamps = client.text_to_dialogue.convert_with_timestamps(
    inputs=dialogue,
    model_id="eleven_multilingual_v2"
)
Returns AudioWithTimestampsAndVoiceSegmentsResponseModel containing:
  • Audio data
  • Timestamps for each voice segment
  • Voice segment information

​
stream()

Stream dialogue generation in real-time. 
audio_stream = client.text_to_dialogue.stream(
    inputs=dialogue,
    model_id="eleven_multilingual_v2"
)

# Process chunks as they arrive
for chunk in audio_stream:
    # Play or process chunk
    pass

​
Async Usage

from elevenlabs import AsyncElevenLabs
import asyncio

async def generate_dialogue():
    client = AsyncElevenLabs(api_key="YOUR_API_KEY")
    
    dialogue = [
        {"text": "Hi there!", "voice_id": "voice_1"},
        {"text": "Hello!", "voice_id": "voice_2"}
    ]
    
    audio = await client.text_to_dialogue.convert(inputs=dialogue)
    
    chunks = []
    async for chunk in audio:
        chunks.append(chunk)
    
    return b"".join(chunks)

audio_data = asyncio.run(generate_dialogue())

​
Use Cases

Audiobooks

Create multi-character audiobooks with distinct voices for each character

Podcasts

Generate podcast episodes with multiple hosts or guests

Training Materials

Create engaging training content with conversational formats

Interactive Stories

Build interactive narratives with character dialogue

Build docs developers (and LLMs) love

Get started for freeTalk to us