HiAPI
Блог

Руководство по использованию

Руководство по использованию ElevenLabs Text to Dialogue: отправка аудио диалога двух персонажей через массив dialogue

От разбиения сценария диалога двух персонажей до запросов тембров по репликам: отправка и приёмка по текущему контракту HiAPI

Nov 18, 2026
Плоская плетёная сетчатая обложка на тёмно-зелёном фоне: латунные и тёмно-зелёные ленты переплетаются в открытую сеть, перекликаясь с темой диалога двух людей.
На этой странице

Сначала убедитесь, что вам нужен синтез диалога, а не озвучивание одного фрагмента

Если ваш материал — это сценарий диалога двух (или более) персонажей, самый очевидный подход часто заключается в том, чтобы синтезировать каждую реплику отдельно, а затем склеить их по порядку. Проблемы этого подхода проявляются только на этапе сдачи: каждая реплика — отдельный аудиофайл, паузы между репликами, стыковку темпа речи и согласованность тембра приходится дополнительно дорабатывать на уровне склейки; чем больше персонажей, тем больше порядок склейки и несоответствие тембров становятся основным источником ошибок.

Назначение elevenlabs/text-to-dialogue — выразить весь диалог одним запросом. Вы разбиваете весь сценарий на массив 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: корень — массив, каждый элемент делится на два поля text и 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

При превышении лимита правильный подход — разбить по смысловым границам на несколько поддиалогов, отправить их отдельно, получить аудио отдельно и затем объединить по потребностям бизнеса; а не обрезать реплики или удалять строки. При разбиении обратите внимание на три момента:

  1. Точки разбиения выбирайте на смене сцены или смене темы, избегая разрыва пары «вопрос-ответ» между двумя запросами;
  2. Каждый подфрагмент считается отдельно и также не превышает 5000;
  3. При пересборке массива для каждого фрагмента после разбиения сохраняйте исходный порядок строк и сопоставление тембров персонажей.

Если контент сам по себе представляет длинный диалог, рекомендуется организовать его на стороне контента по «актам» или «главам», чтобы каждый акт естественно укладывался в бюджет и уменьшал разрывы звучания из-за временного разбиения.

Необязательные параметры: 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, чтобы ознакомиться с текущим контрактом перед началом работы.

Чек-лист самопроверки перед запуском

Если закрепить приведённый ниже набор проверок как автоматический процесс перед отправкой, это покроет подавляющее большинство причин ошибок:

  1. dialogue — массив, число элементов ≥ 1;
  2. Каждый элемент одновременно содержит text и voice, и оба не являются пустыми строками;
  3. Каждый voice входит в перечень контракта, и для одного персонажа глобально используется только одно значение;
  4. Порядок массива совпадает с порядком строк сценария, логика сортировки или дедупликации не вмешивается;
  5. Общее число символов всех text ≤ 5000, превышающий лимит контент разбит по смыслу;
  6. Если заданы явно: stability ∈ {0, 0.5, 1}, language_code ∈ перечень или пуст;
  7. Сводка входных данных (число элементов, число символов, версия сопоставления) записана для сравнения при приёмке.

Помимо чек-листа есть ещё одно эмпирическое правило: сначала прогоните сквозной сценарий на коротком образце, а затем масштабируйте на весь сценарий. Такие проблемы, как сопоставление персонажей и бюджет символов, проявляются уже на образце в несколько десятков строк, и нет необходимости ждать отправки всего контента, чтобы их обнаружить.

Похожие статьи

Все статьи →

Начните работать с постоянными артефактами ИИ

Получите API-ключ и вызывайте модели изображений, видео и аудио через один API на основе tasks.

Читать документацию API