GPT Image 2.5 | Documentación de API

# GPT Image 2.5

Generate images with Flare or edit reference images with Sunburst.

POST https://api.apihop.ai/openai/v1/images/generations

Use `gpt-image-2.5-flare` for fast image generation or `gpt-image-2.5-sunburst` for precise editing. Check `GET https://api.apihop.ai/v1/models` for availability with your API key.

## Request

```http
POST https://api.apihop.ai/openai/v1/images/generations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

```json
{
  "model": "gpt-image-2.5-flare",
  "prompt": "A red ceramic cup on a white table.",
  "size": "1:1",
  "resolution": "1k",
  "quality": "low",
  "n": 1
}
```

| Parameter | Values |
| --- | --- |
| `model` | Required: `gpt-image-2.5-flare` or `gpt-image-2.5-sunburst` |
| `prompt` | Required text describing the image or edit |
| `n` | Integer from 1 to 4; default 1 |
| `size` | `auto`, aspect ratio, or pixel dimensions such as `1600x1200` |
| `resolution` | `1k` (default), `2k`, `4k`; ignored for exact pixel sizes |
| `quality` | `low`, `medium`, `high`, `xhigh`, `max`, `auto` (default) |
| `image_urls` | Up to 16 publicly accessible HTTP(S) image URLs |
| `output_format` | `png` (default), `jpeg`, `webp` |
| `output_compression` | Integer from 0 to 100 for JPEG or WebP |
| `background` | `auto`, `opaque`, `transparent`; transparent requires PNG or WebP |
| `moderation` | `low` (default), `auto` |
| `stream` | `false` (default) for JSON, `true` for SSE completion events |

Supported aspect ratios: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `5:4`, `4:5`, `16:9`, `9:16`, `2:1`, `1:2`, `21:9`, `9:21`, `3:1`, `1:3`. Exact pixel dimensions must be multiples of 16, have no side above 3840 pixels, an aspect ratio at most 3:1, and 655,360 to 8,294,400 total pixels. For example, square `4k` output is 2880x2880, not 4096x4096.

## Reference Images

```json
{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "Keep the product and its lettering. Replace the background with a white studio.",
  "image_urls": ["https://example.com/product.png"],
  "resolution": "2k",
  "quality": "xhigh"
}
```

References use this JSON generation endpoint. Upload local images to your own storage first. Base64 data URIs, multipart uploads, masks, and a separate `/images/edits` endpoint are outside this model's public contract.

## Response

The HTTP connection waits for completion; clients do not poll an upstream task. JSON responses include final image URLs and available token usage:

```json
{
  "created": 1789035000,
  "data": [{"url": "https://example.com/generated-image.png"}],
  "usage": {"input_tokens": 15, "output_tokens": 196, "total_tokens": 211}
}
```

With `stream: true`, wait for `image_generation.completed` and `[DONE]` on the same connection. Partial image previews are not guaranteed.

## Pricing

Billing uses actual text input, cached text input, image input, cached image input, and image output tokens. Both variants have the same token prices. The model catalog shows your current price and the separate OpenAI reference price. An image is not a fixed-price unit: prompt length, references, size, quality, and count affect the total. A temporary reservation is reconciled after completion. Choosing an explicit quality makes expected usage clearer.

Invalid parameters return 400; authentication failures return 401; insufficient balance returns 402. An unavailable model returns 404, rate limits return 429, and generation failures return 5xx. Do not automatically resubmit a request whose completion status is unknown.

See [Error Codes and Troubleshooting](https://apihop.ai/en/docs/api-reference/errors) for error codes, streaming failures, and retry boundaries.

Usa gpt-image-2.5-flare para generar imágenes rápidamente o gpt-image-2.5-sunburst para una edición precisa. Consulta GET https://api.apihop.ai/v1/models para verificar la disponibilidad con tu clave de API.

Solicitud

http

POST https://api.apihop.ai/openai/v1/images/generations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

json

{
  "model": "gpt-image-2.5-flare",
  "prompt": "A red ceramic cup on a white table.",
  "size": "1:1",
  "resolution": "1k",
  "quality": "low",
  "n": 1
}

Parámetro	Valores
`model`	Obligatorio: `gpt-image-2.5-flare` o `gpt-image-2.5-sunburst`
`prompt`	Texto obligatorio que describe la imagen o edición
`n`	Entero de 1 a 4; predeterminado 1
`size`	`auto`, relación de aspecto o dimensiones en píxeles como `1600x1200`
`resolution`	`1k` (predeterminado), `2k`, `4k`; se ignora con tamaños exactos en píxeles
`quality`	`low`, `medium`, `high`, `xhigh`, `max`, `auto` (predeterminado)
`image_urls`	Hasta 16 URL HTTP(S) de imágenes accesibles públicamente
`output_format`	`png` (predeterminado), `jpeg`, `webp`
`output_compression`	Entero de 0 a 100 para JPEG o WebP
`background`	`auto`, `opaque`, `transparent`; la transparencia requiere PNG o WebP
`moderation`	`low` (predeterminado), `auto`
`stream`	`false` (predeterminado) para JSON, `true` para eventos SSE de finalización

Relaciones de aspecto admitidas: 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 2:1, 1:2, 21:9, 9:21, 3:1, 1:3. Las dimensiones exactas deben ser múltiplos de 16, sin ningún lado superior a 3840 píxeles, con una relación de aspecto máxima de 3:1 y de 655,360 a 8,294,400 píxeles totales. Por ejemplo, una salida cuadrada 4k es de 2880x2880, no de 4096x4096.

Imágenes de referencia

json

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "Keep the product and its lettering. Replace the background with a white studio.",
  "image_urls": ["https://example.com/product.png"],
  "resolution": "2k",
  "quality": "xhigh"
}

Las referencias usan este endpoint JSON de generación. Sube primero las imágenes locales a tu propio almacenamiento. Los URI de datos Base64, las subidas multipart, las máscaras y un endpoint separado /images/edits quedan fuera del contrato público de este modelo.

Respuesta

La conexión HTTP espera hasta la finalización; los clientes no consultan una tarea del proveedor. Las respuestas JSON incluyen las URL finales de imágenes y el uso de tokens disponible:

json

{
  "created": 1789035000,
  "data": [{"url": "https://example.com/generated-image.png"}],
  "usage": {"input_tokens": 15, "output_tokens": 196, "total_tokens": 211}
}

Con stream: true, espera image_generation.completed y [DONE] en la misma conexión. No se garantizan vistas previas parciales de imágenes.

Precios

La facturación usa los tokens reales de entrada de texto, texto en caché, entrada de imagen, imagen en caché y salida de imagen. Ambas variantes tienen los mismos precios por token. El catálogo muestra tu precio actual y, por separado, el precio de referencia de OpenAI. Una imagen no es una unidad de precio fijo: la longitud de la instrucción, referencias, tamaño, calidad y cantidad afectan al total. Una reserva temporal se concilia tras la finalización. Elegir explícitamente una calidad aclara el uso esperado.

Los parámetros no válidos devuelven 400; los fallos de autenticación, 401; el saldo insuficiente, 402. Un modelo no disponible devuelve 404, los límites de velocidad devuelven 429 y los fallos de generación, 5xx. No reenvíes automáticamente una solicitud cuyo estado de finalización se desconoce.

Consulta Códigos de error y resolución de problemas para códigos de error, fallos de streaming y límites de los reintentos.