> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/elevenlabs/elevenlabs-python/llms.txt
> Use this file to discover all available pages before exploring further.

# Dialogue

> Generate multi-voice dialogue from text and voice pairs

## 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

```python theme={null}
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

<ParamField path="inputs" type="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
</ParamField>

<ParamField path="output_format" type="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+)
</ParamField>

<ParamField path="model_id" type="str">
  The ID of the TTS model to use for generation.
</ParamField>

<ParamField path="language_code" type="str">
  Language code for the text. Auto-detected if not specified.
</ParamField>

<ParamField path="settings" type="ModelSettingsResponseModel">
  Model-specific settings for voice generation.
</ParamField>

<ParamField path="pronunciation_dictionary_locators" type="Sequence[PronunciationDictionaryVersionLocator]">
  Pronunciation dictionaries to use for custom pronunciations.
</ParamField>

<ParamField path="seed" type="int">
  Random seed for deterministic generation.
</ParamField>

<ParamField path="apply_text_normalization" type="str">
  Whether to apply text normalization. Options: "auto", "on", "off".
</ParamField>

<ParamField path="request_options" type="RequestOptions">
  Request-specific configuration.
</ParamField>

### Returns

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

### Example

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
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

```python theme={null}
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

<CardGroup cols={2}>
  <Card title="Audiobooks" icon="book">
    Create multi-character audiobooks with distinct voices for each character
  </Card>

  <Card title="Podcasts" icon="podcast">
    Generate podcast episodes with multiple hosts or guests
  </Card>

  <Card title="Training Materials" icon="graduation-cap">
    Create engaging training content with conversational formats
  </Card>

  <Card title="Interactive Stories" icon="scroll">
    Build interactive narratives with character dialogue
  </Card>
</CardGroup>

## Related Methods

* [Text to Speech](/api-reference/text-to-speech/convert) - Single voice generation
* [Voices](/api-reference/voices/search) - Browse available voices