how-tos

Руководство по HeyGen Avatar 6 API: первое говорящее видео на cURL и Python

Poyo.ai Team
8 min read
Share:

Руководство по HeyGen Avatar 6 API: первое говорящее видео на cURL и Python

Это руководство по HeyGen Avatar 6 API проведёт вас от API-ключа до готового говорящего видео в PoYo. Вы отправляете один JSON-запрос с ID модели heygen-avatar-6 (или heygen-avatar-6-turbo), сохраняете возвращённый ID задачи и опрашиваете статус, пока MP4 не будет готов. Все тела запросов ниже соответствуют формату из документации PoYo; на странице модели HeyGen Avatar 6 есть Playground, если хотите сначала посмотреть на входные данные.

Перед началом

  • Создайте ключ на poyo.ai/dashboard/api-key и экспортируйте его как POYO_API_KEY. Храните его на сервере.
  • Разместите каждый входной файл по публичному, напрямую скачиваемому HTTP- или HTTPS-адресу. PoYo сам загружает медиафайлы; загрузка файлов в теле запроса не поддерживается.
  • Выберите уровень. Оба ID принимают одинаковые поля. Turbo стоит 10 кредитов ($0.05) за секунду в 1080p; Avatar 6 — 20 кредитов ($0.10). См. Avatar 6 vs Turbo.

Первый запрос к HeyGen Avatar 6 API через cURL

Самому быстрому первому запросу медиафайлы вообще не нужны: публичный аватар HeyGen читает ваш текст.

curl https://api.poyo.ai/api/generate/submit \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen-avatar-6-turbo",
    "input": {
      "avatar": "Abigail Office Front",
      "text": "Hello and welcome to this demonstration of HeyGen Avatar 6.",
      "voice": "Warm Pro Narrator",
      "prompt": "Speak with calm confidence and nod slightly at the end.",
      "aspect_ratio": "16:9",
      "resolution": "1080p"
    }
  }'

Успешный ответ содержит "code": 200 и data.task_id, а status равен not_started. Это задача в очереди, а не видео. Опрашивайте её:

curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

Статусы: not_started, running, finished и failed. При finished MP4 лежит в data.files[] с file_type video, а data.credits_amount показывает, сколько списано. При failed читайте data.error_message.

Ограниченный цикл опроса на Python

В наших тестах в день запуска, 19 ноября 2026 года, короткие клипы из текста занимали примерно от 2 до 2.4 минуты от отправки до результата. Этот цикл опрашивает статус каждые 5 секунд (документация по статусу рекомендует 2–5 s), останавливается через 15 минут и никогда не отправляет запрос повторно по тайм-ауту, потому что повторная отправка — это вторая платная задача.

import os
import time
import requests

BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]


def checked(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        err = body.get("error") or {}
        raise RuntimeError(f"{body.get('code')} {err.get('type')}: {err.get('message')}")
    return body["data"]


def generate(payload, timeout_s=900):
    task = checked(session.post(BASE + "/api/generate/submit", json=payload, timeout=60))
    task_id = task["task_id"]
    print("task", task_id, flush=True)
    deadline = time.monotonic() + timeout_s
    while time.monotonic() < deadline:
        time.sleep(5)
        task = checked(session.get(BASE + "/api/generate/status/" + task_id, timeout=60))
        if task["status"] == "failed":
            raise RuntimeError(task.get("error_message") or "generation failed")
        if task["status"] == "finished":
            videos = [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "video"]
            return videos[0], task.get("credits_amount")
    raise TimeoutError("still running; poll this task again later: " + task_id)


url, credits = generate({
    "model": "heygen-avatar-6",
    "input": {
        "image_urls": ["https://example.com/presenter.png"],
        "audio_url": "https://example.com/speech.mp3",
        "prompt": "Face the camera with a warm smile and use small, natural hand gestures.",
        "resolution": "1080p",
    },
})
print(url, credits)

В продакшене вместо опроса добавьте callback_url на верхнем уровне запроса. PoYo отправляет тот же объект задачи (без обёртки code / data), когда задача finished или failed, с подписью HMAC-SHA256 в X-Webhook-Signature; правило подписи описано в документации по вебхукам.

Три режима ввода HeyGen Avatar 6 API

Переключателя режимов нет. avatar выбирает режим публичного аватара; иначе video_url выбирает режим референсного видео; иначе запрос выполняется в режиме фото. В одном запросе используйте входные данные одного режима.

Режим публичного аватара с текстом

Показан выше. avatar — один из 1,248 публичных образов, text — до 1,000 символов, voice — один из 102 голосов (по умолчанию Warm Pro Narrator). В руководстве text-to-avatar показано, как выбирать образы и голоса из каталога.

Режим публичного аватара с вашим аудио

Замените text и voice на audio_url. aspect_ratio по-прежнему действует:

{
  "model": "heygen-avatar-6",
  "input": {
    "avatar": "Abigail Sofa Front",
    "audio_url": "https://example.com/speech.mp3",
    "aspect_ratio": "9:16"
  }
}

Режим фото

Одна фотография реального человека плюс речь. Видео сохраняет соотношение сторон фото, поэтому перед отправкой обрежьте фото под нужный кадр. callback_url находится рядом с model, а не внутри input:

{
  "model": "heygen-avatar-6",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "image_urls": ["https://example.com/presenter.png"],
    "audio_url": "https://example.com/speech.mp3",
    "prompt": "Face the camera with a warm smile and use small, natural hand gestures.",
    "resolution": "1080p"
  }
}

Режим референсного видео

