GPT Image 2.6 Sunburst · API

Inicio rápido

Tres pasos: envía un trabajo, consúltalo y toma el enlace de la imagen. 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/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.6-sunburst", "prompt": "Una pintura al óleo de un puerto al atardecer, pinceladas visibles, paleta cálida", "size": "16:9", "resolution": "2K"}'

Respuesta (HTTP 202)

{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "gpt-image-2.6-sunburst"
}

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 sale bien

{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "gpt-image-2.6-sunburst",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "2K", "model": "gpt-image-2.6-sunburst"}
}

Paso 3 · data[0].url es la imagen (PNG). Se guarda 15 días; descárgala en tu propio almacenamiento para conservarla 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}/images/generations", headers=HEADERS, json={
    "model": "gpt-image-2.6-sunburst",
    "prompt": "Una pintura al óleo de un puerto al atardecer, pinceladas visibles, paleta cálida",
    "size": "16:9",
    "resolution": "2K",
}).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("gpt-image-2.6-sunburst.png", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["code"], job["error"]["message"])

Autenticación

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Crea una clave API en la consola para empezar.

Parámetros de la petición

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

background puede ser transparent (combínalo con salida PNG o WebP); output_format puede ser png (por defecto), jpeg o webp, y el archivo entregado tiene ese formato. n debe ser 1: para varias imágenes envía varios trabajos a la vez. Otros parámetros (response_format, style y similares) no cambian el precio ni se garantiza que tengan efecto; el resultado llega como url.

Precio

Se cobra por imagen, solo según el nivel: la proporción y que sea texto a imagen o imagen a imagen no cambian nada. El precio del nivel se retiene al enviar y se reembolsa íntegro si el trabajo falla. 1 crédito = $0.005.

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

Pon la relación de aspecto en size y el nivel en resolution. Recibes la imagen original tal como se genera, sin recortes ni redimensionado, en los tamaños de abajo: ambos lados son múltiplos de 16 y 4K no pasa de 3840 px por lado ni de unos 8,3 megapíxeles.

• Solo están disponibles las 7 relaciones de la tabla; cualquier otra se rechaza al enviar con un 400 y no se cobra nada. En 1K, 16:9 y 9:16 quedarían por debajo del mínimo de píxeles del modelo, así que salen a 1088×608 y 608×1088.
• size también puede ser un tamaño en píxeles (p. ej. 1536x1024) en una de las 7 relaciones: ambos lados se redondean hacia abajo a múltiplos de 16, se reducen si superan el límite del nivel y se amplían hasta el mínimo del modelo (unos 655.000 píxeles) si son demasiado pequeños. El nivel lo marca resolution; sin él decide el lado mayor: hasta 1536 es 1K, hasta 2048 es 2K y más es 4K. Lado mayor permitido: 512–1536 en 1K, 2048–2304 en 2K y 2049–4096 en 4K; lo demás se rechaza al enviar con un 400 y no se cobra nada.

Calidad y resolución nativa

• Sin quality la imagen se genera en medium. low, medium y high funcionan en 1K, 2K y 4K, tanto en texto a imagen como en imagen a imagen, y el precio solo depende del nivel de resolución; auto cuenta como medium. xhigh y max aún no están disponibles: se rechazan al enviar con un 400 y no se cobra nada.
• Si quality contiene 1K, 2K o 4K y no envías resolution, se toma como nivel de resolución (el tamaño y el precio siguen ese nivel).
• Los niveles que se dibujan de forma nativa siempre se dibujan de forma nativa: si hay mucha carga, el trabajo espera en la cola, y si aun así no puede dibujarse, falla con reembolso completo; nunca se sustituye por una imagen 1K ampliada.

Imagen a imagen e imágenes de referencia

• Envía image (una imagen) o images (varias, hasta 5) y el trabajo será imagen a imagen; indica en el prompt qué cambiar. Más de 5 se rechaza al enviar con un 400 y no se cobra nada. POST /v1/images/edits acepta los mismos parámetros.
• Los dos endpoints solo aceptan un cuerpo JSON, no la subida de archivos multipart, así que images.edit() del SDK de OpenAI no se puede usar tal cual: pasa enlaces o base64 como en el ejemplo de abajo.
• Cada referencia puede ser una URL pública de imagen (http o https), un data: URI o base64 simple, de hasta 16MB cada una, en PNG o JPEG; una referencia en otro formato hace que el trabajo falle con reembolso completo.
• La URL tiene que descargar directamente la imagen: no puede ser una página web ni estar detrás de un inicio de sesión o de una protección contra hotlinking. Una referencia que no podemos leer se rechaza al enviar con un 400 que indica cuál es y por qué; no se crea ningún trabajo y no se cobra nada.
• La proporción de salida la marca size, no la referencia. Para mantener la proporción original, pon esa proporción en size.
• Alojamos las referencias por ti y las guardamos 7 días.

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": "gpt-image-2.6-sunburst", "prompt": "Mantén a las personas y cambia el fondo por una playa de noche con guirnaldas de luces cálidas", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "2K"}'

Estado y campos del trabajo

GET /v1/images/jobs/{id} devuelve estos estados; cada campo se describe en Trabajos asíncronos. Consulta cada 2–3 segundos o usa un webhook.

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 las imágenes, 15 días.

Cuánto tarda

Normalmente 20–60 segundos desde el envío hasta el resultado; 4K, las ediciones con varias referencias y los momentos de mucha carga tardan más, y algún trabajo puede tardar uno o dos minutos.

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)

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/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.6-sunburst", "prompt": "Una pintura al óleo de un puerto al atardecer, pinceladas visibles, paleta cálida", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'