Gemini Omni 1.2 Flash · API

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

Три шага: отправить задачу, опросить её и забрать ссылку на видео. Замените 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

Чтобы начать, создайте API-ключ в консоли.

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

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

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

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

Цена

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

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

• Первый / первый и последний кадр: одно изображение в 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} возвращает эти статусы; все поля описаны в разделе Асинхронные задачи. Опрашивайте каждые 5–10 секунд или получайте результат вебхуком (см. ниже). Опрос бесплатный, и прочитать задачу может любой ключ того же аккаунта.

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

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

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

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

Ошибка при отправке сразу возвращается как HTTP 4xx / 5xx: задача не создаётся, ничего не списывается. О неудаче после того, как задача принята, сообщает эндпоинт задачи, а резерв возвращается полностью. Все коды перечислены в разделе Коды ошибок.

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

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

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

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

Добавьте при отправке callback_url — как только задача завершится, успешно или с ошибкой, шлюз отправит на этот URL ровно то же, что возвращает эндпоинт опроса; запрос подписан, а при неудачной доставке повторяется. Общий адрес для всего аккаунта можно также задать в консоли, в разделе «Настройки → Вебхуки». Документация по вебхукам →

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"}'