Введение
Опишите в prompt героя, обстановку, действие и желаемый звук, затем выберите duration_seconds и разрешение. Seed помогает сравнивать правки, а prompt_optimization_mode определяет, разрешено ли перерабатывать задание.
| Характеристика | Значение |
|---|---|
| Ввод | Текст |
| Вывод | Видео |
| Разработчик и модель | 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 символов |
aspect_ratio | Нет | Перед отправкой выберите форму кадра из актуальных вариантов интерфейса. Планируйте композицию под место публикации, задавая формат явно в настройках. |
resolution | Нет | Для генерации по тексту выберите 480p или 768p. Наш тест 480p дал 832×480. |
duration_seconds | Нет | Запросите от 5 до 15 секунд. Пятисекундные файлы в наших тестах длились 5,18–5,26 секунды после округления кадров, но оплата учитывала пять секунд результата. |
prompt_optimization_mode | Нет | Задайте disabled, если хотите избежать переработки текста. turbo и quality разрешают модели переписать задание; при сравнении описаний сохраняйте этот выбор. |
seed | Нет | Фиксируйте seed и меняйте одну деталь сцены для удобства сравнения. Совпадение seed не гарантирует идентичного результата. |
Стоимость
Оплата за запрошенные секунды результата по ставке 480p или 768p на странице. Округление до целых кадров не увеличивает оплачиваемую заказанную длину.
| Спецификация | Стоимость |
|---|---|
| $0.03 / секунду |
| $0.054 / секунду |
Сценарии использования
Сцена до начала съёмок
Отправьте описание гончара примерно тридцати лет в брезентовом фартуке, который поворачивается к полке в залитой солнцем мастерской. Запрос на пять секунд в 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 со стереодорожкой AAC. Для этого интерфейса нужно описание, поэтому он подходит для концептуального плана до появления фотографий или отснятого материала.
Отправьте описание сцены
Для вызова heygen/video-1/text-to-video отправьте этот JSON на https://api.spicyapi.ai/api/v1/jobs/createTask. Укажите Authorization: Bearer YOUR_SPICY_API_KEY и Content-Type: application/json. Сцена ниже — предлагаемый запрос, без воспроизведения нашего измеренного теста.
{
"model": "heygen/video-1/text-to-video",
"input": {
"prompt": "A potter in their thirties, wearing a blue work shirt, turns toward a shelf in a sunlit studio. Static medium shot, warm side light, thoughtful mood. Sound: quiet studio ambience, no music.",
"duration_seconds": 5,
"resolution": "480p",
"prompt_optimization_mode": "disabled",
"seed": 42
}
}
Получите ответ задачи
Прочитайте data.taskId в ответе на отправку и вызывайте GET /api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID со своим Bearer-ключом. Успешный результат содержит URL созданного файла; примеры опускают посторонние поля ответа и используют условные идентификаторы и адреса.
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_text_example",
"state": "queued"
}
}
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_text_example",
"state": "succeeded",
"output": {
"assets": [{"url": "https://example.com/generated-scene.mp4"}]
}
}
}
Полный формат запроса и ответа приведён в руководстве API задач. Откройте URL файла, чтобы оценить изображение и прослушать созданную дорожку.
Выберите настройки сцены
Следующие параметры задают длительность, размер изображения и обработку описания. Если важен формат публикации, выберите соотношение сторон среди актуальных вариантов интерфейса.
| Параметр | Назначение и поддерживаемые настройки |
|---|---|
prompt | Опишите героя, видимое действие, обстановку, свет и желаемый звук. |
duration_seconds | Запросите результат на 5–15 секунд. |
resolution | Выберите 480p или 768p; ступени 1080p здесь нет. |
aspect_ratio | Укажите поддерживаемую форму кадра в текущих настройках интерфейса. |
prompt_optimization_mode | disabled, turbo или quality; последние два разрешают переработку текста. |
seed | Зафиксируйте при сравнении одной правки описания; идентичный выход не гарантируется. |
Поставьте компактный план
Прежде чем добавлять указания камеры, задайте одному видимому действию ясную обстановку. Например, опишите поворот человека к полке вместо сочетания экскурсии по комнате, жеста и смены сцены в одном коротком ролике.
HeyGen рекомендует называть постановку камеры, освещение и источники звука. Руководство отдаёт предпочтение цельным сценам и отмечает ограничения сложных движений рук и длинных надписей в кадре. Учитывайте рекомендации разработчика и проверяйте эти детали в собственном результате.
- Последовательно укажите человека, одежду, место и действие.
- Добавьте конкретный ракурс, например неподвижный средний план со светом из окна.
- Опишите нужные звуки; при необходимости укажите отсутствие музыки.
- Сравните правку с прежними seed и режимом переработки, затем меняйте другие настройки.
Изучите замеренный результат
Наш нейтральный текстовый тест запрашивал пять секунд в 480p и дал видео 832×480 при 24 кадрах/с со стереозвуком AAC. В этом запуске обработка заняла около 10 секунд; типичный срок для всех сцен этим не установлен.
В предоставленных тестах запросы на пять секунд дали файлы на 5,18–5,26 секунды с округлением до целых кадров. Если на временной шкале нужна точная точка монтажа, измерьте файл и обрежьте его в редакторе.
Разберитесь в единице оплаты
Генерация по тексту оплачивается за секунду запрошенного результата по текущей ставке выбранного разрешения на странице. Запрос на пять секунд учитывается как пять секунд выхода, даже если округление кадров немного удлиняет воспроизведение. Для пробы композиции выберите 480p, затем рассмотрите 768p под нужный результат. Это предложение по процессу работы без сравнительной оценки качества.
Проверьте ограничения и выберите другую задачу
Перед отправкой оставьте длительность в пределах 5–15 секунд и выберите 480p или 768p. При ошибке входа сравните имена полей и разрешение с таблицей и текущей схемой. При неудаче задачи изучите errorCode и errorMessage, дождитесь успешного завершения перед использованием видео.
Выберите анимацию фото, если конкретный снимок должен определять человека и композицию или нужны нативные 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/text-to-video",
"input": {
"prompt": "A slow aerial shot drifting over a misty pine forest at sunrise",
"resolution": "768p",
"aspect_ratio": "16:9",
"duration_seconds": 5,
"prompt_optimization_mode": "disabled"
}
}'
# 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.

