Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/phpaisdk/elevenlabs/llms.txt

Use this file to discover all available pages before exploring further.

The Dialogue resource renders multi-speaker conversations by assigning each line of text to a specific ElevenLabs voice ID. Each entry in the inputs array is spoken by its designated voice, and the segments are stitched into a single audio output. You can retrieve the plain audio or, when you need precise timing data, request character-level alignment and per-voice segment timestamps in a single call.

​
Basic Usage

create() accepts an array of text-and-voice pairs and returns an AudioResult. The rendered audio can be saved directly to disk. 
$dialogue = ElevenLabs::dialogue()->create([
    ['text' => '[giggling] Knock knock.', 'voice_id' => 'JBFqnCBsd6RMkjVDRZzb'],
    ['text' => '[curious] Who is there?', 'voice_id' => 'Aw4FAjKCGjjNkVhN1Xmq'],
], ['model_id' => 'eleven_v3']);

$dialogue->output->save(__DIR__.'/dialogue.mp3');
Stage directions written in square brackets — such as [giggling] or [curious] — are passed directly to ElevenLabs and influence how the voice delivers that line. ElevenLabs interprets these as expressive cues; they are not stripped or modified by the SDK.

​
Inputs array structure

Each entry in the $inputs array must be an associative array containing exactly two keys:
KeyTypeDescription
textstringThe spoken line, optionally prefixed with a stage direction in [brackets]
voice_idstringThe ElevenLabs voice ID that will speak this line

​
Options

​
model_id
string
The ElevenLabs dialogue model to use for generation. For example, eleven_v3.
​
output_format
string
default:"mp3_44100_128"
The audio encoding format for the rendered output. Sent as a query parameter. Examples: mp3_44100_128, wav_44100, pcm_16000.
​
enable_logging
bool
When set, controls whether ElevenLabs logs this request. Sent as a query parameter.
output_format and enable_logging are extracted from $options before the request body is built and sent as query parameters. All remaining keys in $options are merged into the JSON body alongside inputs.

​
Output format and MIME type

The output_format value determines both the audio encoding and the MIME type reported on AudioData::$mimeType. The SDK maps format prefixes as follows:
Format prefixMIME type
wav_audio/wav
pcm_audio/pcm
opus_audio/opus
ulaw_audio/basic
alaw_audio/a-law
(anything else, including mp3_)audio/mpeg

​
With Timestamps

withTimestamps() calls a different endpoint and returns a TimedDialogueResult that includes the rendered audio alongside character-level alignment and per-voice segment timing. 
$timed = ElevenLabs::dialogue()->withTimestamps([
    ['text' => 'Ready?', 'voice_id' => 'JBFqnCBsd6RMkjVDRZzb'],
    ['text' => 'Ready.', 'voice_id' => 'Aw4FAjKCGjjNkVhN1Xmq'],
]);

$timed->output->save(__DIR__.'/dialogue.mp3');

foreach ($timed->voiceSegments as $segment) {
    echo "{$segment->voiceId}: {$segment->start} - {$segment->end}\n";
}
withTimestamps() accepts the same $inputs array format and the same optional $options array as create().

​
Return Types

​
TimedDialogueResult

Returned by withTimestamps(). Contains the rendered audio and all available timing data.
​
output
AudioData
The rendered dialogue audio. Call $timed->output->save($path) to write it to disk, or read $timed->output->data for the raw binary string.
​
alignment
CharacterAlignment|null
Character-level timing for the entire rendered output. null if the model did not return alignment data.
​
normalizedAlignment
CharacterAlignment|null
Normalized character-level timing. Follows the same structure as alignment but with values normalized by ElevenLabs. null if not returned.
​
voiceSegments
list<VoiceSegment>
An ordered list of per-voice segments describing when each voice is speaking within the final audio track.
​
rawResponse
array
The full decoded JSON response from the ElevenLabs API for inspection or debugging.

​
VoiceSegment

Each element of TimedDialogueResult::$voiceSegments is a VoiceSegment.
​
voiceId
string
The ElevenLabs voice ID that produced this segment.
​
start
float
Start time of this segment in seconds, relative to the beginning of the combined audio output.
​
end
float
End time of this segment in seconds.
​
characterStart
int
Index of the first character (within the full concatenated transcript) that belongs to this segment.
​
characterEnd
int
Index of the last character (exclusive) that belongs to this segment.
​
dialogueInputIndex
int
Zero-based index into the original $inputs array identifying which input entry this segment corresponds to.

​
CharacterAlignment

Used by both alignment and normalizedAlignment on TimedDialogueResult.
​
characters
list<string>
Ordered list of individual characters from the rendered transcript.
​
startTimes
list<float>
Start time in seconds for each character, aligned by index with characters.
​
endTimes
list<float>
End time in seconds for each character, aligned by index with characters.
// Iterate character-level timing
foreach ($timed->alignment?->characters ?? [] as $i => $char) {
    $start = $timed->alignment->startTimes[$i];
    $end   = $timed->alignment->endTimes[$i];
    echo "'{$char}': {$start}s – {$end}s\n";
}

Build docs developers (and LLMs) love

Get started for freeTalk to us