Как подключить API HeyGen: создайте ключ в API dashboard, сохраните его в переменной окружения HEYGEN_API_KEY, передайте заголовок X-Api-Key к базовому URL https://api.heygen.com, проверьте доступ вызовом GET /v3/users/me и отправьте первый запрос POST /v3/video-agents с полем prompt. Дальше остаётся дождаться video_url.
Ключ в API dashboard и переменная окружения
Ключ создаётся в личном кабинете HeyGen на странице API keys. В официальном Quick Start проекта (docs.heygen.com) описан порядок: ключ выпускается в API dashboard, дальше его экспортируют в терминале как переменную окружения. Там же дана готовая строка:
export HEYGEN_API_KEY="your-api-key-here"
Такой способ держит секрет вне кода и вне истории чата. Документация HeyGen отдельно предупреждает: не просите вставлять ключ в переписку с ассистентом. Если вы работаете с агентом вроде Claude Code, Codex или Cursor, правило то же — ключ живёт в окружении машины, а агент читает его оттуда.
Практический порядок:
- Откройте страницу API keys в аккаунте HeyGen.
- Создайте ключ и сохраните значение в менеджере секретов или переменной окружения.
- Пропишите переменную окружения в оболочке или в секретах CI.
- Для ротации ключа заведите новый и удалите старый, чтобы не держать два активных.
Для командной работы удобно хранить ключ в менеджере секретов и подставлять его в окружение при запуске. В коде обращайтесь к process.env.HEYGEN_API_KEY или os.environ["HEYGEN_API_KEY"] — значение не попадает в репозиторий.
Проверьте наличие переменной без вывода секрета: python -c 'import os; print(bool(os.environ.get("HEYGEN_API_KEY")))'. Ответ True означает, что этот процесс видит непустое значение. Сам ключ в логи не печатайте.
Заголовок X-Api-Key и базовый URL
Все запросы к нативному API HeyGen идут на один хост. Документация проекта указывает базовый URL https://api.heygen.com и заголовок авторизации X-Api-Key: <your-key>. Никаких query-параметров для ключа не нужно — только заголовок.
Минимальный каркас запроса на curl:
curl "https://api.heygen.com/v3/users/me" \
-H "X-Api-Key: $HEYGEN_API_KEY"
Для запросов с телом добавляется второй заголовок — Content-Type: application/json. Оба заголовка обязательны: без первого вы получите 401, без второго сервер не разберёт JSON.
| Элемент | Значение | Где задаётся |
|---|---|---|
| Базовый URL | https://api.heygen.com | В каждом запросе |
| Заголовок ключа | X-Api-Key | В заголовках запроса |
| Тип тела | application/json | Для POST и PATCH |
| Переменная окружения | HEYGEN_API_KEY | В оболочке или секретах CI |
Ключ передаётся в заголовке при каждом показанном вызове. Это значит, что любой скрипт, планировщик или CI-джоб должен получать переменную окружения тем же способом, что и интерактивная сессия.
Храните базовый URL в конфиге проекта одной константой. Если HeyGen выпустит новую версию эндпоинтов, вы поменяете путь в одном месте.
Проверочный вызов GET /v3/users/me
Перед первым платным запросом стоит убедиться, что ключ рабочий. Для этого в документации HeyGen предусмотрен вызов GET /v3/users/me. Он возвращает данные текущего пользователя и подтверждает, что заголовок X-Api-Key принят.
curl "https://api.heygen.com/v3/users/me" \
-H "X-Api-Key: $HEYGEN_API_KEY"
Успешный ответ означает три вещи: ключ существует, он активен и заголовок доходит до сервера. Если вместо данных приходит 401 Unauthorized, проверьте три точки — значение переменной, имя заголовка и наличие лишних пробелов при копировании ключа.
Порядок диагностики при 401:
- Проверьте наличие переменной окружения без вывода её значения.
- Сверьте имя заголовка:
X-Api-Key, регистр в HTTP-заголовках обычно не важен, но опечатка в имени ломает запрос. - Проверьте, что ключ не отозван на странице API keys.
- Убедитесь, что запрос уходит на
https://api.heygen.com.
Этот вызов проверяет данные пользователя и не отправляет задачу создания видео. Условия тарификации проверяйте в текущем API-аккаунте. В официальном Quick Start он прямо назван способом подтвердить, что ключ работает.
Первый POST /v3/video-agents с prompt
Основной сценарий генерации в v3 — Video Agent. Документация HeyGen описывает его так: вы отправляете текстовый prompt, агент сам пишет сценарий, подбирает аватара и голос и рендерит видео.
Минимальный запрос:
curl -X POST "https://api.heygen.com/v3/video-agents" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "A presenter explaining our product launch in 30 seconds"}'
Тот же вызов на Python:
import os
import requests
HEYGEN_API_KEY = os.environ["HEYGEN_API_KEY"]
resp = requests.post(
"https://api.heygen.com/v3/video-agents",
headers={"X-Api-Key": HEYGEN_API_KEY},
json={"prompt": "A presenter explaining our product launch in 30 seconds"},
)
resp.raise_for_status()
session_id = resp.json()["data"]["session_id"]
print("Сохраните идентификатор сессии:", session_id)
Ответ приходит в обёртке data:
{ "data": { "session_id": "sess_abc123", "status": "generating", "video_id": null } }
Разбор полей:
| Поле | Что означает | Что делать |
|---|---|---|
| session_id | Идентификатор сессии агента | Сохранить для поллинга |
| status | Текущее состояние | generating — работа идёт |
| video_id | Идентификатор видео | Появляется позже, при null ещё не готов |
Поле prompt — единственное обязательное в минимальном примере. Формулируйте его как задачу для сценариста: что за видео, кто в кадре, сколько это длится. Прогресс сессии можно смотреть в браузере по адресу https://app.heygen.com/video-agent/{session_id} — удобно для отладки формулировок.
Получение результата: поллинг и webhook
Готовое видео появляется не сразу. Документация HeyGen предлагает два пути: опрашивать статус или получить уведомление.
Поллинг идёт в два этапа. Сначала опрашивается сессия, пока в ней не появится video_id. Затем опрашивается само видео, пока статус не станет completed или failed.
import time
video_id = None
while not video_id:
sess = requests.get(
f"https://api.heygen.com/v3/video-agents/{session_id}",
headers={"X-Api-Key": HEYGEN_API_KEY},
).json()["data"]
video_id = sess.get("video_id")
if not video_id:
time.sleep(5)
while True:
video = requests.get(
f"https://api.heygen.com/v3/videos/{video_id}",
headers={"X-Api-Key": HEYGEN_API_KEY},
).json()["data"]
if video["status"] in ("completed", "failed"):
break
time.sleep(10)
if video["status"] == "failed":
raise RuntimeError(f"{video.get('failure_code')}: {video.get('failure_message')}")
print(video["video_url"])
Готовый ответ выглядит так:
{ "data": { "id": "vid_xyz789", "status": "completed", "video_url": "https://files.heygen.ai/video/vid_xyz789.mp4", "duration": 32.5 } }
Второй путь — webhook. В запрос создания добавляется callback_url, и сервис сам присылает уведомление о готовности. Этот вариант удобен для серверных сценариев, где держать цикл ожидания неудобно или дорого.
| Способ | Когда уместен | Что нужно на вашей стороне |
|---|---|---|
| Поллинг сессии и видео | Скрипты, локальные задачи, отладка | Цикл с паузой между запросами |
| callback_url / webhook | Серверная обработка, много задач | Публичный эндпоинт для приёма событий |
Интервалы в примере — 5 секунд для сессии и 10 для видео — взяты из документации HeyGen. При потоке задач увеличивайте паузы, чтобы не упираться в лимиты. Сохраните оба Python-блока в одном файле после настройки переменной окружения. Это учебный пример; реальный запрос редакция не выполняла. Ожидание можно прервать и затем проверить сохранённую сессию; повторно создавать генерацию для проверки статуса не требуется.
Типовые ошибки: 401, 429, 400 и failed
Документация HeyGen перечисляет четыре частых сбоя, и каждый лечится по-своему.
401 Unauthorized. Ключ не передан или неактивен. Проверьте заголовок X-Api-Key и статус ключа на странице API keys. Одна из возможных причин — процесс не унаследовал переменную окружения.
429 Too Many Requests. Достигнут лимит частоты или параллельных задач. Ответ содержит заголовок Retry-After — дождитесь указанного времени и повторите запрос. Документация отмечает, что корпоративные планы получают повышенные лимиты, детали — в разделе Usage Limits.
400 download_failed. Переданная ссылка не скачалась. Документация требует, чтобы URL был публично доступен и указывал прямо на файл. Ссылки за авторизацией, страницы-просмотрщики и временные адреса с истечением срока дают эту ошибку.
Статус failed. Видео не собралось. Причина лежит в полях failure_code и failure_message ответа GET /v3/videos/{video_id}. Полный каталог кодов — в разделе Error Codes документации.
Практика обработки: логируйте failure_code вместе с session_id, чтобы связать сбой с конкретным запуском. Для 429 встройте экспоненциальную паузу с учётом Retry-After. Для 400 проверяйте доступность ссылки до отправки запроса.
Прямой API, MCP/CLI и универсальные обёртки
Один и тот же API HeyGen доступен через несколько поверхностей. Выбор зависит от того, пишете вы код или работаете из агента и терминала.
| Путь | Аутентификация | Код | Когда выбирать |
|---|---|---|---|
| Прямой API | X-Api-Key, ключ HeyGen | Свой | Нужен полный контроль и нативные эндпоинты v3 |
| MCP Server | Ключ HeyGen в конфиге агента | Минимум | Работа из Claude, Cursor и других MCP-агентов |
| CLI | Ключ HeyGen в окружении | Команды оболочки | Скрипты и CI-джобы без своего HTTP-слоя |
| MindCloud | Ключ MindCloud и connectionId | Свой | Процесс уже работает в MindCloud |
| qibb | Токен HeyGen в настройках соединения | Flow | Процесс уже работает в qibb |
MCP и CLI, по описанию в документации HeyGen, оборачивают тот же API: MCP подключает сервис к агентам, CLI даёт команды вида heygen video create и heygen video download. Нативный ключ HeyGen используется в обоих случаях.
Универсальные обёртки работают иначе. В документации MindCloud подключение строится на собственном ключе платформы и идентификаторе соединения с HeyGen, а вызовы идут по шаблону URL с действием. В документации qibb описан свой порядок: получить API Token в аккаунте HeyGen, установить ноду, добавить её во flow и передать токен в настройках соединения. У каждой платформы свой контракт подключения; адреса, параметры и ключи сверяют в её собственной документации.
Миграция v1/v2 и оговорки по региону
Документация HeyGen указывает, что версии v1 и v2 поддерживаются до 31 октября 2026 года, после чего остаётся актуальной линейка v3. Дату стоит перепроверить перед выпуском в продакшен: раздел Changelog в документации обновляется.
Что это значит на практике. Новые интеграции сразу строятся на v3: ключ, заголовок X-Api-Key, эндпоинты /v3/users/me, /v3/video-agents, /v3/videos/{video_id}. Старый код на v1 или v2 продолжит работать до указанной даты, но переносить его лучше заранее — сравнение версий есть в документации проекта.
Отдельно про доступность и оплату. Источники, на которые опирается эта инструкция, описывают техническую сторону: ключи, эндпоинты, лимиты и ошибки. Условия работы сервиса в конкретном регионе и способы оплаты в них не раскрываются, поэтому проверяйте их в аккаунте HeyGen перед тем, как закладывать сервис в проект.
Частые вопросы
Где взять API-ключ HeyGen?
Ключ создаётся в API dashboard аккаунта HeyGen на странице API keys. Документация проекта описывает выпуск ключа как первый шаг быстрого старта. Скопируйте значение сразу после создания и сохраните его в переменной окружения HEYGEN_API_KEY.
Как проверить, что ключ работает?
Отправьте GET-запрос на https://api.heygen.com/v3/users/me с заголовком X-Api-Key. Успешный ответ с данными пользователя подтверждает, что ключ активен и заголовок доходит до сервера. Этот вызов не отправляет задачу создания видео.
Почему приходит 401 Unauthorized?
Причин три: переменная окружения пуста, имя заголовка написано с ошибкой или ключ отозван. Проверьте значение переменной, сверьте заголовок X-Api-Key и статус ключа на странице API keys. Проверьте, унаследовал ли процесс нужную переменную окружения.
Что делать при 429 Too Many Requests?
Ответ содержит заголовок Retry-After — дождитесь указанного интервала и повторите запрос. Дальше помогает экспоненциальная пауза между попытками. Документация отмечает, что корпоративные планы получают повышенные лимиты, детали собраны в разделе Usage Limits.
Как получить ссылку на готовое видео?
Опрашивайте сессию GET /v3/video-agents/{session_id}, пока в ответе не появится video_id. Затем опрашивайте GET /v3/videos/{video_id}, пока статус не станет completed. Поле video_url в ответе содержит прямую ссылку на MP4-файл. Альтернатива — передать callback_url и получить уведомление webhook.