# Gemini Omni 1.2 Flash — /videos/generations

Gemini Omni 1.2 Flash — модель генерации и редактирования видео, которую Google выпустила в ноябре 2026 года. Отправьте асинхронную задачу через `POST /v1/videos/generations`: без изображения — видео из текста, одно изображение — первый кадр, два — первый и последний кадр, 1–3 референса или видео длиной 1–15 с, чтобы его отредактировать. 720P / 1080P / 4K, 16:9 или 9:16, со звуком и без видимого водяного знака. Оплата по секундам; правка — по секундам исходника.

**Эндпоинт:** `POST https://kovapi.com/v1/videos/generations`

## Быстрый старт

Три шага: отправить задачу, опросить её и забрать ссылку на видео. Замените YOUR_API_KEY своим ключом, и команды ниже заработают как есть.

**Шаг 1 · Отправка (сразу возвращает id задачи, HTTP 202)**

```
curl https://kovapi.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-omni-1.2-flash", "prompt": "бумажный кораблик плывёт по дождливой неоновой улице в сумерках, ребёнок в жёлтом дождевике со смехом бежит за ним", "duration": 10, "resolution": "720P", "size": "16:9"}'
```

Ответ (HTTP 202)

```
{
  "id": "img_5c2e8f1a9b3d7e6f0a4c8b2d",
  "object": "video.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "gemini-omni-1.2-flash"
}
```

**Шаг 2 · Опрашивайте каждые 5–10 секунд, пока `status` не станет `succeeded` или `failed`**

