# GPT Image 2.5 Sunburst — /images/generations

Generación de imágenes con GPT Image 2.5 Sunburst, la variante de estilo del modelo de imagen de nueva generación de OpenAI con más grano y pinceladas más marcadas, para imágenes que necesitan textura y presencia física. Las mismas capacidades que Flare, como trabajos asíncronos; niveles 1K / 2K / 4K y cualquier proporción; se cobra por imagen y no se cobra nada si falla.

**Endpoint:** `POST https://nezhagate.com/v1/images/generations`

## 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-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.5-sunburst"
}
```

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

## Parámetros de la petición

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

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| model | string | Sí | El ID del modelo: `gpt-image-2.5-sunburst`. |
| prompt | string | Sí | Qué dibujar. En imagen a imagen, indica qué cambiar. |
| size | string | No | Proporción, como `16:9` (recomendado), o un tamaño en píxeles, como `1536x1024`. Si no lo envías, obtienes un cuadrado 1:1. |
| resolution | string | No | Nivel: `1K` (por defecto), `2K` o `4K`. |
| quality | string | No | Nivel de detalle, solo en 1K: `low`, `medium` (por defecto) o `high`. 2K y 4K se dibujan siempre en medium, y cualquier otro valor cuenta como medium. No cambia el precio; consulta Calidad y resolución nativa más abajo. |
| image / images | string / array | No | Imágenes de referencia; si envías alguna, el trabajo pasa a ser de imagen a imagen: una en `image`, varias en `images` (hasta 8). Cada una puede ser una URL pública de imagen, un data: URI o base64. |
| n | integer | No | Número de imágenes. Mejor no enviarlo: si quieres varias imágenes, envía varios trabajos a la vez. Con `n`, se retiene de entrada el precio de n imágenes y se cobran las imágenes realmente entregadas. |
| callback_url | string | No | Adónde enviar el resultado cuando termine el trabajo; consulta la sección de webhooks más abajo. |

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.

| Nivel | Créditos por imagen | USD por imagen |
| --- | --- | --- |
| 1K | 1 | $0.005 |
| 2K | 6 | $0.03 |
| 4K | 10 | $0.05 |

## 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.

| Proporción | 1K | 2K | 4K |
| --- | --- | --- | --- |
| 1:1 | 1024x1024 | 2048x2048 | 4096x4096 |
| 3:4 | 768x1024 | 1536x2048 | 3072x4096 |
| 2:3 | 683x1024 | 1365x2048 | 2731x4096 |
| 9:16 | 576x1024 | 1152x2048 | 2304x4096 |
| 4:3 | 1024x768 | 2048x1536 | 4096x3072 |
| 3:2 | 1024x683 | 2048x1365 | 4096x2731 |
| 16:9 | 1024x576 | 2048x1152 | 4096x2304 |

- 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-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](https://nezhagate.com/es/docs/guide/async-jobs#fields). Consulta cada 2–3 segundos o usa un webhook.

| Estado | Significado |
| --- | --- |
| queued | En cola. Incluye `queue_position` (trabajos por delante del tuyo) y `eta_seconds` (espera estimada). |
| processing | Generándose. |
| succeeded | Terminado. El resultado está en `data[0].url` y el detalle del cobro en `usage`. |
| failed | Falló. El motivo está en `error`; los créditos reservados se devuelven íntegros. |

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 26 s; el 90% termina en 44 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](https://nezhagate.com/es/docs/guide/errors).

### Errores al enviar

| HTTP | code | Causa | Qué hacer |
| --- | --- | --- | --- |
| 400 | missing_prompt | La petición a `/v1/images/generations` no lleva `prompt`. | Añade un `prompt`. |
| 400 | invalid_request | No se puede leer una imagen de referencia (enlace roto, no es una imagen, supera 16MB...; `message` indica cuál y por qué), `/v1/images/edits` no lleva imagen de referencia, el cuerpo no es un objeto JSON o `n` no es un entero. | Corrige lo que indica `message` y vuelve a enviar la petición. |
| 400 | model_not_found | El ID del modelo está mal escrito, falta `model`, o el modelo no se puede usar en este endpoint (por ejemplo, un modelo de chat en el endpoint de imágenes). | Usa un ID de modelo de `GET /v1/models` o de la [referencia de la API](https://nezhagate.com/es/docs/api). |
| 401 | invalid_api_key | La clave no existe, se eliminó o está desactivada, o la cuenta está desactivada. | Revisa la clave en la página API Keys de la consola. |
| 402 | insufficient_quota | No hay saldo suficiente para retener el importe de esta petición. La pasarela retiene primero el coste máximo posible de la petición, así que una ráfaga de llamadas simultáneas también puede provocarlo. | Si se debe a una ráfaga, espera unos segundos y reintenta; si no, recarga. |
| 429 | rate_limit_exceeded | Se superó el límite de peticiones por minuto configurado en esta clave (contado sobre los últimos 60 segundos). Sin cabecera `Retry-After`. | Espera unos segundos y reintenta, o sube el límite de la clave en la consola. |
| 503 | model_maintenance | El modelo está en mantenimiento y no acepta peticiones; mientras tanto, ningún otro modelo responde en su lugar. | Reintenta cuando termine el mantenimiento; consulta el [estado del servicio](https://nezhagate.com/es/status). |
| 503 | service_unavailable | Un fallo temporal de nuestro lado, por ejemplo al guardar un archivo de referencia; `/v1/responses` también responde 503, con `Retry-After`, cuando no hay ninguna línea disponible por un momento. | Reintenta en breve. |

### Trabajos fallidos (`status` `failed`)

| code | Cuándo aparece | Qué hacer |
| --- | --- | --- |
| moderation_blocked | Imagen: el sistema de seguridad del proveedor del modelo rechazó el prompt o una imagen de referencia (el código también puede ser `content_policy_violation`). | Reescribe el prompt o cambia la referencia; si se reenvía sin cambios, normalmente se vuelve a rechazar. |
| upstream_error | Cualquier otro fallo: se probaron todas las líneas, el trabajo esperó 15 minutos sin empezar, el proveedor lo rechazó sin dar motivo, etc.; `message` indica cuál. | Volver a enviarlo suele funcionar. |

## 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 →](https://nezhagate.com/es/docs/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-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"}'
```