Генерация видео

Обновлено: 31 октября 2026

Видео генерируется асинхронно: вы ставите задачу, опрашиваете статус и скачиваете готовый файл. Сейчас доступ открыт части аккаунтов; если POST /v1/videos отвечает 404 video_not_enabled, напишите в поддержку.

Коротко

Видео через API в Heli генерируется асинхронно: POST /v1/videos ставит задачу, GET /v1/videos/{id} показывает статус, готовый файл хранится около 24 часов. Цена — в рублях за секунду видео, на время генерации сумма резервируется, а за неудавшуюся генерацию ничего не списывается. Сейчас доступ открыт части аккаунтов.

1. Поставить задачу

curl https://getheli.ru/v1/videos \
  -H "Authorization: Bearer $HELI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/veo-3.1-fast",
    "prompt": "Медленный наезд камеры на неоновую вывеску кофейни, дождь на стекле",
    "duration": 4,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

Поля: model, prompt, duration (или seconds, секунды), resolution, aspect_ratio, size, generate_audio, seed. Для видео из картинки — frame_images (первый/последний кадр, frame_type: first_frame / last_frame), для стиля — input_references. Картинки передаются как {"type":"image_url","image_url":{"url":"https://…"}}. Допустимые длительности, разрешения и пропорции у каждой модели свои: смотрите GET /v1/models, у видеомоделей kind: "video" и блок video.

Ответ сразу, генерация идёт в фоне:

{
  "id": "video_4f1c…",
  "object": "video",
  "model": "google/veo-3.1-fast",
  "status": "queued",
  "created_at": 1793352000,
  "completed_at": null,
  "expires_at": null,
  "seconds": "4",
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "outputs": 0,
  "content_url": null,
  "cost_rub": null,
  "error": null
}

2. Дождаться и скачать

Опрашивайте GET /v1/videos/{id} раз в 10–30 секунд. Статусы: queued, in_progress, completed, failed, expired. Генерация обычно занимает от 30 секунд до нескольких минут. Когда статус completed, файл отдаёт content_url (тот же ключ в заголовке Authorization, поддерживается Range).

curl https://getheli.ru/v1/videos/video_4f1c… \
  -H "Authorization: Bearer $HELI_API_KEY"

curl -L https://getheli.ru/v1/videos/video_4f1c…/content \
  -H "Authorization: Bearer $HELI_API_KEY" -o video.mp4

Файл хранится ограниченное время. Скачайте его до expires_at (обычно 24 часа после готовности): потом content отвечает 410, и видео нужно генерировать заново. Мы не храним ваши видео у себя.

Цена и резерв

Цена — в рублях за секунду видео и зависит от разрешения (таблица на странице моделей и в кабинете). При постановке задачи резервируем максимальную цену секунды × секунды (если длительность не указана — максимальную для модели). Когда видео готово, списываем фактическую стоимость, остаток резерва возвращается. Если генерация не удалась, отклонена модерацией или истекла, ничего не списываем. Итоговая сумма — в поле cost_rub.

Одновременно у аккаунта может идти ограниченное число задач (по умолчанию 2); при превышении — 429 too_many_active_videos. Не хватает баланса на резерв — 402.