Gemini Omni 1.2 Flash · API

Inicio rápido

Tres pasos: envía un trabajo, consúltalo y toma el enlace del vídeo. Sustituye YOUR_API_KEY por tu clave y los comandos de abajo funcionan tal cual.

Paso 1 · Envía el trabajo (devuelve al momento un id de trabajo, 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": "un barco de papel flota por una calle de neones bajo la lluvia al anochecer mientras un niño con impermeable amarillo lo persigue riendo", "duration": 10, "resolution": "720P", "size": "16:9"}'

Respuesta (HTTP 202)

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

Paso 2 · Consulta cada 5–10 segundos hasta que status sea succeeded o failed

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

Respuesta cuando sale bien

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

Paso 3 · data[0].url es el clip (MP4). Se guarda 7 días; descárgalo en tu propio almacenamiento para conservarlo más tiempo.

Ejemplo completo (Python: enviar, esperar y guardar en disco)

import time
import requests

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

# 1. enviar el trabajo
job = requests.post(f"{BASE}/videos/generations", headers=HEADERS, json={
    "model": "gemini-omni-1.2-flash",
    "prompt": "un barco de papel flota por una calle de neones bajo la lluvia al anochecer mientras un niño con impermeable amarillo lo persigue riendo",
    "duration": 10,
    "resolution": "720P",
    "size": "16:9",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. consultar cada 10 segundos, durante una hora como máximo
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. descargar el vídeo
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"])

Mientras está en cola, la consulta también devuelve queue_position (trabajos por delante del tuyo) y eta_seconds (espera estimada). Si se agota el tiempo máximo que fijaste, no vuelvas a enviarlo: el trabajo sigue ahí, así que vuelve a consultar el mismo id más tarde.

Autenticación

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Crea una clave API en la consola para empezar.

De un vistazo

Parámetros de la petición

El cuerpo JSON de POST /v1/videos/generations:

Los demás campos (seed, negative_prompt, fps, watermark y similares) no se reenvían y no cambian el precio; los resultados siempre son MP4 y se devuelven como url.

Precio

Por segundo: coste = tarifa por segundo de la resolución elegida x la duración. Una edición se factura por los segundos del original (lo que pase del último segundo entero se corta y no se cobra). Las imágenes de referencia no se cobran. Ese importe se retiene al enviar y se cobra al terminar con éxito; los fallos se reembolsan íntegramente. 1 crédito = $0.005.

Material de referencia

• Primer / primer y último fotograma: una imagen en image es el primer fotograma; dos en images con image_role: first_frame son primer y último fotograma. Hasta 10 segundos. Haz coincidir la orientación de las imágenes con size.
• Referencias: de 1 a 3 imágenes en images con image_role: reference (2-3 imágenes son referencias por defecto); las personas, objetos o escenarios aparecen en el clip sin convertirse en fotograma. Nómbralas @Image1 / @Image2 en el prompt.
• Edición de vídeo: un vídeo de 1 a 15 s en video_urls y un prompt que diga qué cambiar, p. ej. «hazlo de noche bajo la luna, deja todo lo demás igual»; pueden acompañarlo hasta 5 imágenes de referencia («sustituye a la persona por la de @Image1»). Descargamos el original al enviar y lo medimos: ilegible, de menos de 1 s o de más de 15 s devuelve 400, sin cargo.
• Aún no disponible: 360P, continuación (extend), vídeo / audio de referencia, negative_prompt (escribe en el prompt lo que no quieres).
• Cada imagen puede ser una URL pública de imagen, un data: URI o base64, de hasta 16 MB; para enviar varias, ponlas en un array en images. Guardamos las imágenes antes de poner el trabajo en cola; si alguna no se puede leer, la petición se rechaza con 400, message indica cuál y no se cobra nada.
• Los archivos de referencia que alojamos y los resultados se guardan 7 días.

Edición de vídeo: cambiar el escenario y poner a la persona de una imagen de referencia

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": "hazlo de noche bajo la luna y sustituye a la persona del centro por la de @Image1, deja todo lo demás igual", "video_urls": ["https://example.com/clip-8s.mp4"], "images": ["https://example.com/person.png"], "resolution": "720P"}'

El resultado sigue la duración del original; un original de 8 s se factura como 8 s y la imagen de referencia no se cobra.

Estado y campos del trabajo

GET /v1/videos/jobs/{id} devuelve estos estados; cada campo se describe en Trabajos asíncronos. Consulta cada 5–10 segundos o deja que un webhook (más abajo) te envíe el resultado. Las consultas son gratis, y cualquier clave de la misma cuenta puede consultar el trabajo.

• processing puede volver a queued, por ejemplo mientras el servicio está saturado, mientras se vuelve a obtener un clip ya terminado o tras un reinicio del servicio. Si un trabajo no se puede terminar, la pasarela puede volver a generarlo automáticamente; se reintente las veces que se reintente, el trabajo se cobra una sola vez.
• Cada cuenta ejecuta hasta 50 trabajos a la vez; los demás esperan en orden de envío, y un trabajo que no ha empezado a los 15 minutos falla y se reembolsa íntegro. Los registros de trabajos se guardan 3 días y los enlaces de los vídeos, 7 días.

Cuánto tarda

Nuestras pruebas: 3-6 s en 720P cerca de 1 minuto, 13 s en 1080P unos 2,5 minutos, 4K unos 3 minutos, ediciones cerca de 1,5 minutos; más con cola, hasta 20 minutos, después reembolso íntegro.

Errores y reembolsos

Un error al enviar se devuelve al momento como HTTP 4xx / 5xx: no se crea ningún trabajo y no se cobra nada. Un fallo después de que el trabajo fue aceptado lo informa el endpoint del trabajo, y la retención se reembolsa íntegra. Todos los códigos están en Códigos de error.

Errores al enviar

Trabajos fallidos (status failed)

Decide según code, no según el texto de message. Trata cualquier code que no reconozcas (o un error sin code) como upstream_error: volver a enviarlo suele funcionar. Todos los trabajos fallidos se reembolsan íntegros.

Webhooks en lugar de consultas

Añade callback_url al enviar y, en cuanto termine el trabajo, con éxito o con error, la pasarela enviará a esa URL exactamente lo mismo que devuelve el endpoint de consulta, firmado y con reintentos si la entrega falla. También puedes configurar una dirección para toda la cuenta en Configuración → Webhook, en la consola. Documentación de 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": "un barco de papel flota por una calle de neones bajo la lluvia al anochecer mientras un niño con impermeable amarillo lo persigue riendo", "duration": 10, "resolution": "720P", "size": "16:9", "callback_url": "https://your-domain.com/webhook"}'