GPT Image 2.5 | Documentazione 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 per generare immagini rapidamente o gpt-image-2.5-sunburst per modifiche precise. Controlla la disponibilità per la tua chiave tramite GET https://api.apihop.ai/v1/models.

Richiesta

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
}

Parametro	Valori
`model`	Obbligatorio: `gpt-image-2.5-flare` o `gpt-image-2.5-sunburst`
`prompt`	Testo obbligatorio che descrive l’immagine o la modifica
`n`	Intero da 1 a 4; valore predefinito 1
`size`	`auto`, proporzioni o dimensioni in pixel come `1600x1200`
`resolution`	`1k` (predefinito), `2k`, `4k`; ignorato con dimensioni esatte in pixel
`quality`	`low`, `medium`, `high`, `xhigh`, `max`, `auto` (predefinito)
`image_urls`	Fino a 16 URL di immagini HTTP(S) pubblicamente accessibili
`output_format`	`png` (predefinito), `jpeg`, `webp`
`output_compression`	Intero da 0 a 100 per JPEG o WebP
`background`	`auto`, `opaque`, `transparent`; la trasparenza richiede PNG o WebP
`moderation`	`low` (predefinito), `auto`
`stream`	`false` (predefinito) per JSON, `true` per eventi di completamento SSE

Proporzioni supportate: 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. Le dimensioni esatte in pixel devono essere multipli di 16, con nessun lato superiore a 3840 pixel, proporzioni non superiori a 3:1 e un totale da 655,360 a 8,294,400 pixel. Per esempio, l’output quadrato 4k è 2880x2880, non 4096x4096.

Immagini di riferimento

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"
}

I riferimenti usano questo stesso endpoint di generazione JSON. Carica prima le immagini locali nel tuo spazio di archiviazione. URI dati Base64, caricamenti multipart, maschere e un endpoint separato /images/edits non fanno parte del contratto pubblico di questo modello.

Risposta

La connessione HTTP attende il completamento; i client non interrogano un processo a monte. Le risposte JSON contengono gli URL finali delle immagini e l’utilizzo dei token disponibile:

json

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

Con stream: true, attendi image_generation.completed e [DONE] sulla stessa connessione. Le anteprime parziali delle immagini non sono garantite.

Prezzi

La fatturazione usa i token effettivi di input testuale, input testuale in cache, input immagine, input immagine in cache e output immagine. Le due varianti condividono gli stessi prezzi dei token. Il catalogo mostra il tuo prezzo corrente e, separatamente, il prezzo di riferimento OpenAI. Un’immagine non è un’unità a prezzo fisso: lunghezza del prompt, riferimenti, dimensioni, qualità e quantità influiscono sul totale. Una prenotazione temporanea viene riconciliata dopo il completamento. Una qualità esplicita rende più chiaro il consumo previsto.

Parametri non validi restituiscono 400, errori di autenticazione 401 e credito insufficiente 402. Un modello non disponibile restituisce 404, i limiti di frequenza 429 e gli errori di generazione 5xx. Non reinviare automaticamente una richiesta il cui completamento è incerto.

Per codici di errore, errori di streaming e limiti dei tentativi, consulta Codici di errore e risoluzione dei problemi.