Превращение сценария в короткое видео с говорящим аватаром с помощью heygen-avatar-v и API hiapi

Короткие говорящие видео — обновления от основателей, демонстрации продукта, рекламные ролики в стиле UGC — обычно означают, что нужно записать живого человека, подготовить микрофон и потом ещё раз всё смонтировать. heygen-avatar-v на hiapi сжимает всё это до одного вызова API: отправляете сценарий или аудиофайл и получаете видео с аватаром, у которого губы синхронизированы с речью, есть естественные фоновые движения и дорожка субтитров — готовое к публикации в ленте коротких видео. В этой статье мы пройдём реальный рабочий процесс /v1/tasks, посмотрим на сгенерированный фрагмент, разберём ограничения, о которых стоит знать до того, как строить на этом конвейер, и приведём актуальные цены из /api/pricing hiapi. Если вам нужны приёмы стилизации на уровне промптов для самого аватара, это уже покрыто в heygen-avatar-v prompt recipes — здесь же речь о том, как подключить модель к переиспользуемому конвейеру коротких видео.

Что на самом деле выдаёт heygen-avatar-v

heygen-avatar-v — это модель видео с цифровым человеком, а не генератор «текст-в-видео» в духе Sora/Kling: она управляет предустановленным аватаром HeyGen с помощью текстового сценария или загруженного аудиофайла и возвращает видео, где рот аватара синхронизирован с речью, а также есть ненавязчивые постоянные движения (моргание, лёгкие повороты головы, покачивание плеч), поэтому он не выглядит как статичный портрет. Именно это поведение «движется, даже когда бездействует» и есть граница между годным фрагментом для коротких видео и говорящим фото, которое сразу выдаёт подделку.

Модель управляется двумя взаимно исключающими входами — вы отправляете один или другой:

• prompt — текстовый сценарий; озвучивается TTS hiapi и управляет синхронизацией губ
• audio_url — публичный URL на заранее записанную голосовую дорожку (ваша озвучка, клонированный голос, что угодно), которая управляет синхронизацией губ

Поля duration нет. Длительность фрагмента целиком зависит от того, сколько звучит сценарий или аудио — строка из 40 слов даст более короткий фрагмент, чем строка из 200 слов. Это важно для планирования затрат, об этом ниже.

Необязательные поля уточняют стиль: avatar (выбор из библиотеки предустановок HeyGen), voice (используется только с prompt, при наличии audio_url игнорируется), aspect_ratio (9:16 для Reels/TikTok/Shorts, 16:9, 1:1), resolution, background (сплошной цвет или сцена — но см. подводный камень ниже), caption (генерирует дорожку субтитров) и output_format (mp4 или webm, последний с прозрачным фоном для компоновки со своей сценой).

Реальный фрагмент: на входе сценарий, на выходе видео с аватаром и субтитрами

Ниже — фактический результат heygen-avatar-v: аватар произносит строку сценария, между фразами видны движения в покое, присутствует синхронизированная дорожка субтитров:

Обратите внимание, чего не происходит: аватар не застывает между предложениями, а субтитры следуют за речью, а не приклеены постфактум. Это сочетание — непрерывные движения плюс синхронизированные субтитры — и есть вся причина выбрать эту модель вместо озвучки статичного изображения аватара в редакторе.

Подводные камни: две проблемы, которые укусят первый конвейер

caption возвращает вложенный файл субтитров, а не жёстко вшитые субтитры. Установка caption: true возвращает помимо видео синхронизированный .srt-файл — она не впечатывает текст в кадры видео. Если вы хотите, чтобы текст субтитров был на экране (как это принято на большинстве платформ коротких видео), нужно отдельно вшить этот .srt-файл (например, ffmpeg -i clip.mp4 -vf subtitles=captions.srt output.mp4 или через штатный импорт субтитров вашей платформы). Относитесь к «субтитрам» из API как к данным, а не к отрендеренной картинке.

background работает только для иллюстративных аватаров, для реалистичных — нет. Библиотека аватаров HeyGen смешивает фотореалистичных и иллюстративных/анимационных аватаров. Параметр background успешно заменяет сцену за иллюстративным аватаром, но фотореалистичные аватары сохраняют свой исходный записанный фон, что бы вы ни передавали, — модель его не вырезает. Если ваш конвейер предполагает, что каждый аватар принимает переопределение фона, сначала протестируйте конкретный avatar ID, который собираетесь использовать, а уже потом полагайтесь на то, что он скомпонуется как вы ожидаете. Для фотореалистичных аватаров, которых вы хотите поместить на свой фон, надёжный путь — output_format: webm (прозрачный).

Стоимость: оплата за выходные секунды, а не за вызовы

Согласно актуальному /api/pricing hiapi, heygen-avatar-v тарифицируется по $0.15 за выходную секунду — единый тариф независимо от разрешения или соотношения сторон. Поскольку входного параметра длительности нет, ваша фактическая стоимость зависит от того, сколько звучит сценарий или аудио:

