Генерация видео: как использовать

Видео генерируется асинхронно, цикл Sora-совместимый: POST /v1/videos создаёт задачу, GET /v1/videos/{id} опрашивает статус, GET /v1/videos/{id}/content отдаёт готовый MP4. Модель обязательна — например, google/veo-3.1-fast или kling/v3. Баланс проверяется при создании задачи, а списание (тариф за секунду) происходит только после успешного завершения генерации.

Как устроен цикл генерации?

Три шага. Создали задачу — получили video object со статусом queued. Опрашиваете статус — он проходит queued → in_progress → completed (или failed, тогда в error будут code и message). Дождались completed — скачиваете MP4. Генерация занимает минуты, поэтому опрашивать раз в 5-10 секунд более чем достаточно.

Как создать задачу?

Эндпоинт принимает и application/json, и multipart/form-data — второй формат использует client.videos.create() из OpenAI SDK.

Параметры:

• prompt — обязателен, до 5000 символов.
• model — обязателен, дефолта нет. Видео-модели помечены в каталоге.
• seconds — длительность, строкой или числом («4», «6», «8»). Шлюз принимает 1-60, фактический набор длительностей задаёт модель: Veo 3.1 — 4, 6 или 8 секунд.
• size — «ШИРИНАxВЫСОТА»: 1280x720 (16:9), 720x1280 (вертикальное 9:16), 1920x1080 (16:9 в 1080p). Внутри маппится на соотношение сторон и разрешение; 1080p получается, когда меньшая сторона ≥ 1080.
• input_reference — стартовый кадр для image-to-video: в multipart — файл (до 20 МБ), в JSON — URL картинки.
• provider-specific поля — generate_audio, seed, negative_prompt — принимаются в JSON и уходят провайдеру.

Полная схема запроса и ответа — в референсе создания видео.

Как узнать, что видео готово?

Опрашивать GET /v1/videos/{id} — именно этот запрос продвигает статус (мы ходим к провайдеру в момент вашего опроса). progress грубый: 0, 50 или 100 — точных процентов провайдеры не отдают. Поля ответа — в референсе статуса.

Списание за генерацию происходит в момент перехода в completed. Задача завершилась с failed — денег не берём.

Как скачать результат?

GET /v1/videos/{id}/content отдаёт байты MP4 (Content-Type: video/mp4). Скачивание бесплатное, сколько угодно раз. Если генерация ещё идёт, придёт 409 video_not_ready; чужой или несуществующий id — 404 (коды разобраны в гайде «Ошибки API»).

Список всех задач ключа — GET /v1/videos с курсорной пагинацией (limit до 100, after — id последнего видео предыдущей страницы, в ответе has_more). Список статусы не продвигает — только GET /v1/videos/{id}.

Что за /v1/video/generations?

Наш исходный, до-Sora формат: POST /v1/video/generations возвращает 202 и job в статусе processing, статус и скачивание — по GET /v1/video/generations/{job_id} и .../download. Он остаётся рабочим документированным алиасом — существующие интеграции ломать не будем. Для нового кода берите /v1/videos: его понимает OpenAI SDK.

Сколько стоит видео?

Тариф — за секунду готового ролика, у каждой модели свой. Актуальные цены — на странице цен для разработчиков. Посмотреть, как генерирует Veo 3.1, без кода можно на сайте.