Введение
Назначьте исходным файлам роли через <Picture 1>, <Video 1> и <Audio 1>, соблюдая общий лимит 12 файлов. Выберите 16:9 или 9:16. Внимательно проверяйте внешность, если видеореференс сильно задаёт движение и обстановку.
| Характеристика | Значение |
|---|---|
| Ввод | Текст |
| Вывод | Видео |
| Разработчик и модель | HeyGen — HeyGen Video 1.0; имя API heygen-video-1 |
| Публичные имена интерфейсов | heygen/video-1/text-to-video; heygen/video-1/image-to-video; heygen/video-1/reference-to-video |
| Запрашиваемая длительность | 5–15 секунд во всех трёх интерфейсах |
| Ступени генерации по тексту | 480p или 768p; результат со стереозвуком AAC |
| Ступени анимации фото | 480p, 768p, 1080p, 2k — нативные разрешения |
| Замеренные размеры анимации | 832×480 при 480p; 1890×1080 при 1080p; 2688×1536 при 2k |
| Настройки результата по референсам | 480p или 768p; соотношение сторон 16:9 или 9:16 |
| Бюджет входных референсов | До 12 файлов вместе; референсные видео суммарно до 15 секунд |
| Режимы переработки описания | disabled, turbo, quality |
| Измеренная длина файлов | Запросы на пять секунд дали 5,18–5,26 секунды; оплачены пять заказанных секунд |
| Основа оплаты | Заказанные секунды результата; секунды видеореференсов тоже учитываются, а каждое изображение начиная с третьего оплачивается отдельно |
Ключевые возможности и особенности
Письменная сцена становится роликом
Text-to-video создаёт сцену на 5–15 секунд в 480p или 768p со звуковой дорожкой. Наш пятисекундный запуск 480p дал 832×480 при 24 кадрах/с со стереозвуком AAC примерно за 10 секунд обработки. Это описание одного запуска, без обещания срока.
Сохраните человека с исходного фото
Image-to-video использует image_url и описание движения для анимации вашей фотографии. Тесты 480p, 1080p и 2k сохранили человека и композицию; вариант 2k дал 2688×1536 пикселей. Выбирайте такой вход, когда важна преемственность с конкретным снимком.
Задайте человека и предмет отдельно
Reference-to-video объединяет изображения, видео и аудио в пределах 12 файлов. Тест портрета и флакона дал вертикальный кадр, где мужчина держит заданный флакон. Другой, смешанный запуск близко повторил видео и потерял лицо с фото. Назначайте каждому входу ясную задачу.
Меняйте описание с сохранением настроек
Параметры seed и prompt_optimization_mode помогают упорядочить правки. Фиксируйте seed при сравнении одного изменения, учитывая, что идентичность результата не гарантирована. Выберите disabled для сохранения текста или turbo и quality, если хотите разрешить модели переработать задание.
Параметры запроса
| Параметр | Обязательно | Описание |
|---|---|---|
prompt | Да | Назовите каждый референс его меткой и укажите роль. Для пары портрета и товара напишите, что человек из <Picture 1> держит предмет из <Picture 2>. Не менее 1 символов · Не более 32000 символов |
reference_image_urls | Нет | Используйте изображения для человека, предмета или обстановки, которые должны попасть в сцену. Не менее 1 элементов · Не более 9 элементов |
reference_video_urls | Нет | Суммарная длина видеореференсов — до 15 секунд, каждый ролик входит в общий лимит 12 файлов. Их секунды также оплачиваются, а доминирующее видео может вытеснить лицо с изображения. Не менее 1 элементов · Не более 3 элементов |
reference_audio_urls | Нет | Укажите роль звука метками вроде <Audio 1> и передавайте записи, на которые имеете права. Аудиофайлы входят в общий лимит 12 референсов. Не менее 1 элементов · Не более 3 элементов |
aspect_ratio | Нет | Выберите 16:9 для горизонтального плана или 9:16 для вертикального. В предоставленном тесте мужчины с флаконом использован 9:16 и учтены оба изображения. |
resolution | Нет | Генерация по референсам предлагает 480p или 768p. |
duration_seconds | Нет | Запросите 5–15 секунд результата отдельно от переданных исходных роликов. В расчёте суммируются секунды результата и видеореференсов. |
prompt_optimization_mode | Нет | disabled исключает переработку описания; turbo и quality её разрешают. Сохраняйте режим, проверяя влияние каждого референса на сцену. |
seed | Нет | Не меняйте seed при добавлении или удалении референса для сравнения. Одинаковый seed не обещает идентичного ролика и не гарантирует сохранения конкретного лица. |
Стоимость
Оплата за запрошенные секунды результата и секунды видеореференсов по ставке на странице. Два начальных изображения включены, каждое начиная с третьего оплачивается дополнительно.
| Спецификация | Стоимость |
|---|---|
| $0.102 / секунду |
| $0.144 / секунду |
Сценарии использования
Сцена до начала съёмок
Отправьте описание гончара примерно тридцати лет в брезентовом фартуке, который поворачивается к полке в залитой солнцем мастерской. Запрос на пять секунд в 480p даст концептуальный ролик со звуком для обсуждения до съёмки.
Портрет с небольшим жестом
Возьмите разрешённый портрет женщины примерно тридцати лет в вечернем платье у окна и задайте поворот головы с медленным движением камеры. Image-to-video создаст короткую анимацию по фото; сравните внешность и композицию с исходником.
Ведущий с вашим товаром
Прикрепите мужской портрет как <Picture 1>, а фото флакона с пипеткой как <Picture 2>. Запросите план 9:16, где мужчина держит флакон. Наш тест с двумя изображениями использовал оба референса и обрабатывался около 158 секунд.
Концепция с опорой на движение
Передайте портрет, четырёхсекундный ролик движения и аудиореференс, указав их роли в описании. Наш смешанный запуск близко повторил движение и сцену видео, но не сохранил лицо с портрета. Этот подход подходит, когда движение важнее конкретного лица.
Крупный результат на основе фото
Добавьте к исходному фото сдержанное описание движения и выберите 1080p или 2k для image-to-video. Наши пятисекундные тесты дали нативные 1890×1080 и 2688×1536, сохранив человека с исходника.
Руководство по промптам и практические советы
Соотнесите интерфейс с материалами
Выберите text-to-video для описанной сцены, image-to-video для фотографии или reference-to-video для нескольких исходных материалов. Если нужны 1080p и 2k, они доступны в анимации фото.
Подготовьте цельное описание сцены
Опишите человека, одежду, обстановку, освещение и одно видимое действие. При референсах свяжите действие с метками вроде <Picture 1> и <Picture 2>. Используйте тексты, голоса и изображения людей, на которые у вас есть права.
Создайте задачу генерации
Выполните POST на https://api.spicyapi.ai/api/v1/jobs/createTask с Bearer-авторизацией и JSON, например {"model":"heygen/video-1/text-to-video","input":{"prompt":"A potter in their thirties turns toward a shelf.","
duration_seconds":5,"resolution":"480p"}}.Получите и оцените ролик
Сохраните data.taskId и запрашивайте GET /api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID для проверки результата. Просмотрите видео, затем фиксируйте seed при сравнении одного изменения. Повтор настроек не обещает идентичного результата.
HeyGen Video 1.0 API: сцена из референсов
HeyGen Video 1.0 объединяет ваши изображения, видео и аудиореференсы в сцену на 5–15 секунд в 480p или 768p. Интерфейс принимает до 12 файлов в сумме и поддерживает 16:9 либо 9:16. Общая длина референсных роликов ограничена 15 секундами.
Вызов с человеком и товаром
Укажите heygen/video-1/reference-to-video в POST на https://api.spicyapi.ai/api/v1/jobs/createTask. Добавьте Authorization: Bearer YOUR_SPICY_API_KEY и Content-Type: application/json, затем замените оба условных URL изображений материалами, которые вам разрешено использовать.
{
"model": "heygen/video-1/reference-to-video",
"input": {
"prompt": "The man in his thirties from <Picture 1>, in a pale blue shirt, holds the dropper bottle from <Picture 2> beside his face in a softly lit bathroom. Vertical framing, static camera, warm light, composed mood.",
"reference_image_urls": [
"https://example.com/person.jpg",
"https://example.com/bottle.jpg"
],
"duration_seconds": 5,
"resolution": "480p",
"aspect_ratio": "9:16",
"prompt_optimization_mode": "disabled",
"seed": 21
}
}
Предлагаемый запрос демонстрирует метки и не повторяет исходный тестовый запрос. Используйте разрешённые тексты, голоса и изображения людей; не имитируйте личность реального человека.
Прочитайте результат генерации
Получите data.taskId после отправки и запрашивайте задачу через GET /api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID. Сокращённые JSON ниже иллюстрируют очередь и успешный результат; идентификаторы и ссылки на файлы условные.
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_references_example",
"state": "queued"
}
}
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_references_example",
"state": "succeeded",
"output": {
"assets": [{"url": "https://example.com/reference-scene.mp4"}]
}
}
}
Подробности интеграции приведены в полном формате задач. Проверьте вклад каждого референса в результат: успешное состояние само по себе не означает одинакового сохранения всех входов.
Назначьте каждому референсу роль
Назовите каждый вход соответствующей меткой и укажите его вклад в план. Документация HeyGen поясняет, что нумерация идёт независимо внутри каждого списка медиа: изображение — <Picture 1>, видео — <Video 1>, аудио — <Audio 1>.
| Параметр | Использование и ограничение |
|---|---|
prompt | Опишите новую сцену и ссылайтесь на переданные материалы метками. |
reference_image_urls | Изображения людей, товаров или обстановки; каждое начиная с третьего оплачивается дополнительно. |
reference_video_urls | Референсы движения или сцены суммарно до 15 секунд; их секунды тоже оплачиваются. |
reference_audio_urls | Записи с ролью, указанной метками вроде <Audio 1>. |
| Все списки вместе | До 12 референсов всех трёх типов медиа. |
duration_seconds | Запрошенная длина результата 5–15 секунд. |
resolution | 480p или 768p. |
aspect_ratio | 16:9 или 9:16. |
prompt_optimization_mode | disabled, turbo или quality; два последних режима могут переписать задание. |
seed | Зафиксируйте для сравнения одной правки без обещания идентичного рендера. |
Учтите два теста референсов
Тест с двумя изображениями использовал мужчину и флакон с пипеткой в результате 9:16, показав мужчину с этим флаконом. Обработка заняла около 158 секунд. Это замер отдельного запуска, без целевого срока сервиса генерации по референсам.
Смешанный тест близко повторил своё видео и не перенёс лицо с изображения. Входами были одно изображение, четырёхсекундное видео и аудио. Если важен человек с конкретного фото, избегайте доминирующего ролика движения. Одни изображения или image-to-video дают более сфокусированную основу для проверки.
- Начните с портрета и изображения товара, если именно они должны появиться.
- Явно назначьте им роли через
<Picture 1>и<Picture 2>. - Добавляйте видео, когда действительно нужны его движение или сцена, затем заново проверьте лицо.
- Сравнивайте изменение при неизменных seed и настройке переработки текста.
Рассчитайте оплату референсов
Генерация по референсам учитывает запрошенные секунды результата вместе с секундами видеореференсов по ставке этой страницы. Каждое изображение начиная с третьего оплачивается отдельно. Для запроса на пять секунд с четырьмя секундами видеореференса при планировании учтите обе длительности: исходное видео не заменяет запрошенное время результата.
Предоставленные пятисекундные тесты дали файлы на 5,18–5,26 секунды после округления кадров. Часть оплаты за выход остаётся равной пяти запрошенным секундам и учитывается отдельно от видеореференсов.
Найдите проблему и выберите другой интерфейс
До отправки проверьте общее число файлов, длину видео и настройки результата. Более 12 файлов, свыше 15 секунд исходных роликов, соотношение за пределами 16:9 и 9:16 или ступень выше 768p выходят за поддерживаемые на этой странице настройки. Для отклонённых и неудачных задач изучите ошибку ответа: отсутствие результата не означает автоматически проблему внешности.
Используйте анимацию изображения для конкретной фотографии или нативных 1080p и 2k. Если референсы не нужны, выберите видео по тексту. HeyGen Avatar IV предназначен для говорящих фото, а HeyGen Video Translate стоит изучить для перевода.
Быстрый старт API
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "heygen/video-1/reference-to-video",
"input": {
"aspect_ratio": "16:9",
"duration_seconds": 5,
"prompt": "A slow aerial shot drifting over a misty pine forest at sunrise",
"prompt_optimization_mode": "disabled",
"resolution": "768p",
"reference_image_urls": [
"https://example.com/reference.png"
]
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
Аутентификация, полная схема, опрос статуса и обработка ошибок описаны в справочнике API.