```
curl https://kovapi.com/v1/videos/jobs/img_5c2e8f1a9b3d7e6f0a4c8b2d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Ответ при успехе

```
{
  "id": "img_5c2e8f1a9b3d7e6f0a4c8b2d",
  "object": "video.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "gemini-omni-1.2-flash",
  "data": [
    {"url": "https://img.kovapi.com/i/8c1f0e5d2b7a49e3a6d0c4f1b9e2a7d5.mp4"}
  ],
  "usage": {"clips": 1, "model": "gemini-omni-1.2-flash"}
}
```

**Шаг 3 · `data[0].url` — это ролик (MP4). Он хранится 7 дней; чтобы пользоваться им дольше, скачайте его в своё хранилище.**

**Полный пример (Python: отправить, дождаться, сохранить на диск)**

```
import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. отправка
job = requests.post(f"{BASE}/videos/generations", headers=HEADERS, json={
    "model": "gemini-omni-1.2-flash",
    "prompt": "бумажный кораблик плывёт по дождливой неоновой улице в сумерках, ребёнок в жёлтом дождевике со смехом бежит за ним",
    "duration": 10,
    "resolution": "720P",
    "size": "16:9",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. опрос каждые 10 секунд, не дольше часа
deadline = time.time() + 3600
while job["status"] not in ("succeeded", "failed") and time.time() < deadline:
    time.sleep(10)
    job = requests.get(f"{BASE}/videos/jobs/{job['id']}", headers=HEADERS).json()

# 3. скачивание видео
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("gemini-omni-1.2-flash.mp4", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
elif job["status"] == "failed":
    print("failed:", job["error"]["code"], job["error"]["message"])
else:
    print("still", job["status"], job["id"])
```

Пока задача в очереди, опрос также возвращает `queue_position` (сколько задач впереди вашей) и `eta_seconds` (ожидаемое время ожидания). Если ваш лимит ожидания истёк, не отправляйте задачу заново: она никуда не делась, продолжайте опрашивать тот же id позже.

## Аутентификация
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Основные характеристики

| Длительность | 3–15 с с шагом в секунду (по умолчанию 10) · кадры 3–10 с · правка — по длине исходника (1–15 с) |
| --- | --- |
| Разрешение | 720P / 1080P / 4K |
| Пропорции | 16:9 / 9:16 |
| Референсные изображения | первый кадр 1 · первый и последний 2 · референсы 1–3 · до 5 референсов при правке |
| Правка видео | Правка видео: один исходник, 1–15 с, mp4 / mov, до 50 МБ · оплата по секундам исходника |
| Референсное аудио | не поддерживается |
| Звук | Всегда включён (реплики, музыку и эффекты описывайте в промпте); отключить нельзя (`audio: false` отклоняется) |
| Длина промпта | до 20 000 символов (китайский и английский считаются одинаково) |
| Оплата | По секундам: цена за секунду выбранного разрешения x длительность (для правки — секунды исходника) |

## Параметры запроса

JSON-тело запроса `POST /v1/videos/generations`:

| Параметр | Тип | Обязательный | Описание |
| --- | --- | --- | --- |
| model | string | Да | ID модели: `gemini-omni-1.2-flash`. |
| prompt | string | Да | Описание видео, камеры, действия и звука, до 20 000 символов (китайский и английский считаются одинаково). Несколько референсов называйте @Image1 / @Image2; для правки напишите, что изменить, например «сделай ночь, остальное без изменений». negative_prompt не поддерживается: пишите нежелательное прямо в промпт. |
| duration | integer | Нет | Длительность: целое число от 3 до 15 секунд (по умолчанию 10); псевдоним `seconds`. Режим кадров: 3–10 с; для правки не указывайте — длительность берётся из исходника. Оплата по секундам, см. «Цены» ниже. |
| resolution | string | Нет | Разрешение: 720P (по умолчанию) / 1080P / 4K (1080P и 4K — официальный апскейл; 4K вертикально — 2160x3840). Принимаются и 720p, 1080p, 4k, 2160p. 360P недоступно. |
| size | string | Нет | Соотношение сторон: 16:9 (по умолчанию) / 9:16; псевдоним aspect_ratio. Другие соотношения отклоняются. Для правки без указания берётся ориентация исходника. |
| images | array | Нет | Несколько изображений (до 16 МБ каждое): 2–3 по умолчанию референсы (не больше 3); с image_role=first_frame два — первый и последний кадр; правка принимает до 5 референсов. Принимаются также image_urls и image_with_roles ([{"url": ..., "role": "first_frame" \| "last_frame" \| "reference"}]). Превышение лимита отклоняется, а не обрезается. Одно изображение (публичный URL, data: URI или base64): по умолчанию первый кадр (3–10 с); с image_role=reference — референс. Принимаются также first_frame_image и last_frame_image. |
| image_role | string | Нет | `first_frame` (первый кадр / первый и последний, 3–10 с) или `reference` (1–3 референса). Без указания одно изображение — первый кадр, 2–3 — референсы. Принимаются и другие распространённые написания: `first_frame_image`, `last_frame_image`, `image_urls`, `image_with_roles`, `omni_reference_task_type`. |
| video_urls | array | Нет | Правка видео: одно видео длиной 1–15 с (mp4 / mov, до 50 МБ; публичная ссылка, data:video/mp4;base64,... или загрузка в Playground); псевдонимы video_url / video_references. Результат той же длины, что исходник, и оплачивается по его секундам; всё после последней целой секунды обрезается (4,5 с — как 4 с). Нельзя совмещать с кадрами; продолжение (extend) недоступно. |
| audio | boolean | Нет | Модель всегда генерирует звук (реплики, музыку и эффекты описывайте в промпте); параметр можно не указывать (false отклоняется). |
| callback_url | string | Нет | Куда отправить результат, когда задача завершится; подробнее — в разделе о вебхуках ниже. |
| n | integer | Нет | Каждая задача создаёт один ролик; передавать параметр не нужно. При значении больше 1 всё равно создаётся один ролик, но при отправке резервируется стоимость n роликов, а лишнее возвращается после завершения задачи. |

Другие поля (`seed`, `negative_prompt`, `fps`, `watermark` и т. п.) дальше не передаются и не влияют на цену; результат всегда в MP4 и возвращается в виде `url`.

## Цена

Оплата по секундам: стоимость = цена за секунду выбранного разрешения x длительность. Правка оплачивается по секундам исходника (всё после последней целой секунды обрезается и не оплачивается). Референсные изображения бесплатны. Эта сумма удерживается при отправке и списывается при успехе; при ошибке — полный возврат. 1 кредит = $0.005.

| Разрешение | Кредитов за секунду | USD за секунду | Ролик 10 с | Правка исходника на 8 с |
| --- | --- | --- | --- | --- |
| 720P | 7 | $0.035 | $0.35 | $0.28 |
| 1080P | 10 | $0.05 | $0.50 | $0.40 |
| 4K | 20 | $0.10 | $1.00 | $0.80 |

## Референсные материалы

- **Первый / первый и последний кадр**: одно изображение в `image` — первый кадр; два в `images` с `image_role: first_frame` — первый и последний кадр. До 10 секунд. Ориентация изображений должна совпадать с `size`.

- **Референсы**: 1–3 изображения в `images` с `image_role: reference` (2–3 изображения по умолчанию референсы); люди, предметы или обстановка появляются в ролике, не становясь кадром. В промпте их можно называть @Image1 / @Image2.

- **Правка видео**: одно видео длиной 1–15 с в `video_urls` и промпт о том, что изменить, например «сделай лунную ночь, остальное без изменений»; можно приложить до 5 референсных изображений («замени человека на того, что на @Image1»). При отправке мы скачиваем исходник и измеряем его: нечитаемый, короче 1 с или длиннее 15 с — ответ 400 без списания.

- Пока недоступно: 360P, продолжение (extend), референсное видео / аудио, negative_prompt (нежелательное пишите прямо в промпт).

- Каждое изображение — публичная ссылка на изображение, `data:` URI или base64, не более 16 MB; несколько изображений передавайте массивом в `images`. При отправке мы сначала сохраняем изображения у себя, и только потом задача встаёт в очередь; изображение, которое не удаётся прочитать, отклоняется с ошибкой 400, в `message` указано, какое именно, и ничего не списывается.

- Референсные материалы, которые мы размещаем у себя, и готовые ролики хранятся 7 дней.

**Правка видео: сменить обстановку и подставить человека с референса**

```
curl https://kovapi.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-omni-1.2-flash", "prompt": "сделай лунную ночь и замени человека в центре на того, что на @Image1, остальное без изменений", "video_urls": ["https://example.com/clip-8s.mp4"], "images": ["https://example.com/person.png"], "resolution": "720P"}'
```

Результат той же длины, что исходник; исходник на 8 с оплачивается как 8 с, референс бесплатный.

## Статус задачи и поля ответа

`GET /v1/videos/jobs/{id}` возвращает эти статусы; все поля описаны в разделе [Асинхронные задачи](https://docs.kovapi.com/ru/guide/async-jobs#fields). Опрашивайте каждые 5–10 секунд или получайте результат вебхуком (см. ниже). Опрос бесплатный, и прочитать задачу может любой ключ того же аккаунта.

| Статус | Что значит |
| --- | --- |
| queued | В очереди. В ответе есть `queue_position` (сколько задач впереди) и `eta_seconds` (ожидаемое время ожидания). |
| processing | Генерируется. |
| succeeded | Готово. Результат в `data[0].url`, детали оплаты в `usage`. |
| failed | Ошибка. Причина в `error`; зарезервированные кредиты возвращаются полностью. |

- `processing` может снова смениться на `queued`: например, при высокой нагрузке, пока готовый ролик скачивается повторно или после перезапуска сервиса. Если задачу не удалось выполнить, шлюз может автоматически запустить рендер заново; сколько бы ни было повторов, задача оплачивается один раз.

- Один аккаунт выполняет до 50 задач одновременно; остальные ждут в порядке отправки, а задача, не начавшаяся за 15 минут, завершается ошибкой с полным возвратом. Записи о задачах хранятся 3 дня, ссылки на видео — 7 дней.

## Сколько ждать

Наши тесты: 3–6 с в 720P — около 1 минуты, 13 с в 1080P — около 2,5 минуты, 4K — около 3 минут, правка — около 1,5 минуты; в очереди дольше, ждём до 20 минут, затем полный возврат.

## Ошибки и возвраты

Ошибка при отправке сразу возвращается как HTTP 4xx / 5xx: задача не создаётся, ничего не списывается. О неудаче после того, как задача принята, сообщает эндпоинт задачи, а резерв возвращается полностью. Все коды перечислены в разделе [Коды ошибок](https://docs.kovapi.com/ru/guide/errors).

### Ошибки при отправке

| HTTP | code | Причина | Что делать |
| --- | --- | --- | --- |
| 400 | invalid_request | Недопустимый параметр: длительность, разрешение, пропорция или число референсов выходят за пределы, допустимые для этой модели; промпт слишком длинный; не удаётся прочитать референсное изображение или видео; передан `audio: false` модели, ролики которой всегда со звуком, и т. п. Что именно не так, указано в `message`. | Исправьте то, что указано в `message`, и отправьте снова. |
| 400 | invalid_source_video | Исходное видео не принято: не удалось прочитать длительность, оно короче 1 с или длиннее 15 с, либо файл повреждён. | Отправьте вместо него воспроизводимый mp4 / mov длиной 1–15 с; за этот запрос ничего не списано. |
| 400 | invalid_callback_url | `callback_url` — не публичный адрес http(s) или длиннее 2000 символов. | Укажите адрес, доступный из интернета. |
| 400 | model_not_found | ID модели написан с ошибкой, `model` не передан или модель нельзя использовать на этом эндпоинте (например, чат-модель на эндпоинте изображений). | Берите ID модели из `GET /v1/models` или из [справочника API](https://docs.kovapi.com/ru/api). |
| 401 | invalid_api_key | Ключ не существует, удалён или отключён, либо отключён аккаунт. | Проверьте ключ на странице API Keys в консоли. |
| 402 | insufficient_quota | Баланса не хватает, чтобы зарезервировать стоимость этого запроса. Шлюз сначала резервирует максимально возможную стоимость запроса, поэтому ошибка может возникнуть и при всплеске одновременных вызовов. | Если был всплеск запросов, подождите несколько секунд и повторите; в остальных случаях пополните баланс. |
| 429 | rate_limit_exceeded | Превышен лимит запросов в минуту, заданный для этого ключа (считается за последние 60 секунд). Заголовка `Retry-After` нет. | Подождите несколько секунд и повторите или увеличьте лимит ключа в консоли. |
| 503 | model_maintenance | Модель на обслуживании и не принимает запросы; пока идёт обслуживание, другая модель вместо неё не ответит. | Повторите, когда обслуживание закончится; ход работ — на [странице статуса](https://kovapi.com/ru/status). |
| 503 | service_unavailable | Временный сбой на нашей стороне, например при сохранении референсного файла. Задача не создана, ничего не списано. | Повторите чуть позже. |

### Неудачные задачи (`status` — `failed`)

| code | Когда возникает | Что делать |
| --- | --- | --- |
| content_policy | Промпт или референсное изображение не прошли проверку контента у поставщика модели. | Перепишите промпт или замените референс и только потом отправляйте снова: те же входные данные будут отклонены повторно. |
| invalid_request | Поставщик модели не принимает такое сочетание параметров (например, режима и разрешения). Причина указана в `message`. | Измените параметры согласно `message` и отправьте снова. |
| wait_timeout | Видео: за 120 минут результата не было, задача завершилась по таймауту, кредиты возвращены полностью; если ролик будет готов позже, он выдаётся бесплатно. | Отправьте задачу заново. |
| upstream_error | Любая другая ошибка: автоматические повторы не помогли, задача ждала 15 минут и так и не запустилась, поставщик отказал без объяснения причины и т. п.; что именно произошло, указано в `message`. | Обычно повторная отправка проходит успешно. |

Ориентируйтесь на `code`, а не на текст `message`. Любой незнакомый `code` (или его отсутствие) обрабатывайте как `upstream_error`: повторная отправка обычно проходит успешно. За каждую неудачную задачу деньги возвращаются полностью.

## Вебхуки вместо опроса

Добавьте при отправке `callback_url` — как только задача завершится, успешно или с ошибкой, шлюз отправит на этот URL ровно то же, что возвращает эндпоинт опроса; запрос подписан, а при неудачной доставке повторяется. Общий адрес для всего аккаунта можно также задать в консоли, в разделе «Настройки → Вебхуки». [Документация по вебхукам →](https://docs.kovapi.com/ru/webhooks)

```
curl https://kovapi.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-omni-1.2-flash", "prompt": "бумажный кораблик плывёт по дождливой неоновой улице в сумерках, ребёнок в жёлтом дождевике со смехом бежит за ним", "duration": 10, "resolution": "720P", "size": "16:9", "callback_url": "https://your-domain.com/webhook"}'
```