Guide
ElevenLabs Text to Dialogue Guide: Submitting Two-Person Dialogue Audio with the dialogue Array
From splitting a two-person script to per-line voice requests, submitting and validating according to the current HiAPI contract
On this page
First confirm that you need dialogue synthesis, not single-segment narration
If your material is a two-person (or multi-role) dialogue script, the most straightforward approach is often to synthesize each line separately and then stitch them together in order. The problems with this approach only surface at the delivery stage: each line is an independent audio file, so pauses between lines, pacing continuity and voice consistency all have to be patched again at the stitching layer; the more characters there are, the more stitching order and voice mismatches become the main source of bugs.
elevenlabs/text-to-dialogue is positioned to express an entire dialogue in a single request. You split the whole script into a dialogue array and submit it; the model completes the multi-voice dialogue within the same generation, and the output is one complete audio track. Compared with "multiple single-segment syntheses + stitching", it folds character mapping and line order into the request body, so at validation time you only need to check one result.
So start with a decision:
- If the content is continuous narration by the same speaker, text-to-speech is enough; you do not need a
dialoguearray; - If the content is a dialogue where two or more characters alternate and you want a unified overall listening experience, use the
dialoguearray of this interface; - If the content is a dialogue but the total character count far exceeds the limit, you need to split it into segments at semantic boundaries and submit them in batches, rather than falling back to line-by-line synthesis.
Once you have determined that it belongs to the second category, the next thing to understand is the structure of the array itself.

Structure of the dialogue array: text and voice per line
In the HiAPI contract, the core input of elevenlabs/text-to-dialogue has only one required field: dialogue. It is an array with at least 1 item, and each element is one line of dialogue containing two required subfields:
text: the text of that line, a string with at least 1 character;voice: the voice used for that line, a string that can be a preset voice name or avoice_id, defaulting toEkK5I93UQWFDigLMpZcX.
Both fields are required — even if you only want to use the default voice, it is recommended to explicitly write voice so the request body is self-explanatory. A minimal two-person request looks like this:
{
"dialogue": [
{ "text": "How is progress on your side?", "voice": "EkK5I93UQWFDigLMpZcX" },
{ "text": "We can produce the first version this week.", "voice": "Z3R5wn05IrDiVCyEkUrK" },
{ "text": "Great, then I'll send you the acceptance checklist first.", "voice": "EkK5I93UQWFDigLMpZcX" }
]
}
Note that the order of the array is the order of the dialogue; the interface has no additional "speaker" field, and characters are distinguished entirely by voice. This is the point that most needs to be designed in advance during integration.

Splitting a two-person script into line-by-line entries
From script text to the dialogue array, it is recommended to follow a fixed pipeline to avoid errors when writing JSON by hand.
Step 1: Split by line and label the speaker
Organize the script into paired "speaker + line" structures, one line per entry, and do not merge the lines of two characters into the same text — in that case one element can only carry one voice, and characters cannot be distinguished after merging. Narration and stage directions in parentheses are not lines and should be removed separately, not stuffed into text.
Step 2: Clean the text
Check each entry: remove leading and trailing whitespace, normalize punctuation and line breaks, and delete empty lines. The minimum length constraint for text is 1 character, and an empty string will directly trigger a validation failure. If a line contains only interjections (such as "mm" or "right"), keep it; but if it becomes an empty string after cleaning, confirm with the content owner whether to delete that line.
Step 3: Build the character mapping and generate the array
Each speaker label maps to a unique voice, and then elements are generated in line order. The pseudocode is roughly:
speaker_voice = {
"A": "EkK5I93UQWFDigLMpZcX",
"B": "Z3R5wn05IrDiVCyEkUrK",
}
dialogue = [
{"text": line.text, "voice": speaker_voice[line.speaker]}
for line in script
]
Common pitfalls
- The same character uses different voices in two places, causing a noticeable disconnect in the listening experience;
- A missing
voicecauses the whole segment to fall back to the default voice, turning a two-person dialogue into "one person playing two roles"; - The array order is disrupted by sorting or deduplication logic, breaking the semantics of the dialogue.
After generation, print the first few elements for manual verification before moving on to the character budget stage.
Fixing the voice mapping: one voice per character
The reason voice must be "fixed" is that it determines both the timbre itself and the semantics of "who is speaking". If the same character has two different voice values in the whole dialogue, listeners will think the speaker changed; conversely, if two characters collide on the same voice, the dialogue loses distinguishability.
In practice, it is recommended to maintain a constant mapping table from characters to voices in code, rather than scattering string literals across every line:
const VOICE = {
host: "EkK5I93UQWFDigLMpZcX",
guest: "Z3R5wn05IrDiVCyEkUrK",
};
All lines take values only from this table, so moving or reordering lines in the script will not break consistency. voice supports preset voice names or voice_id; if your team already has its own voice naming system, you can convert it once at the configuration layer and unify it into values accepted by the interface when forming the request. The contract provides a voice enum; validating against the enum before submission can block low-level issues such as typos — values outside the enum are not silently treated as the default.
Another often-overlooked point is stability across segments. When the total character count exceeds the limit and the content needs to be split into multiple requests, the voice mapping table must be reused as-is; do not pick voices again in the new request, or the same character will sound different across segments.

