Gemini Omni 1.2 Flash · API

Quick start

Three steps: submit a job, poll it, take the video link. Replace YOUR_API_KEY with your key and the commands below run as they are.

Step 1 · Submit (returns a job id at once, 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": "a paper boat drifts down a rainy neon street at dusk while a child in a yellow raincoat runs after it laughing", "duration": 10, "resolution": "720P", "size": "16:9"}'

Response (HTTP 202)

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

Step 2 · Poll every 5–10 seconds until status is succeeded or failed

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

Response when it succeeds

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

Step 3 · data[0].url is the clip (MP4). It is kept for 7 days; download it to your own storage to keep it longer.

Complete example (Python: submit, wait, save to disk)

import time
import requests

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

# 1. submit
job = requests.post(f"{BASE}/videos/generations", headers=HEADERS, json={
    "model": "gemini-omni-1.2-flash",
    "prompt": "a paper boat drifts down a rainy neon street at dusk while a child in a yellow raincoat runs after it laughing",
    "duration": 10,
    "resolution": "720P",
    "size": "16:9",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. poll every 10 seconds, for up to an hour
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. download the video
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"])

While queued, the poll also returns queue_position (jobs ahead of yours) and eta_seconds (expected wait). If your time limit passes, do not resubmit: the job is still there, so keep polling the same id later.

Authentication

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Create an API Key in the console to start.

At a glance

Request parameters

The JSON body of POST /v1/videos/generations:

Other fields (seed, negative_prompt, fps, watermark and the like) are not passed on and do not change the price; results are always MP4, returned as a url.

Price

Billed per second: cost = the per-second rate of the chosen resolution x the length. A video edit is billed by the source seconds (a part past the last whole second is cut and not billed). Reference images are free. That amount is held at submit and settled on success; failures are refunded in full. 1 credit = $0.005.

Reference material

• First / first + last frame: one image in image is the first frame; two in images with image_role: first_frame are first + last frame. Up to 10 seconds. Match the orientation of the images to size.
• References: 1-3 images in images with image_role: reference (2-3 images are references by default); the people, objects or settings appear in the clip without becoming a frame. Name them @Image1 / @Image2 in the prompt.
• Video edit: one 1-15 s video in video_urls, and a prompt saying what to change, e.g. "make it night under the moon, keep everything else the same"; up to 5 reference images can come along ("replace the person with the one in @Image1"). We download the source at submit and measure it: unreadable, under 1 s or over 15 s returns 400, not charged.
• Not available yet: 360P, continuation (extend), reference video / audio input, negative_prompt (write what you do not want into the prompt).
• Each image is a public image URL, a data: URI or base64, up to 16 MB; send several as an array in images. We store the images before the job is queued; one that cannot be read is refused with 400, message says which, and nothing is charged.
• Reference files we store and the results are both kept for 7 days.

Video edit: change the setting and swap in the person from a reference image

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": "make it a moonlit night and replace the person in the centre with the one in @Image1, keep everything else the same", "video_urls": ["https://example.com/clip-8s.mp4"], "images": ["https://example.com/person.png"], "resolution": "720P"}'

The output follows the source length; an 8 s source is billed as 8 s, the reference image is free.

Job status and fields

GET /v1/videos/jobs/{id} reports these statuses; every field is described in Async jobs. Poll every 5–10 seconds, or let a webhook (below) push the result. Polling is free, and any key of the same account can read the job.

• processing can go back to queued, for example while the service is busy, while a finished clip is fetched again, or after a restart. If a job cannot be finished, the gateway may render it again automatically; however many retries it takes, a job is charged once.
• One account runs up to 50 jobs at a time; further jobs wait in submission order, and a job that has not started after 15 minutes fails and is refunded in full. Job records are kept for 3 days and video links for 7 days.

How long it takes

Our tests: 3-6 s at 720P about 1 minute, 13 s at 1080P about 2.5 minutes, 4K about 3 minutes, edits about 1.5 minutes; longer in a queue, up to 20 minutes, then fully refunded.

Errors and refunds

An error at submit comes back at once as HTTP 4xx / 5xx: no job is created and nothing is charged. A failure after the job was accepted is reported by the job endpoint, and the hold is refunded in full. Every code is listed under Error codes.

Errors at submit

Failed jobs (status failed)

Branch on code, not on the text of message. Treat any code you do not recognise (or a missing one) as upstream_error: resubmitting usually works. Every failed job is refunded in full.

Webhooks instead of polling

Add callback_url when you submit and the moment the job ends, success or failure, the gateway pushes exactly what the poll endpoint returns to that URL, signed and retried on failure. You can also set an account-wide address under Settings → Webhook in the console. Webhook docs →

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": "a paper boat drifts down a rainy neon street at dusk while a child in a yellow raincoat runs after it laughing", "duration": 10, "resolution": "720P", "size": "16:9", "callback_url": "https://your-domain.com/webhook"}'