GPT Image 2.5 | Dokumentacja 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.

Używaj gpt-image-2.5-flare do szybkiego generowania obrazów lub gpt-image-2.5-sunburst do precyzyjnej edycji. Sprawdź dostępność dla swojego klucza API przez GET https://api.apihop.ai/v1/models.

Żądanie

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
}

Parametr	Wartości
`model`	Wymagane: `gpt-image-2.5-flare` lub `gpt-image-2.5-sunburst`
`prompt`	Wymagany tekst opisujący obraz lub edycję
`n`	Liczba całkowita od 1 do 4; domyślnie 1
`size`	`auto`, proporcje lub wymiary w pikselach, na przykład `1600x1200`
`resolution`	`1k` (domyślnie), `2k`, `4k`; ignorowane przy dokładnych wymiarach w pikselach
`quality`	`low`, `medium`, `high`, `xhigh`, `max`, `auto` (domyślnie)
`image_urls`	Do 16 publicznie dostępnych adresów URL obrazów HTTP(S)
`output_format`	`png` (domyślnie), `jpeg`, `webp`
`output_compression`	Liczba całkowita od 0 do 100 dla JPEG lub WebP
`background`	`auto`, `opaque`, `transparent`; przezroczystość wymaga PNG lub WebP
`moderation`	`low` (domyślnie), `auto`
`stream`	`false` (domyślnie) dla JSON, `true` dla zdarzeń zakończenia SSE

Obsługiwane proporcje: 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. Dokładne wymiary w pikselach muszą być wielokrotnościami 16, żaden bok nie może przekraczać 3840 pikseli, proporcje nie mogą przekraczać 3:1, a łączna liczba pikseli musi wynosić od 655,360 do 8,294,400. Na przykład kwadratowy wynik 4k ma 2880x2880, a nie 4096x4096.

Obrazy referencyjne

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

Referencje używają tego punktu końcowego generowania JSON. Najpierw prześlij lokalne obrazy do własnej przestrzeni dyskowej. Identyfikatory URI danych Base64, przesyłanie multipart, maski i oddzielny punkt końcowy /images/edits nie należą do publicznego kontraktu tego modelu.

Odpowiedź

Połączenie HTTP czeka na zakończenie; klienty nie odpytują zadania dostawcy. Odpowiedzi JSON zawierają końcowe adresy URL obrazów i dostępne informacje o zużyciu tokenów:

json

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

Przy stream: true czekaj na image_generation.completed i [DONE] w tym samym połączeniu. Częściowe podglądy obrazów nie są gwarantowane.

Ceny

Rozliczenie wykorzystuje rzeczywiste tokeny wejścia tekstowego, buforowanego wejścia tekstowego, wejścia obrazowego, buforowanego wejścia obrazowego i wyjścia obrazowego. Oba warianty mają takie same ceny tokenów. Katalog modeli pokazuje Twoją aktualną cenę i oddzielną cenę referencyjną OpenAI. Obraz nie jest jednostką o stałej cenie: długość promptu, referencje, rozmiar, jakość i liczba obrazów wpływają na sumę. Tymczasowa rezerwacja jest rozliczana po zakończeniu. Jawny wybór jakości ułatwia przewidzenie zużycia.

Nieprawidłowe parametry zwracają 400; błędy uwierzytelniania zwracają 401; niewystarczające saldo zwraca 402. Niedostępny model zwraca 404, limity częstotliwości zwracają 429, a błędy generowania zwracają 5xx. Nie wysyłaj automatycznie ponownie żądania, którego stan zakończenia jest nieznany.

Zobacz kody błędów i diagnozowanie, aby poznać kody błędów, awarie strumieniowania i granice ponawiania.