Для анимированных или нарисованных персонажей. video_url — клип с персонажем; image_urls опционально добавляет один кадр того же персонажа. Результат сохраняет соотношение сторон клипа:

{
  "model": "heygen-avatar-6-turbo",
  "input": {
    "video_url": "https://example.com/cartoon-character.mp4",
    "image_urls": ["https://example.com/cartoon-character.png"],
    "audio_url": "https://example.com/speech.mp3",
    "resolution": "2K"
  }
}

Правила валидации полей HeyGen Avatar 6 API

Проверяйте их в своём коде перед отправкой; это задокументированные лимиты.

ПолеРежимПравило
modelВсеheygen-avatar-6 или heygen-avatar-6-turbo
image_urlsФото (обязательно), референсное видео (опционально)Массив ровно из одного URL
video_urlРеференсное видеоНе менее 2 s, до 50 MB
avatarПубличный аватарОдно из 1,248 перечисленных имён
audio_urlФото, референсное видео; или публичный аватар вместо text2–60 s, до 15 MB
textПубличный аватар1–1,000 символов
voiceПубличный аватар с textОдно из 102 имён
promptВсеДо 1,200 символов
aspect_ratioПубличный аватар16:9, 9:16, 1:1, 4:5, 5:4
resolutionВсе1080p (по умолчанию) или 2K

Имена аватаров и голосов сопоставляются без учёта регистра и лишних пробелов, с одним задокументированным исключением: Hope и Hope (с пробелом в конце) — это два разных голоса. Схема входных данных не допускает лишних полей, поэтому не передавайте нативные опции HeyGen вроде motion_expressiveness или motion_prompt из собственного API HeyGen; в PoYo указания по движению задаются в prompt.

Ошибки, которые стоит обрабатывать

Всегда читайте code в теле ответа. Некоторые ошибки валидации возвращаются как HTTP 200 с "code": 400, поэтому проверять только HTTP-статус недостаточно.

code в телеerror.typeЧто делать
400validation_error и другиеИсправьте входные данные: аудио вне диапазона 2–60 s, неизвестное имя аватара, поле из другого режима. Не повторяйте без изменений
401authentication_errorПроверьте заголовок Authorization: Bearer
402insufficient_credits_errorПополните баланс или дождитесь расчёта по выполняющимся текстовым задачам (см. ниже)
429rate_limit_errorПодождите и повторите
500 / 502 / 503internal_error, upstream_error, service_errorПовторяйте с экспоненциальной задержкой

Длина аудио, длина референсного видео и имя аватара проверяются при отправке, поэтому такие ошибки проявляются сразу как 400, а не как неудачная задача через несколько минут.

У случая 402 есть особенность, характерная для HeyGen. В нашем тесте в день запуска, после отправки двух текстовых задач, третий запрос (Turbo, 2K, 22 слова) вернулся как HTTP 200 с code 402 в теле и типом insufficient_credits_error: "this request needs at least 252 credits, and 344 credits are already reserved by your unfinished HeyGen Avatar 6 text tasks." Текстовые задачи удерживают кредиты, пока выполняются, поэтому серия текстовых запросов может получить 402, даже если итоговые списания уложились бы в баланс. Ставьте текстовые задачи в очередь или показывайте сообщение об ошибке пользователю: в нём уже есть оба числа.

Как рассчитывается первый счёт за HeyGen Avatar 6 API

PoYo тарифицирует секунды вывода с округлением вверх до целых секунд (1 кредит = $0.005):

Модель1080p2K
heygen-avatar-6-turbo10 кредитов ($0.05) / s18 кредитов ($0.09) / s
heygen-avatar-620 кредитов ($0.10) / s29 кредитов ($0.145) / s
  • С audio_url (все режимы): списание равно длине аудио с округлением вверх и происходит при отправке. Клип длиной 12.3 секунды на Avatar 6 в 1080p — это 13 × 20 = 260 кредитов ($1.30).
  • С text: кредиты резервируются при отправке и пересчитываются по длине готового видео, когда задача завершается. В наших тестах скрипт из 27 слов на Turbo дал 10.16 s, к оплате 11 секунд, то есть 110 кредитов по текущим ценам (11 s × 10, $0.55); скрипт из 21 слова на Avatar 6 дал 6.88 s, к оплате 7 секунд, то есть 140 кредитов по текущим ценам (7 s × 20, $0.70).

data.credits_amount в завершённой задаче — это число для сверки. Больше примеров — в статье Цены HeyGen Avatar 6 API.

Часто задаваемые вопросы

Как вызвать HeyGen Avatar 6 API из Python?

Отправьте JSON методом POST на https://api.poyo.ai/api/generate/submit через requests, затем опрашивайте /api/generate/status/{task_id} с ограничением по времени, как в цикле выше. Подойдёт любой HTTP-клиент; SDK не требуется.

Есть ли у HeyGen Avatar 6 API callback?

Да. Добавьте callback_url на верхнем уровне запроса. PoYo отправит данные задачи, когда она завершится или завершится с ошибкой.

Почему мой запрос к HeyGen Avatar 6 API вернул HTTP 200, но без задачи?

Прочитайте тело ответа. code, отличный от 200, означает, что запрос не выполнен, даже при HTTP 200; причина указана в error.message.

Можно ли загрузить файл напрямую в HeyGen Avatar 6 API?

Нет. image_urls, video_url и audio_url принимают публичные HTTP- или HTTPS-адреса, которые PoYo скачивает сам.

Сколько хранятся результаты HeyGen Avatar 6 API?

Сгенерированные видео доступны 3 дня после создания. Скачайте MP4 в своё хранилище.

Share: