KovAPIKovAPI
nano-banana-2-lite

Nano Banana 2 Lite · API

POST https://kovapi.com/v1/images/generations

Generación de imágenes (asíncrona, por trabajos) con Google Nano Banana 2 Lite (Gemini 3.1 Flash Lite Image), el modelo más rápido y económico de la familia Nano Banana. Para texto a imagen basta el prompt; para editar, pon las referencias en image o images (URL, data: URI o base64) o llama a /v1/images/edits. Al enviar recibes al instante un id de trabajo (HTTP 202); consulta GET /v1/images/jobs/{id} para obtener la imagen. Solo 1K, en 14 proporciones: 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 21:9, 4:1, 1:4, 8:1 y 1:8. Una solicitud en 2K o 4K se rechaza al enviar y no se cobra. Se cobra por imagen; las solicitudes fallidas no se cobran.

Probar en el Playground →

Inicio rápido

Tres pasos: enviar el trabajo, consultarlo y quedarte con el enlace de la imagen. Sustituye YOUR_API_KEY por tu clave y los comandos de abajo funcionan tal cual.

Paso 1 · Enviar (devuelve un id de trabajo al instante, HTTP 202)
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2-lite", "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field", "size": "16:9", "resolution": "1K"}'
Respuesta (HTTP 202)
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281500,
  "model": "nano-banana-2-lite"
}
Paso 2 · Consulta cada 2-3 segundos hasta que status sea succeeded o failed
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"
Respuesta cuando termina bien
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281500,
  "model": "nano-banana-2-lite",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.jpg"}
  ],
  "usage": {"images": 1, "resolution": "1K", "model": "nano-banana-2-lite"}
}

Paso 3 · data[0].url es la imagen (el original del upstream, en JPEG). Se guarda 7 días; descárgala a tu propio almacenamiento si la necesitas 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
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "nano-banana-2-lite",
    "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field",
    "size": "16:9",
    "resolution": "1K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. consultar cada 3 segundos hasta que termine
while job["status"] not in ("succeeded", "failed"):
    time.sleep(3)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

# 3. descargar la imagen
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("nano-banana-2-lite.jpg", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["message"])

Autenticación

Header
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Crea una clave API en la consola para empezar.

Cuerpo de la petición

ParámetroTipoObligatorioDescripción
model string Sí ID del modelo; aquí nano-banana-2-lite.
prompt string Sí Prompt de texto que describe la imagen.
size string No Relación de aspecto de salida. Recomendado: pasa una relación (1:1, 3:4, 2:3, 9:16, 4:3, 3:2, 16:9) y el modelo renderiza de forma nativa con esa proporción, sin recortar el sujeto. También se aceptan tamaños en píxeles (p. ej. 1024x1024, 1024x1536, 1536x1024). Por defecto 1:1 (cuadrada).
resolution string No Resolución: solo 1K (es la predeterminada; puedes omitirla). resolution 2K / 4K devuelve 400 unsupported_resolution al enviar y no se cobra. Si size es un tamaño en píxeles, los 14 tamaños nativos 1K de Lite (p. ej. 2928x352 o 1584x672) cuentan como 1K.
thinking_level string No Nivel de razonamiento, solo en nano-banana-2-lite: minimal (por defecto; se puede omitir) o high. high piensa antes de dibujar: tarda 3–6 segundos más y cuesta lo mismo. Vale la pena para composiciones complejas, cantidades exactas y texto; en nuestras pruebas las imágenes no se vieron claramente distintas. En otros modelos, high se rechaza al enviar con un 400, sin cobro.
n integer No Siempre 1: cada trabajo devuelve una imagen. Un valor mayor sigue devolviendo una imagen y cobrando una; para varias imágenes envía varios trabajos a la vez.
image string No Imagen a imagen: una imagen de referencia como URL pública, data: URI o base64 en bruto. Si está presente, la petición ejecuta una verdadera transformación imagen a imagen que preserva la identidad en el tamaño y la proporción elegidos, equivalente a llamar a /v1/images/edits.
images array No Varias imágenes de referencia, hasta 8 (si mandas más, solo se usan las 8 primeras): un array de cadenas o de objetos {"image_url": "..."}; cada una es una URL pública, un data: URI o base64, de hasta 16 MB. Enviarlas activa imagen a imagen, igual que /v1/images/edits. Para una sola referencia también sirve el campo image de arriba.

Ejemplo de petición

cURL
# 1) submit -> 202 {"id":"img_...","status":"queued"}
curl https://kovapi.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "nano-banana-2-lite", "prompt": "a serene ink-wash poster, lots of negative space", "size": "16:9", "resolution": "1K"}'
# 2) poll until status=succeeded
curl https://kovapi.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'

Respuesta

200 · JSON
{
  "id": "img_3f9a...c2",
  "object": "image.generation.job",
  "status": "queued",
  "model": "nano-banana-2-lite"
}

Precio

Se cobra por imagen y el precio depende solo del nivel de resolución: la proporción y si es texto a imagen o imagen a imagen no cambian nada. Al enviar se retiene el precio del nivel y, si el trabajo falla, se reembolsa por completo. 1 crédito = $0.005.

NivelCréditos por imagenUSD por imagen
1K2$0.01

Cada trabajo devuelve exactamente una imagen: envíes el n que envíes, recibes una imagen y pagas una. Para varias imágenes, envía varios trabajos a la vez (una cuenta genera hasta 50 al mismo tiempo).

Proporción, resolución y tamaño de salida

Pon la proporción en size; resolution se puede omitir (1K es el único nivel). El modelo dibuja directamente en la proporción elegida y recibes la imagen original del upstream, sin recortar ni redimensionar; cada proporción tiene un tamaño fijo, indicado abajo:

Proporción1K
1:11024x1024
16:91376x768
9:16768x1376
4:31200x896
3:4896x1200
3:21264x848
2:3848x1264
4:5928x1152
5:41152x928
21:91584x672
1:4512x2064
4:12064x512
1:8352x2928
8:12928x352

Solo se admiten las proporciones de la tabla (un tamaño en píxeles en size cuenta como la más cercana, con un margen del 1,5 %). Cualquier otra proporción falla de inmediato y no se cobra; no se dibuja una imagen para recortarla después.

size también puede ser un tamaño en píxeles: los tamaños de la tabla (p. ej. 2928x352 o 1584x672) se generan en 1K, y cualquier otro tamaño en píxeles se genera con el tamaño nativo 1K de la proporción más cercana (hasta un 1,5 % de diferencia); si el lado más largo supera 1536 cuenta como 2K / 4K y se rechaza al enviar. resolution solo puede ser 1K: 2K / 4K devuelve 400 unsupported_resolution al enviar, sin trabajo y sin cobro. Sin size obtienes un cuadrado 1:1.

Imagen a imagen e imágenes de referencia

  • Envía image (una imagen) o images (varias, hasta 8; si mandas más, solo se usan las 8 primeras) y el trabajo pasa a ser imagen a imagen; explica en el prompt qué quieres cambiar. POST /v1/images/edits admite los mismos parámetros.
  • Cada referencia puede ser una URL pública de imagen (http o https), un data: URI o base64 sin más, de hasta 16 MB cada una, en un formato común como JPEG, PNG o WebP.
  • La URL tiene que descargar la imagen en sí: no una página web, ni una dirección que pida iniciar sesión o bloquee el hotlinking. Una referencia que no podemos leer se rechaza al enviar con un 400 y el motivo; no se crea ningún trabajo ni se cobra nada.
  • La proporción de salida la decide size, no la referencia. Para mantener la proporción original, pon en size la de la imagen.
  • Alojamos las referencias por ti y las guardamos 7 días.
curl · Imagen a imagen con dos referencias
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2-lite", "prompt": "Keep the people, change the background to a beach at night with warm string lights", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "1K"}'

Estado del trabajo y campos

GET /v1/images/jobs/{id} siempre devuelve id, object (image.generation.job), status, created (segundos Unix) y model; los demás campos dependen del estado:

statusSignificadoCampos adicionales
queuedEn colaqueue_position (trabajos por delante del tuyo), eta_seconds (espera estimada en segundos, orientativa)
processingGenerando—
succeededListodata[].url (el enlace de la imagen; nuestro alojamiento la guarda 7 días); usage.images (imágenes entregadas), usage.resolution (nivel cobrado)
failedFallido; el importe retenido al enviar se ha reembolsado por completoerror.message, error.type, error.code

Consulta cada 2-3 segundos. Una cuenta genera hasta 50 imágenes a la vez; los demás trabajos esperan en orden de envío, y un trabajo que no ha empezado a los 15 minutos falla y se reembolsa por completo. Los registros de los trabajos se guardan 3 días; después, el id devuelve 404, pero el enlace de la imagen sigue siendo válido durante sus 7 días. Solo la cuenta que envió un trabajo puede consultarlo.

Cuánto tarda

Tiempo habitual desde el envío hasta el resultado, como referencia. Imagen a imagen tarda de unos segundos a una docena más; un trabajo que la pasarela reintenta automáticamente puede tardar 1-2 minutos.

NivelTiempo habitual
1K5–15 s

Errores y reembolsos

Todos los errores tienen la misma forma, {"error": {"message", "type", "code", "param"}}; decide según code.

Errores devueltos al enviar (no se crea ningún trabajo ni se cobra nada)

HTTPcodeCausaQué hacer
400missing_promptprompt está vacíoAñade un prompt
400model_not_foundEl id del modelo es incorrecto o no está disponible ahoraRevisa el id; /v1/models lista los disponibles
400invalid_requestNo se puede leer una imagen de referencia (enlace roto, no es una imagen, más de 16 MB...); message dice cuál y por quéUsa un enlace directo a la imagen o envíala en base64
401invalid_api_keyLa clave es incorrecta, se ha borrado o está desactivadaRevisa la clave en la consola
402insufficient_quotaNo hay saldo suficiente para retener este trabajoRecarga y vuelve a intentarlo
429rate_limit_exceededSe superó el límite por minuto fijado en esta claveReduce la frecuencia o sube el límite de la clave en la consola
503model_maintenanceEl modelo está en mantenimientoInténtalo más tarde; consulta la página de estado
503service_unavailableUn error temporal de nuestro lado (p. ej. al guardar tu referencia)Vuelve a intentarlo en un momento

Trabajos fallidos (el trabajo se aceptó y terminó con status failed; la retención se reembolsa por completo)

SituaciónQué verásQué hacer
El prompt o una referencia no pasó la revisión de seguridad de Googleerror.message como Content blockedReescribe el prompt o cambia la referencia; reenviarlo sin cambios suele volver a rechazarse
Un fallo temporal o un tiempo agotado del proveedor (antes reintentamos automáticamente y solo devolvemos el fallo si los reintentos también fallan)error.code como upstream_error o upstream_timeout, con el motivo en messageVuelve a enviarlo
El trabajo esperó 15 minutos sin empezarerror.message lo indicaVuelve a enviarlo más tarde

Usa un webhook en lugar de consultar

En producción, añade callback_url al enviar. Cuando el trabajo termine, bien o mal, enviaremos por POST a esa URL el mismo JSON que devuelve la consulta, como image.completed o image.failed, con cabeceras de firma que puedes verificar. También puedes fijar una URL para toda la cuenta en Ajustes > Webhook. Documentación de webhooks

curl · callback_url
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2-lite", "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'