GPT Image 2.5 Flare · 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://nezhagate.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.5-flare", "prompt": "Una foto de producto minimalista de una taza de cerámica blanca sobre un fondo claro, luz lateral suave", "size": "16:9", "resolution": "2K"}'

Respuesta (HTTP 202)

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

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

curl https://nezhagate.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.5-flare",
  "data": [
    {"url": "https://img.nezhagate.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "2K", "model": "gpt-image-2.5-flare"}
}

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://nezhagate.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.5-flare",
    "prompt": "Una foto de producto minimalista de una taza de cerámica blanca sobre un fondo claro, luz lateral suave",
    "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.5-flare.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:

Los demás parámetros de OpenAI (background, output_format, response_format, style y similares) no cambian el precio y no se garantiza que tengan efecto; los resultados siempre son PNG y se devuelven 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 proporción en size y el nivel en resolution. La imagen se entrega exactamente con el tamaño de la tabla: el nivel fija el lado más largo y el otro lado se ajusta a la proporción. Las proporciones que no están en la tabla funcionan igual.

• En 1K el modelo compone la imagen en el formato horizontal, vertical o cuadrado más cercano, y luego la pasarela la recorta al centro y la redimensiona al tamaño de la tabla; cuanto más se aleja una proporción de 3:2, 2:3 o 1:1, más se recortan los bordes. La pasarela añade a tu prompt una frase sobre la proporción (en inglés) para que el sujeto quede completo y centrado; mantén lejos de los bordes todo lo que no deba perderse.
• Los niveles que se dibujan de forma nativa (consulta Calidad y resolución nativa más abajo) se dibujan en tu proporción, así que no se recorta nada de los bordes.
• size también puede ser un tamaño en píxeles (por ejemplo, 1536x1024): la imagen se entrega exactamente con ese tamaño (reducida si el lado más largo supera 4096). El nivel lo marca entonces resolution o, si no lo envías, el lado más largo: hasta 1536 es 1K, hasta 2048 es 2K, y por encima es 4K. resolution puede subir el nivel, pero nunca bajarlo, y no cambia el tamaño entregado, así que no combines un tamaño pequeño con un nivel alto.

Calidad y resolución nativa

• Sin quality, la imagen se dibuja con el nivel de detalle medium de OpenAI. En 1K puedes elegir low, medium o high, tanto en texto a imagen como en imagen a imagen; 2K y 4K se dibujan siempre en medium. Cualquier otro valor (auto, xhigh, max, etc.) cuenta como medium y nunca provoca un error. El precio depende solo del nivel de resolución, nunca de quality.
• 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).
• 1K se dibuja en el encuadre nativo del modelo, de unos 1,57 megapíxeles (1254×1254 en cuadrado), y la pasarela lo redimensiona al tamaño de la tabla de arriba.
• 2K y 4K se dibujan de forma nativa en la proporción que pidas, hasta 3840 px por lado y unos 8,3 megapíxeles: 2K 1:1 llega como 2048×2048, 4K 16:9 como 3840×2160 y 4K 1:1 como 2880×2880. Cuando el tamaño 4K de la tabla es mayor, la pasarela amplía la imagen hasta él (un 7 % por lado en 16:9, más cuanto más cuadrada sea la proporción); para recibir los píxeles nativos tal cual, envía en size un tamaño en píxeles dentro de esos límites, por ejemplo 3840x2160.
• Los niveles que se dibujan de forma nativa solo se ejecutan en sus líneas nativas: si están ocupadas, 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.
• Un trabajo 1K se completa a veces en una línea de respaldo, donde quality puede no tener efecto.

Imagen a imagen e imágenes de referencia

• Envía image (una imagen) o images (varias, hasta 8; las que pasen de 8 no se usan) y el trabajo será de imagen a imagen; indica 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 una URL pública de imagen (http o https), un data: URI o base64 puro, de hasta 16MB cada una, en un formato habitual como JPEG, PNG o WebP.
• 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://nezhagate.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.5-flare", "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

Desde el envío hasta el resultado, 1K suele tardar 20–60 segundos; 2K y 4K se dibujan de forma nativa y suelen tardar 30–120 segundos. Imagen a imagen y varias referencias tardan más, y un trabajo que la pasarela reintenta en otra línea puede tardar unos minutos.

Llamadas reales de los últimos 7 días: mediana 25 s; el 90% termina en 40 s o menos.

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://nezhagate.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.5-flare", "prompt": "Una foto de producto minimalista de una taza de cerámica blanca sobre un fondo claro, luz lateral suave", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'