GPT Image 2.6 Sunburst · Token · 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-token", "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-token"
}

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-token",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "2K", "model": "gpt-image-2.6-sunburst-token"}
}

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-token",
    "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-token.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 (úsalo con salida PNG o WebP); output_format es png (por defecto), jpeg o webp. n debe ser 1. Un parámetro que no esté en la tabla devuelve 400 unsupported_image_parameter al enviar y no se cobra nada; el resultado llega como url y usage incluye los tokens y el cargo del trabajo.

Cobro por tokens

Al enviar se retiene un máximo según el tamaño, la calidad y el número de referencias; al terminar, el trabajo se liquida con el uso que informa OpenAI y el resto de la retención se devuelve al momento; un fallo se reembolsa por completo. Precios por 1M tokens:

Tokens de salida medidos y coste (sin entrada)

Con el mismo tamaño y calidad, los tokens de salida son siempre los mismos, sea cual sea el prompt; cada referencia añade unos 700-1.600 tokens de entrada de imagen.

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.

• Se admiten las 15 proporciones de la tabla; cualquier otra devuelve 400 al enviar y no se cobra nada. Con size en auto y una imagen de referencia, la imagen sigue la proporción más cercana a la primera referencia; sin referencia es 1:1. Algunas proporciones largas y estrechas en 1K quedan por debajo del mínimo de píxeles del modelo y se generan con los tamaños ampliados de la tabla (16:9 es 1088×608).
• size también puede ser un tamaño en píxeles (p. ej. 1536x1024) en una de las 15 proporciones: ancho y alto 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, el lado largo: hasta 1536 es 1K, hasta 2048 es 2K, más es 4K. Rangos del lado largo: 1K 512-1536, 2K 2016-2304, 4K 2049-4096; fuera de ellos la solicitud devuelve 400 al enviar y no se cobra nada.

Calidad y resolución nativa

• Sin quality la imagen se genera en medium. La calidad solo cambia los tokens y el precio, nunca el tamaño; con auto decide el modelo, la retención supone max y el trabajo se liquida con el uso real.
• 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).
• En horas de mucha demanda los trabajos esperan en cola en lugar de fallar al momento; si tras una espera larga (unos 15 minutos) no hay imagen, el trabajo falla y se reembolsa por completo, y puedes reenviarlo tal cual.

Imagen a imagen e imágenes de referencia

• Envía image (una) o images (varias, hasta 16; las que pasen de ahí no se usan) para imagen a imagen, y di en el prompt qué cambiar. 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 un enlace público (http / https), un data: URI o base64, de hasta 16 MB, en PNG, JPEG o WebP; una referencia en otro formato hace fallar el trabajo y la retención se reembolsa por 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-token", "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-token", "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"}'