Введение
Отправьте image_url и prompt с описанием желаемого движения. В тестах фото сохранились человек и композиция исходника в 480p, 1080p и 2k. Подберите нативную ступень под размеры будущего результата.
| Характеристика | Значение |
|---|---|
| Ввод | Изображение |
| Вывод | Видео |
| Разработчик и модель | 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 | Да | Укажите нужное изменение, например поворот головы или перевод взгляда, и то, что должно остаться узнаваемым. Выберите действие, которое сможете оценить за запрошенное время. Не менее 1 символов · Не более 32000 символов |
image_url | Да | Передайте исходное фото с человеком и композицией для анимации. Перед описанием движения убедитесь, что кадрирование уже подходит задуманному плану. |
resolution | Нет | Выберите 480p, 768p, 1080p или 2k со строчной k. В тестах 480p, 1080p и 2k дали соответственно 832×480, 1890×1080 и 2688×1536. |
duration_seconds | Нет | Задайте желаемую длину от 5 до 15 секунд. Единица оплаты следует запросу, даже если округление до целых кадров немного удлиняет файл. |
prompt_optimization_mode | Нет | Используйте disabled для сохранения задания без переработки либо turbo или quality для её разрешения. Сначала сравните движение при неизменном режиме, затем меняйте разрешение. |
seed | Нет | Фиксированный seed помогает оценить одно изменение в описании движения за раз. Это инструмент сравнения, без гарантии идентичности возвращаемого ролика. |
Стоимость
Оплачивается каждая запрошенная секунда результата по указанной ставке выбранного нативного разрешения. Добавочное время от округления кадров не добавляет секунд к счёту.
| Спецификация | Стоимость |
|---|---|
| $0.03 / секунду |
| $0.054 / секунду |
| $0.144 / секунду |
| $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, 1080p и 2k. В наших тестах сохранились человек и композиция исходника, поэтому этот интерфейс — практичная отправная точка, когда снимок уже задаёт план.
Отправьте фото и задайте движение
Передайте heygen/video-1/image-to-video на https://api.spicyapi.ai/api/v1/jobs/createTask с JSON ниже. Установите Authorization: Bearer YOUR_SPICY_API_KEY и Content-Type: application/json, заменив URL фото своим изображением.
{
"model": "heygen/video-1/image-to-video",
"input": {
"image_url": "https://example.com/portrait.jpg",
"prompt": "The woman in her thirties in the supplied portrait, wearing a cream blouse, turns gently toward the window. Retain the source person and composition, soft morning light, calm mood, static camera.",
"duration_seconds": 5,
"resolution": "1080p",
"prompt_optimization_mode": "disabled",
"seed": 7
}
}
Этот образец иллюстрирует возможную анимацию портрета, без дополнительного тестового результата. Используйте фотографию и изображение человека, на которые у вас есть права.
Заберите готовое видео
В ответ на отправку возвращается идентификатор задачи для получения результата через GET /api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID. Сокращённые примеры ответа показывают нужные поля с условными значениями и не описывают новый запуск.
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_photo_example",
"state": "queued"
}
}
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_photo_example",
"state": "succeeded",
"output": {
"assets": [{"url": "https://example.com/animated-portrait.mp4"}]
}
}
}
Полная структура приведена в документации задач SpicyAPI. Сохраните готовый файл и сравните человека в движении и кадрирование с входной фотографией.
Настройте анимацию
Передайте image_url вместе с описанием, затем выберите длительность и нативное разрешение. Настройки ниже отдельно задают исходную фотографию и движение, которое требуется добавить.
| Параметр | Что передать |
|---|---|
image_url | Исходный снимок, определяющий человека и композицию. |
prompt | Действие, поведение камеры, освещение и постановку сцены. |
duration_seconds | Желаемую длительность результата от 5 до 15 секунд. |
resolution | 480p, 768p, 1080p или 2k; в JSON пишите 2k со строчной k. |
prompt_optimization_mode | disabled исключает переработку; turbo и quality её разрешают. |
seed | Настройку сравнения правок без обещания одинакового результата. |
Сохраните основу фотографии
Опишите небольшое изменение исходной позы, не перестраивая всю сцену словами. Поворот головы или перевод взгляда дают понятное действие для оценки при сравнении человека и кадрирования со снимком.
По данным HeyGen, image-to-video начинается с переданного изображения. Руководство по описаниям рекомендует сдержанное движение камеры и точные точки контакта для жестов. Это сведения разработчика; наши данные здесь — сохранение фотографии и нативные размеры, зафиксированные в предоставленных тестах.
- Выберите фото с человеком и обстановкой, которые нужно сохранить.
- Задайте одно движение и укажите важные визуальные элементы.
- В пробе 480p проверьте внешность и действие.
- Когда направление сцены устроит вас, попробуйте 1080p или 2k с прежним seed для сравнения.
Сравните измеренные размеры
Пятисекундные тесты фотографий дали нативные результаты запрошенных ступеней, сохранив человека с исходника. Замеры относятся к испытанной композиции и не задают универсальное соответствие пикселей для всех снимков.
| Запрошенная ступень | Измеренный результат |
|---|---|
480p | 832×480 |
1080p | 1890×1080 |
2k | 2688×1536 |
768p тоже поддерживается, но размеров теста изображений для этой ступени у нас нет. Отдельный замер времени обработки изображений также отсутствует: около 10 секунд текстового запуска нельзя считать оценкой времени этого интерфейса.
Спланируйте оплату и проверьте длину
Анимация изображений оплачивается за запрошенные секунды результата по ставке выбранной ступени на странице. Пятисекундные файлы в наших тестах длились 5,18–5,26 секунды из-за округления до целых кадров; оплачиваемая длительность выхода оставалась пять секунд. Большее число пикселей решает задачу размеров публикации; движение проверьте отдельно перед следующим рендером.
Проверьте вход и рассмотрите альтернативы
Если запрос отклонён, проверьте image_url, описание и написание разрешения. Длительность должна оставаться в пределах 5–15 секунд; для соответствующей ступени используйте 2k. До изменения полей сверьтесь с текущей схемой и ошибкой задачи. Даже при успешной задаче результат с изменившимся важным жестом требует просмотра.
Для сцены по словам без исходного фото выберите генерацию по тексту. Чтобы дать портрету и товару отдельные роли, используйте генерацию по референсам, учитывая возможное доминирование видео над внешностью. Если фото должно говорить как аватар, изучите HeyGen Avatar IV.
Быстрый старт 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/image-to-video",
"input": {
"duration_seconds": 5,
"image_url": "https://example.com/reference.png",
"prompt": "A slow aerial shot drifting over a misty pine forest at sunrise",
"prompt_optimization_mode": "disabled",
"resolution": "768p"
}
}'
# 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.

