![]()
Это руководство по 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 | Фото, референсное видео; или публичный аватар вместо text | 2–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 | Что делать |
|---|---|---|
| 400 | validation_error и другие | Исправьте входные данные: аудио вне диапазона 2–60 s, неизвестное имя аватара, поле из другого режима. Не повторяйте без изменений |
| 401 | authentication_error | Проверьте заголовок Authorization: Bearer |
| 402 | insufficient_credits_error | Пополните баланс или дождитесь расчёта по выполняющимся текстовым задачам (см. ниже) |
| 429 | rate_limit_error | Подождите и повторите |
| 500 / 502 / 503 | internal_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):
| Модель | 1080p | 2K |
|---|---|---|
heygen-avatar-6-turbo | 10 кредитов ($0.05) / s | 18 кредитов ($0.09) / s |
heygen-avatar-6 | 20 кредитов ($0.10) / s | 29 кредитов ($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 в своё хранилище.