Как использовать HeyGen Avatar IV API? Заставьте фото заговорить за 5 минут

TL;DR

• Что это: цифровой аватар по фото от HeyGen. Одно портретное фото плюс реплика (или аудио) — и вы получаете MP4, в котором человек с фото открывает рот и говорит. Уже доступен в HiAPI: откройте страницу модели, загрузите фото и генерируйте.
• Сколько стоит: оплата по секундам видео, $0.15 за секунду, 720p и 1080p по одной цене, 10 секунд — $1.50.
• Как вызывать API: POST https://api.hiapi.ai/v1/tasks, в model укажите heygen-avatar-iv, передайте ссылку на фото и реплику, получите taskId и опрашивайте — первый запуск займёт 5 минут.

Сначала посмотрите готовый ролик. Это 9-секундное горизонтальное объяснение, сделанное из одного поясного фото в свитере и одной английской реплики:

1080p / 16:9, 9 секунд, голос Cute Chloe - Friendly. Свитер, причёска и комната с фото сохраняются, а артикуляция, моргание и лёгкие кивки следуют за речью.

Исходный текст реплики:

Hi, I'm Lin. With one photo and a short script, I can present your product or record a lesson, with natural lip-sync and expressions.

Сгенерировать с этой репликой → текст уже заполнен, просто загрузите своё фото и генерируйте.

Кому подходит HeyGen Avatar IV?

Используйте его, когда у вас есть фото и вы хотите, чтобы «этот человек» вышел в кадр и заговорил. Типичные сценарии:

• Презентации продуктов и реклама: одно фото и смена реплик — пакет коротких видео с разными торговыми преимуществами.
• Курсы и обучение: преподаватель один раз записывает фото, а к каждому уроку пишет только текст.
• Корпоративные объявления и видео для поддержки: образ консультанта, врача или директора магазина фиксирован, а контент обновляется в любой момент.
• Иллюстрации и 3D-персонажи: достаточно чёткого лица — мультяшный персонаж тоже может заговорить.

Если вам не нужен собственный образ и вы хотите выбрать из готовых аватаров, либо нужен прозрачный фон, субтитры или 4K — выбирайте HeyGen Avatar V, цена та же.

Сначала попробуйте один раз на странице модели

Прежде чем писать код, сгенерируйте один ролик в веб-интерфейсе и посмотрите, как выглядит ваше фото:

1. Нажмите «Сгенерировать с этой репликой» выше — текст заполнится автоматически.
2. Загрузите фото одного человека анфас с ровным светом.
3. Выберите 1080p, 16:9; голос можно не выбирать, по умолчанию Warm Pro Narrator.
4. Нажмите «Сгенерировать», по завершении посмотрите превью онлайн и скачайте, если всё устраивает.

10 секунд стоят $1.50, на $10 можно сгенерировать примерно 66 секунд видео — хватит, чтобы сравнить несколько фото и голосов.

Три вещи, которые нужны перед вызовом API

1. API Key: создайте в консоли, формат sk-..., передавайте в заголовке Authorization: Bearer.
2. Публичная HTTPS-ссылка на фото: лучше всего подходит фото одного человека анфас, без перекрытия черт лица, с ровным светом и естественно закрытым ртом. API читает фото по ссылке, поэтому сначала загрузите изображение в собственное хранилище или CDN.
3. Реплика или аудио, одно из двух: если передать реплику, её озвучит выбранный голос; если передать аудио (audio_url), артикуляция будет следовать за вашей записью.

Минимальный запрос: версия на cURL

Ссылку на фото из примера можно использовать как есть — подставьте свой ключ и запускайте:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen-avatar-iv",
    "input": {
      "image_url": "https://static.hiapi.ai/blog/heygen-avatar-iv/portrait-landscape.jpg",
      "prompt": "Hi, I'\''m Lin. With one photo and a short script, I can present your product or record a lesson, with natural lip-sync and expressions.",
      "voice": "Cute Chloe - Friendly",
      "resolution": "1080p",
      "aspect_ratio": "16:9"
    }
  }'

ID задачи возвращается в data.taskId:

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Длительность передавать не нужно: при использовании реплики она определяется длиной текста и темпом речи, при использовании аудио совпадает с длиной аудио.

Получение результата

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Когда data.status станет success, найдите в data.output элемент с type равным video — его url и есть MP4:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-...",
    "status": "success",
    "model": "heygen-avatar-iv",
    "output": [
      {"type": "video", "url": "https://temp.hiapi.ai/.../...-0.mp4"}
    ]
  },
  "message": "success"
}

Полный пример на Python: создание, опрос, скачивание

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

payload = {
    "model": "heygen-avatar-iv",
    "input": {
        "image_url": "https://static.hiapi.ai/blog/heygen-avatar-iv/portrait-landscape.jpg",
        "prompt": "Hi, I'm Lin. With one photo and a short script, I can present your product or record a lesson, with natural lip-sync and expressions.",
        "voice": "Cute Chloe - Friendly",
        "resolution": "1080p",
        "aspect_ratio": "16:9",
    },
}

resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
task_id = resp.json()["data"]["taskId"]
print("task:", task_id)

while True:
    data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(8)

if data["status"] == "success":
    video_url = next(o["url"] for o in data["output"] if o["type"] == "video")
    with open("avatar-iv.mp4", "wb") as f:
        f.write(requests.get(video_url, timeout=120).content)
    print("saved avatar-iv.mp4")
else:
    print(data.get("error"))

Обзор параметров

Параметр	Обязательный	Значение по умолчанию	Описание
image_url	Да	—	Публичная HTTPS-ссылка на портретное фото, нужно чёткое лицо
prompt	Одно из двух	—	Реплика, до 5000 символов, на китайском и английском
voice	Нет	Warm Pro Narrator	102 встроенных голоса, работает только при использовании реплики
audio_url	Одно из двух	—	Аудио для управления артикуляцией, до 600 секунд
resolution	Нет	720p	720p или 1080p, одна цена
aspect_ratio	Нет	16:9	16:9, 9:16, 4:5, 5:4, 1:1, auto (наследует пропорции фото)
background	Нет	Белый	{"type": "color" или "image", "value": ...}, заполняет поля кадра
callback	Нет	—	{"url": "...", "when": "final"}, отправляет объект задачи при достижении финального статуса

Полный список голосов см. в китайской документации.

Два способа управления и работа с фоном

Управление репликой: передайте prompt и voice, подходит для пакетной смены контента. Вертикальный ролик ниже — фото само по себе 9:16, поэтому кадр заполняется полностью:

1080p / 9:16, 8 секунд, голос Andrew.

I've been using these new earbuds for a week. The noise canceling is super quiet, and the battery lasts all day. Follow me for more.

Сгенерировать с этой репликой → текст уже заполнен, загрузите своё вертикальное фото, выберите 9:16 и генерируйте.

Управление аудио: если у вас уже записана озвучка или нужно использовать свой голос, замените prompt и voice на audio_url — артикуляция и паузы будут следовать за записью.

Фон: когда пропорции выходного кадра и фото различаются, появляются поля — заполните их через background. Для сплошного цвета передайте {"type": "color", "value": "#F5EFE6"}, для изображения — {"type": "image", "value": "https://..."}. В ролике ниже горизонтальное фото преподавателя помещено в вертикальный кадр, а верх и низ заполнены изображением классной доски:

1080p / 9:16, 11 секунд, голос Professor Dean, в background использовано изображение классной доски.

Hello everyone. Today we'll explain the Pythagorean theorem in five minutes. In a right triangle, the squares of the two legs add up to the square of the hypotenuse.

Сгенерировать с этой репликой → текст уже заполнен, просто загрузите своё фото и генерируйте.

3 вещи, о которых стоит помнить перед запуском в продакшен

1. Используйте callback на сервере. Добавьте в запрос "callback": {"url": "https://yourapp.com/webhook", "when": "final"}, и по завершении задачи результат придёт автоматически — опрос не нужен.
2. Не повторяйте POST после получения taskId. Каждый POST /v1/tasks создаёт новую задачу и тарифицируется отдельно. При сетевом таймауте сначала проверьте, сохранили ли вы taskId; если да — продолжайте опрос или ждите callback.
3. Скачивайте сразу после успеха. Ссылки на результат истекают — как только получили результат, сохраните MP4 в собственное хранилище.

Как считается оплата?

$0.15 за секунду, оплата по фактической длине сгенерированного видео, разрешение на цену не влияет — сразу берите 1080p. При создании задачи средства резервируются по оценочной длительности, после завершения разница доплачивается или возвращается, а за неудачные задачи возвращается вся сумма.

Длительность видео	Стоимость
5 секунд	$0.75
10 секунд	$1.50
30 секунд	$4.50
60 секунд	$9.00

Стоимость зависит только от секунд, поэтому для экономии делайте реплики короче. 300 роликов по 10 секунд в месяц — около $450, 20 уроков по 60 секунд — около $180. Полный прайс см. на странице цен.

9-секундное видео с Линь из начала статьи стоило $1.35. Сгенерировать с той же репликой → текст уже заполнен, загрузите своё фото и посчитайте, сколько секунд будет в вашем видео.

Частые вопросы

Можно ли использовать китайскую реплику? Да. prompt поддерживает китайский и английский, до 5000 символов.

Можно ли использовать свой голос? Да. Передайте запись в audio_url, до 600 секунд, артикуляция будет следовать за вашей записью.

Какое фото даёт лучший результат? Фото одного человека анфас, без перекрытия черт лица, с ровным светом и естественно закрытым ртом. Иллюстрации и 3D-персонажи тоже подходят, если есть чёткое лицо. Профиль, маска, групповое фото или фото с очень маленьким лицом — попробуйте другое фото; за задачи с ошибкой распознавания возвращается вся сумма.

Фото горизонтальное, а нужно вертикальное видео — что делать? Установите aspect_ratio в 9:16, а поля сверху и снизу заполните через background, как в ролике с классной доской выше.

Сколько времени создаётся одно видео? Генерация асинхронная: чем длиннее реплика и выше разрешение, тем дольше ждать. Используйте callback на сервере — результат придёт автоматически по завершении.

Полезные ссылки по HeyGen Avatar IV

• Страница модели HeyGen Avatar IV: загрузите фото и генерируйте онлайн
• Документация HeyGen Avatar IV на китайском: все параметры и 102 голоса
• Страница модели HeyGen Avatar V: 497 готовых аватаров, поддержка прозрачного фона и субтитров
• Страница цен HiAPI: цены всех моделей по секундам и по изображениям

Попробуйте прямо сейчас: найдите своё фото анфас, сгенерируйте с репликой Линь →, текст уже заполнен, загрузите фото, выберите 1080p, 16:9 — видео примерно на 9 секунд обойдётся в $1.35.