![]()
HeyGen Avatar 6 API умеет создавать видео с ведущим из одного лишь скрипта. В режиме публичного аватара вы указываете один из 1,248 готовых образов HeyGen, отправляете до 1,000 символов text, выбираете один из 102 голосов, и heygen-avatar-6 (или heygen-avatar-6-turbo) возвращает MP4 с синхронизацией губ. Без фото, без записи, без шага синтеза речи на вашей стороне. В этом руководстве: как выбрать образ и голос из каталога, как управлять жестами через prompt, как выбрать формат кадра и сколько стоит текстовый запрос. Образы также можно посмотреть на странице модели HeyGen Avatar 6.
Запрос text to avatar
Это задокументированное тело запроса для режима публичного аватара с текстом:
{
"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"
}
}
| Поле | Обязательно | Правило |
|---|---|---|
avatar | Да | Одно из 1,248 имён образов |
text | Да (вместо audio_url) | 1–1,000 символов |
voice | Нет | Одно из 102 имён; по умолчанию Warm Pro Narrator |
prompt | Нет | До 1,200 символов режиссёрских указаний |
aspect_ratio | Нет | 16:9 (по умолчанию), 9:16, 1:1, 4:5, 5:4 |
resolution | Нет | 1080p (по умолчанию) или 2K |
Этот режим выбирается именно наличием avatar. Не отправляйте вместе с ним image_urls или video_url; в одном запросе используйте входные данные одного режима. Отправляйте на POST https://api.poyo.ai/api/generate/submit и опрашивайте /api/generate/status/{task_id}, как в руководстве по HeyGen Avatar 6 API.
Выберите образ аватара из каталога
PoYo публикует все имена на странице Avatars and Voices и в виде JSON-каталога. В каталоге пять ключей:
| Ключ | Содержимое |
|---|---|
models | heygen-avatar-6, heygen-avatar-6-turbo (одни и те же имена работают в обеих) |
default_voice | Warm Pro Narrator |
avatars | Все 1,248 имён образов, плоским списком |
avatars_by_person | Те же образы, сгруппированные по 156 людям |
voices | Все 102 имени голосов |
У каждого человека один или несколько образов, и каждый образ — отдельное значение avatar. У Abigail их пять (Abigail (Upper Body), Abigail Office Front, Abigail Office Side, Abigail Sofa Front, Abigail Sofa Side); у Annie — 54; у восьми человек по одному образу. Имена описывают обстановку, одежду и ракурс камеры, и обычно этого достаточно, чтобы выбрать без предпросмотра:
| Нужно | Ищите имена с | Примеры |
|---|---|---|
| Ведущий смотрит в камеру | Front | Abigail Office Front, Bryan Suit Front |
| Ракурс в три четверти | Side | Abigail Office Side |
| Сидя, неформально | Sofa, Sitting, Lounge | Annie Sofa Sitting Front |
| Роль или обстановка | Doctor, Nurse, Yoga, Tech Expert | Ann Doctor Standing, Adriana Nurse Front, Amelia Yoga Front, Bryan Tech Expert |
Около 480 имён содержат Front и около 430 — Side. Для серии обучающих видео выберите одного человека и придерживайтесь его образов Front, чтобы ведущий был одним и тем же во всех роликах. Соответствующий образ Side используйте для перебивок.
Имена сопоставляются без учёта регистра и лишних пробелов, поэтому abigail office front выбирает Abigail Office Front. PoYo сверяет avatar со списком при отправке, поэтому опечатка сразу даёт 400, а не неудачную задачу. Сначала проверяйте в своём коде:
import requests
catalog = requests.get(
"https://docs.poyo.ai/api-manual/video-series/heygen-avatar-6-catalog.json", timeout=30
).json()
def norm(name: str) -> str:
return " ".join(name.split()).lower()
AVATARS = {norm(a): a for a in catalog["avatars"]}
VOICES = set(catalog["voices"])
def build_request(model, avatar, text, voice=None, prompt=None, aspect_ratio="16:9", resolution="1080p"):
if norm(avatar) not in AVATARS:
raise ValueError(f"unknown avatar: {avatar!r}")
if not 1 <= len(text) <= 1000:
raise ValueError("text must be 1-1,000 characters")
if voice is not None and voice not in VOICES:
raise ValueError(f"unknown voice: {voice!r} (copy the exact name from the catalog)")
if prompt is not None and len(prompt) > 1200:
raise ValueError("prompt must be at most 1,200 characters")
body = {"avatar": AVATARS[norm(avatar)], "text": text,
"aspect_ratio": aspect_ratio, "resolution": resolution}
if voice:
body["voice"] = voice
if prompt:
body["prompt"] = prompt
return {"model": model, "input": body}
Проверка голоса намеренно использует точные имена; в следующем разделе объясняется почему.
Выберите голос
voice определяет, кто читает text. Если его не указать, будет Warm Pro Narrator. Среди 102 голосов есть обычные имена (Andrew, Ivy, Jessica Anne Bogart), описательные (Calm Chloe, Professor Dean, Radio Rick, Chill Brian) и несколько с меткой стиля в имени.
Три момента часто вызывают проблемы:
- Пробелы в конце могут иметь значение. В документации отмечено, что
HopeиHope(с пробелом в конце) — два разных голоса.Archer,Cassidy,Adam Stone,Spuds OxleyиAndrew Rizzтоже заканчиваются пробелом в каталоге. Копируйте имена из JSON, а не набирайте заново. - Некоторые имена содержат эмодзи или суффиксы, похожие на имена файлов, например
Cute Chloe - Friendly 😊илиBrenda - UGC - 1.mp4. Эти символы — часть имени. Отправляйте тело запроса как JSON в UTF-8, и имя пройдёт без изменений. - Голос не привязан к аватару. Любой из 102 голосов может читать за любой из 1,248 образов. Выберите голос, подходящий человеку в кадре; в наших тестах в день запуска мы сочетали
Bryan Tech ExpertсAndrewиAbigail Office FrontсJessica Anne Bogart.
voice применяется, только когда вы отправляете text. Если вместо этого отправить audio_url, аватар произнесёт вашу запись, а voice использоваться не будет.
Управляйте жестами через prompt
prompt принимает до 1,200 символов указаний по жестам, мимике и позе. Технический отчёт HeyGen описывает приём так: «Напишите действие рядом со словами. Avatar 6 выполнит его точно в нужный момент». Пример из отчёта: "Friendly pharmacist. On 'Hello', give a thumbs up. On 'the counter on the left', point to the side with your index finger."
Шаблон в этом формате:
{
"model": "heygen-avatar-6",
"input": {
"avatar": "Bryan Tech Expert",
"text": "Hello! Today I will show you three settings that make your dashboard faster. First, open the menu on the left.",
"voice": "Andrew",
"prompt": "Friendly product expert. On 'Hello', wave once. On 'three settings', hold up three fingers. On 'the menu on the left', point to his left side. Keep a relaxed posture and smile between sentences.",
"aspect_ratio": "16:9",
"resolution": "1080p"
}
}
Советы, которые делают промпты полезными:
- Цитируйте точные слова из
text, на которые должно приходиться каждое действие, чтобы момент был однозначным. - Сначала опишите одну роль или настроение ("Friendly product expert"), затем моменты.
- Не указывайте
prompt, если у вас нет конкретных указаний. На странице запуска Avatar 6 HeyGen сказано, что модель сама «подбирает жесты, эмоции и мимику под ваш скрипт».
Выберите соотношение сторон под площадку
aspect_ratio есть только в режиме публичного аватара; режимы фото и референсного видео сохраняют форму входных данных.
| Площадка | aspect_ratio |
|---|---|
| Сайт, YouTube, урок в LMS | 16:9 (по умолчанию) |
| Shorts, Reels, TikTok, истории | 9:16 |
| Квадратный пост в ленте, карточка в приложении | 1:1 |
| Вертикальный пост в ленте | 4:5 |
| Горизонтальный пост в ленте | 5:4 |
resolution задаётся отдельно: 1080p или 2K при любом соотношении. 2K стоит дороже за секунду, поэтому черновики рендерьте в 1080p.
Какой длины будет видео и сколько оно стоит
С текстом видео длится столько, сколько аватару нужно, чтобы его прочитать, до 1,000 символов. Вы платите за длину готового видео с округлением вверх до целых секунд. Кредиты резервируются при отправке и пересчитываются по фактическим секундам, когда задача завершается.
Наши тесты в день запуска на продакшен-API, 19 ноября 2026 года (16:9, 1080p):
| Модель | Аватар / голос | Скрипт | Результат | Стоимость по текущим ценам | Время |
|---|---|---|---|---|---|
heygen-avatar-6-turbo | Abigail Office Front / Jessica Anne Bogart | 27 слов | 10.16 s | 110 кредитов ($0.55) | Около 2.4 min |
heygen-avatar-6 | Bryan Tech Expert / Andrew | 21 слово | 6.88 s | 140 кредитов ($0.70) | Около 2 min |
В этих двух запусках это примерно 2.7 и 3.1 слова в секунду: полезно для грубой оценки бюджета, но не гарантия, поскольку темп зависит от голоса и скрипта. Тарифы за секунду: Turbo 10 кредитов ($0.05) в 1080p или 18 ($0.09) в 2K; Avatar 6 20 кредитов ($0.10) или 29 ($0.145). Подробнее — в статье Цены HeyGen Avatar 6 API.
Поскольку текстовые задачи удерживают резерв, пока выполняются, одновременная отправка многих задач может вернуть 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." Ставьте текстовые задачи в очередь или держите баланс, покрывающий текущие резервы. Пока вы итерируете, используйте Turbo; сравнение Avatar 6 vs Turbo показывает, когда переключаться.
Часто задаваемые вопросы
Может ли HeyGen Avatar 6 API превратить текст в видео с говорящим аватаром?
Да. В режиме публичного аватара отправьте avatar, до 1,000 символов text и при желании voice. Аудиофайл не нужен.
Где найти список аватаров и голосов HeyGen Avatar 6 API?
На странице документации PoYo Avatars and Voices, а также в скачиваемом JSON-каталоге с ключами avatars, avatars_by_person и voices.
Какой голос по умолчанию в HeyGen Avatar 6 API?
Warm Pro Narrator; он используется, если voice не указан.
Можно ли использовать своё фото с текстом вместо готового аватара?
Нет. text работает только в режиме публичного аватара. Для своего фото используйте режим фото с image_urls и audio_url; при необходимости сначала сгенерируйте аудио TTS-моделью.
Какие соотношения сторон поддерживает text to avatar в HeyGen Avatar 6?
16:9, 9:16, 1:1, 4:5 и 5:4, в 1080p или 2K.
Как тарифицируется текстовый запрос в HeyGen Avatar 6 API?
По длине готового видео, округлённой вверх до целых секунд, по посекундному тарифу модели. Кредиты резервируются при отправке и пересчитываются, когда задача завершается.