Character budget and request splitting
The interface has one hard constraint on size: the total number of characters in all text fields in the dialogue array must not exceed 5000. Note that this is the sum of all texts in the array, not the length of a single line, and not the number of elements. Chinese, English and punctuation are usually all counted as characters; when estimating, it is better to leave margin under the broadest counting convention.
The counting logic should be written after generating the array and before sending the request:
total = sum(len(item["text"]) for item in dialogue)
assert total <= 5000
When the limit is exceeded, the correct approach is to split at semantic boundaries into multiple sub-dialogues, submit them separately and get the audio separately, then combine them as the business requires; do not truncate lines or delete sentences. Pay attention to three points when splitting:
- Choose split points at scene changes or topic transitions, avoiding splitting a question-and-answer pair across two requests;
- Count each sub-segment separately, and likewise keep each under 5000;
- When rebuilding the array for each split segment, preserve the original line order and character-voice mapping.
If the content itself is a long dialogue, it is recommended to organize it by "act" or "chapter" on the content side so that each act naturally falls within the budget, reducing the listening discontinuities caused by ad-hoc splitting.
Optional parameters: stability and language_code
In addition to dialogue, the interface provides two optional parameters, and the trade-off depends on the content type.
stability
stability is a numeric parameter that can be 0, 0.5 or 1, defaulting to 0.5. Its meaning is voice stability:
- The smaller the value, the richer and more varied the emotion, suitable for dialogues with emotional ups and downs and narrative content;
- The larger the value, the more stable and consistent the output, suitable for scenarios that require a unified listening experience, such as brand announcements and customer-service scripts;
- The default 0.5 is a compromise between the two.
Note that this is a per-request-level parameter, not a per-line setting. When characters in the same dialogue have very different emotions, either accept a compromise value or let different segments use different stability values when splitting.
language_code
language_code is an ISO-format language code, defaulting to an empty string; leaving it empty means automatic language detection. When the content language is clear and you want to avoid detection bias, specifying it explicitly is safer, for example filling in zh for Chinese content. The contract provides a complete enum of language codes; validate against it before submission to avoid passing unsupported values.
Neither parameter is required; if the content has no special requirements, omitting them and using the default behavior is perfectly fine.
Submission and validation: check against the task-based contract
This interface submits in the form of a task: you send the input, get a task result, and then validate around that result. This means two things.
First, validate the input contract yourself. Check each item before sending the request: dialogue is an array with at least 1 item; each item has both a non-empty text and voice; the total number of characters across all text fields does not exceed 5000; stability is only 0/0.5/1; language_code is in the enum or left empty. Putting these checks on the client can significantly reduce invalid submissions.
Second, do not assume behavior not declared by the contract. The interface documentation does not promise automatic retries, idempotency keys or failure compensation, so do not rely on "re-submitting the same request" as a fallback — each submission should be treated as an independent task. A robust engineering approach is:
- Before submission, record an input summary of this request (number of array entries, total character count, voice mapping version) for later comparison;
- After receiving the result, first confirm that the audio is usable, the duration is reasonable and the characters are distinguishable, then distribute it downstream;
- If a rerun is needed, go through the full input validation again instead of reusing an unverified old request body.
The focus of validation is "whether the result meets expectations", not guessing the server's internal process. On HiAPI, you can check the current contract on the elevenlabs/text-to-dialogue model page before you start.
Pre-launch self-check checklist
Make the following set of checks a fixed automated process before submission, and it will basically cover the vast majority of failure causes:
dialogueis an array with at least 1 element;- Each element contains both
textandvoice, and neither is an empty string; - Each
voiceis within the contract enum, and the same character uses only one value globally; - The array order matches the script line order, with no sorting or deduplication logic involved;
- The total number of characters across all
textfields is ≤ 5000, and over-limit content has been split semantically; - If explicitly set,
stability∈ {0, 0.5, 1} andlanguage_code∈ enum or empty; - The input summary (entry count, character count, mapping version) has been recorded for validation comparison.
Beyond the checklist, there is one more rule of thumb: first run end-to-end on a short sample, then scale up to the whole script. Problems such as character mapping and character budget can be exposed on a sample of a few dozen lines; there is no need to wait until the entire content has been submitted to discover them.
Related articles
View all articles →-
Guide
gpt-6.2-sol Getting Started Guide: Capability Boundaries, API Integration, and Token Pricing Essentials
Integration decisions and practical essentials for engineering teams
-
Guide
gpt-6.2-astra Getting Started Guide: Text Model Capability Boundaries, Integration Essentials, and Cost Control
-
Guide
Tripo H3.1 Getting Started Guide: Choosing Among Three Input Modes, Parameters, and Pricing
A practical guide for developers on 3D generation integration decisions and cost control