Длина сценария (примерно)	Длительность вывода	Стоимость
Короткая цепляющая фраза	Около 5 секунд	$0.75
Один такт короткого видео	Около 10 секунд	$1.50
Продающая реплика из нескольких предложений	Около 20 секунд	$3.00
Полноценный 30-секундный рекламный ролик	Около 30 секунд	$4.50

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

Конвейер: отправить, опрашивать, скачать до истечения срока

heygen-avatar-v работает на асинхронном эндпоинте hiapi /v1/tasks — как и все остальные модели на платформе, основанные на задачах, по схеме «сначала создать, потом опрашивать». Одна деталь, характерная для этого рабочего процесса: задача проходит через стадию archiving между handling и success, когда платформа завершает обработку видео и вложенных файлов субтитров, так что не считайте archiving терминальным состоянием в цикле опроса.

import time
import requests

API_KEY = "sk-your-hiapi-key"  # from https://www.hiapi.ai/en/dashboard/api-keys
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def create_avatar_video(script: str, avatar: str, aspect_ratio: str = "9:16") -> str:
    payload = {
        "model": "heygen-avatar-v",
        "input": {
            "prompt": script,
            "avatar": avatar,
            "aspect_ratio": aspect_ratio,
            "caption": True,
        },
    }
    resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]

def wait_for_video(task_id: str, timeout_s: int = 300, poll_every: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        status = task["status"]
        if status == "success":
            return task["output"]  # [{"url": "...mp4"}, {"url": "...srt"}] — download both, now
        if status == "failed":
            err = task.get("error", {})
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        # "handling" and "archiving" are both non-terminal — keep polling
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    task_id = create_avatar_video(
        script="Here's the thirty-second version of what we shipped this week.",
        avatar="your-avatar-id",
    )
    outputs = wait_for_video(task_id)
    print("outputs:", outputs)

Две операционные заметки, которые нельзя пропустить при масштабном использовании:

• Скачивайте сразу. Как и любой вывод задачи на hiapi, возвращённые URL содержат expireAt и не подходят для долгосрочных ссылок — как только задача успешно завершилась, заберите байты (видео и .srt) в своё хранилище.
• Не отправляйте полезную нагрузку с минимальным набором полей «чтобы проверить схему». Поскольку строго обязателен только prompt или audio_url, остальные поля молча используют значения по умолчанию, и полезная нагрузка из одного {"prompt": "test"} не вернёт 400 — она запустит реальный, оплачиваемый рендеринг. Проверяйте имена полей по документации или добивайтесь 4xx-ответа с заведомо неверным значением, а не пропуская поля на реальном эндпоинте.

FAQ

Могу ли я использовать свой голос вместо TTS hiapi? Да — передайте audio_url вместо prompt, указав публичный URL вашей записи, и аватар будет синхронизировать губы по этой дорожке, а не синтезировать речь из текста.

Опция caption впечатывает субтитры в видео? Нет. caption: true возвращает отдельный .srt-файл, синхронизированный с аудио выходного видео. Если вы хотите видеть текст субтитров на экране, впечатайте его сами как шаг постобработки.

Могу ли я управлять длительностью фрагмента? Напрямую нет — параметра duration не существует. Длительность вывода определяется длиной сценария (при использовании prompt) или длиной аудиофайла (при использовании audio_url).

Почему не появился указанный мной фон? background работает только для иллюстративных/анимационных аватаров из библиотеки HeyGen. Реалистичные, фотореалистичные аватары сохраняют свой исходный записанный фон; в этом случае используйте output_format: webm, чтобы получить прозрачный вывод и скомпоновать его самостоятельно.

Какие разрешения и соотношения сторон поддерживаются? До 4K, поддерживаются соотношения сторон 9:16, 16:9 и 1:1 — покрывают от лент вертикальных коротких видео до широкоэкранных и квадратных размещений.

Ключевые выводы

Построение конвейера коротких видео с аватаром на hiapi сводится к нескольким конкретным фактам, а не к догадкам: стоимость — $0.15 за выходную секунду (поэтому замеряйте время сценария до отправки, а не после), вывод субтитров — это вложенный .srt-файл, который нужно впечатать самостоятельно, замена фона работает только для иллюстративных аватаров, а ваш цикл опроса должен считать archiving таким же нетерминальным состоянием, как и handling. Прежде чем жёстко закладывать бюджет, посмотрите актуальные цифры на странице цен hiapi, а полный справочник полей — на странице модели. Если вы готовы начать, получите API-ключ в панели управления и начните с короткого сценария — 5 секунд вывода достаточно, чтобы убедиться, что аватар, соотношение сторон и обработка субтитров работают нормально, а потом масштабируйтесь до целых партий.