Руководство по использованию
Руководство по использованию ElevenLabs Text to Dialogue: отправка аудио диалога двух персонажей через массив dialogue
От разбиения сценария диалога двух персонажей до запросов тембров по репликам: отправка и приёмка по текущему контракту HiAPI
На этой странице
Сначала убедитесь, что вам нужен синтез диалога, а не озвучивание одного фрагмента
Если ваш материал — это сценарий диалога двух (или более) персонажей, самый очевидный подход часто заключается в том, чтобы синтезировать каждую реплику отдельно, а затем склеить их по порядку. Проблемы этого подхода проявляются только на этапе сдачи: каждая реплика — отдельный аудиофайл, паузы между репликами, стыковку темпа речи и согласованность тембра приходится дополнительно дорабатывать на уровне склейки; чем больше персонажей, тем больше порядок склейки и несоответствие тембров становятся основным источником ошибок.
Назначение elevenlabs/text-to-dialogue — выразить весь диалог одним запросом. Вы разбиваете весь сценарий на массив dialogue и отправляете его, а модель в рамках одной генерации выполняет многоголосый диалог, выводя один цельный аудиофайл. По сравнению с «многократным синтезом отдельных фрагментов + склейкой» этот подход переносит сопоставление персонажей и порядок строк в тело запроса, и при приёмке вам нужно проверить только один результат.
Поэтому сначала примите решение:
- Если контент — это непрерывное озвучивание одним говорящим, достаточно синтеза речи из текста, массив
dialogueне нужен; - Если контент — это диалог двух и более персонажей, чередующихся между собой, и вы хотите единое общее звучание, следует использовать массив
dialogueданного интерфейса; - Если контент — диалог, но общее число символов значительно превышает лимит, нужно разбить его на смысловые сегменты и отправлять по частям, а не возвращаться к синтезу по репликам.
Убедившись, что ваш случай относится ко второй категории, далее нужно разобраться в структуре самого массива.

Структура массива dialogue: text и voice для каждой строки
В контракте HiAPI у elevenlabs/text-to-dialogue есть только одно обязательное поле ввода: dialogue. Это массив, минимум 1 элемент, каждый элемент — одна строка диалога, содержащая два обязательных подполя:
text: текст реплики этой строки, строка, минимум 1 символ;voice: тембр, используемый в этой строке, строка, можно указать имя предустановленного тембра илиvoice_id, по умолчаниюEkK5I93UQWFDigLMpZcX.
Оба поля обязательны — даже если вы хотите использовать только тембр по умолчанию, рекомендуется явно указать voice, чтобы тело запроса было самодокументируемым. Минимальная форма запроса диалога двух персонажей выглядит так:
{
"dialogue": [
{ "text": "Как у тебя продвигается?", "voice": "EkK5I93UQWFDigLMpZcX" },
{ "text": "На этой неделе будет первая версия.", "voice": "Z3R5wn05IrDiVCyEkUrK" },
{ "text": "Хорошо, тогда я сначала отправлю тебе чек-лист приёмки.", "voice": "EkK5I93UQWFDigLMpZcX" }
]
}
Обратите внимание, что порядок массива — это порядок диалога; у интерфейса нет дополнительного поля «говорящий», персонажи различаются исключительно по voice. Это тот момент, который нужно продумать заранее в первую очередь во всём процессе интеграции.

Разбиение сценария диалога двух персонажей на построчные элементы
От текста сценария к массиву dialogue рекомендуется обрабатывать по фиксированному конвейеру, чтобы избежать ошибок при ручном написании JSON.
Шаг 1: разбиение по строкам и разметка говорящих
Приведите сценарий к парной структуре «говорящий + реплика», по одной реплике на элемент; не объединяйте реплики двух персонажей в один text — тогда один элемент может нести только один voice, и после объединения различить персонажей невозможно. Повествование и сценические ремарки в скобках не являются репликами, их следует отдельно исключить и не помещать в text.
Шаг 2: очистка текста
Проверяйте по одной: удаляйте начальные и конечные пробелы, унифицируйте пунктуацию и переносы строк, удаляйте пустые строки. Минимальная длина text — 1 символ, пустая строка сразу вызовет ошибку валидации. Если в какой-то строке только междометия (например, «да», «угу»), её можно оставить; но если после очистки она становится пустой строкой, нужно согласовать с контент-отделом, удалять ли эту строку.
Шаг 3: создание сопоставления персонажей и генерация массива
Каждая метка говорящего сопоставляется с уникальным тембром, затем по порядку строк генерируются элементы. Псевдокод примерно такой:
speaker_voice = {
"A": "EkK5I93UQWFDigLMpZcX",
"B": "Z3R5wn05IrDiVCyEkUrK",
}
dialogue = [
{"text": line.text, "voice": speaker_voice[line.speaker]}
for line in script
]
Типичные ошибки
- Для одного персонажа в двух местах используются разные тембры — звучание будет заметно разорвано;
- Пропущен
voice, из-за чего весь фрагмент откатывается к тембру по умолчанию, и диалог двух персонажей превращается в «один актёр за двоих»; - Порядок массива нарушен логикой сортировки или дедупликации — семантика диалога ломается.
После генерации сначала распечатайте первые несколько элементов для ручной проверки, а затем переходите к этапу бюджета символов.
Фиксированное сопоставление тембров: один voice на одного персонажа
voice нужно «фиксировать», потому что он определяет и сам тембр, и семантику «кто говорит». Если у одного персонажа во всём диалоге встречаются два разных значения voice, слушатель решит, что говорящий сменился; и наоборот, если два персонажа совпадают по одному voice, диалог теряет различимость.
На практике рекомендуется поддерживать в коде таблицу констант сопоставления персонажей и тембров, а не разбрасывать строковые литералы в каждой реплике:
const VOICE = {
host: "EkK5I93UQWFDigLMpZcX",
guest: "Z3R5wn05IrDiVCyEkUrK",
};
Все строки берут значения только из этой таблицы, и переносы строк или переупорядочивание сценария не нарушат согласованность. voice поддерживает имя предустановленного тембра или voice_id; если у команды уже есть своя система именования тембров, можно выполнить преобразование на уровне конфигурации и привести к значению, принимаемому интерфейсом, при формировании запроса. В контракте приведён перечень тембров; проверяйте по нему перед отправкой — это позволит отсечь такие простые проблемы, как опечатки. Значения вне перечня не будут незаметно обработаны как значения по умолчанию.
Ещё один часто упускаемый момент — стабильность между фрагментами. Когда общее число символов превышает лимит и требуется разбить на несколько запросов, таблицу сопоставления тембров нужно использовать без изменений и не выбирать тембры заново в новых запросах, иначе один и тот же персонаж будет звучать по-разному в разных фрагментах.

Бюджет символов и разбиение запросов
У интерфейса есть жёсткое ограничение по объёму: общее число символов всех полей text в массиве dialogue не должно превышать 5000. Обратите внимание, что это сумма всего текста в массиве, а не длина одной строки и не число элементов. Китайские и английские символы, а также знаки препинания обычно учитываются как символы; при оценке лучше оставлять запас по самому широкому критерию.
Логику подсчёта следует выполнять после генерации массива и до отправки запроса:
total = sum(len(item["text"]) for item in dialogue)
assert total <= 5000
При превышении лимита правильный подход — разбить по смысловым границам на несколько поддиалогов, отправить их отдельно, получить аудио отдельно и затем объединить по потребностям бизнеса; а не обрезать реплики или удалять строки. При разбиении обратите внимание на три момента:
- Точки разбиения выбирайте на смене сцены или смене темы, избегая разрыва пары «вопрос-ответ» между двумя запросами;
- Каждый подфрагмент считается отдельно и также не превышает 5000;
- При пересборке массива для каждого фрагмента после разбиения сохраняйте исходный порядок строк и сопоставление тембров персонажей.
Если контент сам по себе представляет длинный диалог, рекомендуется организовать его на стороне контента по «актам» или «главам», чтобы каждый акт естественно укладывался в бюджет и уменьшал разрывы звучания из-за временного разбиения.
Необязательные параметры: stability и language_code
Помимо dialogue, интерфейс предоставляет два необязательных параметра, выбор которых зависит от типа контента.
stability
stability — числовой параметр, может принимать значения 0, 0.5, 1, по умолчанию 0.5. Его смысл — стабильность тембра:
- Чем меньше значение, тем богаче эмоции и больше вариаций, что подходит для диалогов с эмоциональными колебаниями и сюжетного контента;
- Чем больше значение, тем стабильнее и однороднее вывод, что подходит для брендовых объявлений, скриптов службы поддержки и других сценариев, требующих единого звучания;
- Значение по умолчанию 0.5 — компромисс между ними.
Обратите внимание, что это параметр уровня всего запроса, а не построчная настройка. Если в одном диалоге эмоции персонажей сильно различаются, либо примите компромиссное значение, либо при разбиении на фрагменты используйте разные stability для разных фрагментов.
language_code
language_code — код языка в формате ISO, по умолчанию пустая строка; пустое значение означает автоматическое определение языка. Когда язык контента известен и вы хотите избежать ошибок определения, явное указание надёжнее, например для китайского контента укажите zh. В контракте приведён полный перечень языковых кодов; перед отправкой следует выполнить проверку, чтобы не передать неподдерживаемое значение.
Оба параметра необязательны; если у контента нет особых требований, их можно опустить и использовать поведение по умолчанию.
Отправка и приёмка: проверка по контракту задач
Данный интерфейс принимает запросы в форме задачи: вы отправляете входные данные, получаете результат задачи и проводите приёмку по этому результату. Это означает две вещи.
Во-первых, входной контракт нужно проверять самостоятельно. Перед отправкой запроса проверьте по пунктам: dialogue — массив и содержит не менее 1 элемента; каждый элемент одновременно имеет непустые text и voice; общее число символов всех text не превышает 5000; stability принимает только 0/0.5/1; language_code входит в перечень или пуст. Размещение этих проверок на клиенте значительно сокращает недействительные отправки.
Во-вторых, не предполагайте поведение, не заявленное в контракте. В документации интерфейса нет обещаний автоматических повторов, ключей идемпотентности или компенсации ошибок, поэтому не полагайтесь на «повторную отправку того же запроса» как на страховку — каждая отправка должна рассматриваться как отдельная задача. Инженерно надёжный подход таков:
- Перед отправкой записывайте сводку входных данных запроса (число элементов массива, общее число символов, версию сопоставления тембров) для последующего сравнения;
- После получения результата сначала убедитесь, что аудио пригодно, длительность разумна, персонажи различимы, и только затем передавайте дальше по цепочке;
- При необходимости повторного запуска заново пройдите полную проверку входных данных, а не используйте непроверенное старое тело запроса.
Ключевой момент приёмки — «соответствует ли результат ожиданиям», а не предположения о внутренних процессах сервера. В HiAPI вы можете открыть страницу модели elevenlabs/text-to-dialogue, чтобы ознакомиться с текущим контрактом перед началом работы.
Чек-лист самопроверки перед запуском
Если закрепить приведённый ниже набор проверок как автоматический процесс перед отправкой, это покроет подавляющее большинство причин ошибок:
dialogue— массив, число элементов ≥ 1;- Каждый элемент одновременно содержит
textиvoice, и оба не являются пустыми строками; - Каждый
voiceвходит в перечень контракта, и для одного персонажа глобально используется только одно значение; - Порядок массива совпадает с порядком строк сценария, логика сортировки или дедупликации не вмешивается;
- Общее число символов всех
text≤ 5000, превышающий лимит контент разбит по смыслу; - Если заданы явно:
stability∈ {0, 0.5, 1},language_code∈ перечень или пуст; - Сводка входных данных (число элементов, число символов, версия сопоставления) записана для сравнения при приёмке.
Помимо чек-листа есть ещё одно эмпирическое правило: сначала прогоните сквозной сценарий на коротком образце, а затем масштабируйте на весь сценарий. Такие проблемы, как сопоставление персонажей и бюджет символов, проявляются уже на образце в несколько десятков строк, и нет необходимости ждать отправки всего контента, чтобы их обнаружить.
Похожие статьи
Все статьи →-
Руководство по использованию
Руководство по началу работы с gpt-6.2-sol: границы возможностей, интеграция через API и тарификация токенов
Ключевые моменты принятия решений и практики интеграции для инженерных команд
-
Руководство по использованию
Руководство по началу работы с gpt-6.2-astra: границы возможностей текстовой модели, ключевые моменты интеграции и контроль затрат
-
Руководство по использованию
Руководство по началу работы с Tripo H3.1: три способа ввода, параметры и как выбрать тариф
Практическое руководство для разработчиков по принятию решений и контролю затрат при интеграции генерации 3D