GPT Image 2.5 | API Belgeleri

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

Hızlı görsel oluşturmak için gpt-image-2.5-flare, hassas düzenleme için gpt-image-2.5-sunburst kullanın. Anahtarınızın erişimini GET https://api.apihop.ai/v1/models ile kontrol edin.

İstek

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
}

Parametre	Değerler
`model`	Zorunlu: `gpt-image-2.5-flare` veya `gpt-image-2.5-sunburst`
`prompt`	Görseli veya düzenlemeyi açıklayan zorunlu metin
`n`	1 ile 4 arasında tam sayı; varsayılan 1
`size`	`auto`, en boy oranı veya `1600x1200` gibi piksel boyutları
`resolution`	`1k` (varsayılan), `2k`, `4k`; kesin piksel boyutlarında yok sayılır
`quality`	`low`, `medium`, `high`, `xhigh`, `max`, `auto` (varsayılan)
`image_urls`	Herkese açık en fazla 16 HTTP(S) görsel URL’si
`output_format`	`png` (varsayılan), `jpeg`, `webp`
`output_compression`	JPEG veya WebP için 0 ile 100 arasında tam sayı
`background`	`auto`, `opaque`, `transparent`; şeffaflık PNG veya WebP gerektirir
`moderation`	`low` (varsayılan), `auto`
`stream`	JSON için `false` (varsayılan), SSE tamamlanma olayları için `true`

Desteklenen oranlar: 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. Kesin piksel boyutları 16’nın katı olmalı, hiçbir kenar 3840 pikseli, en boy oranı 3:1’i aşmamalı ve toplam piksel sayısı 655,360 ile 8,294,400 arasında olmalıdır. Örneğin kare 4k çıktı 2880x2880’dir, 4096x4096 değildir.

Referans görseller

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

Referanslar aynı JSON oluşturma uç noktasını kullanır. Yerel görselleri önce kendi depolamanıza yükleyin. Base64 veri URI’leri, multipart yüklemeler, maskeler ve ayrı bir /images/edits uç noktası bu modelin genel sözleşmesine dahil değildir.

Yanıt

HTTP bağlantısı tamamlanmayı bekler; istemciler üst sağlayıcının görevini sorgulamaz. JSON yanıtları nihai görsel URL’lerini ve mevcut token kullanımını içerir:

json

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

stream: true için aynı bağlantıda image_generation.completed ve [DONE] olaylarını bekleyin. Kısmi görsel önizlemeleri garanti edilmez.

Fiyatlandırma

Faturalandırma gerçek metin girdisi, önbelleğe alınmış metin girdisi, görsel girdisi, önbelleğe alınmış görsel girdisi ve görsel çıktısı tokenlarını kullanır. İki varyantın token fiyatları aynıdır. Model kataloğu geçerli fiyatınızı ve ayrı olarak OpenAI referans fiyatını gösterir. Bir görsel sabit fiyatlı bir birim değildir; istem uzunluğu, referanslar, boyut, kalite ve adet toplamı etkiler. Geçici rezervasyon tamamlanmadan sonra uzlaştırılır. Kaliteyi açıkça belirtmek beklenen kullanımı netleştirir.

Geçersiz parametreler 400, kimlik doğrulama hataları 401, yetersiz bakiye 402 döndürür. Kullanılamayan model 404, hız sınırları 429, oluşturma hataları 5xx döndürür. Tamamlanma durumu bilinmeyen bir isteği otomatik olarak yeniden göndermeyin.

Hata kodları, akış hataları ve yeniden deneme sınırları için Hata kodları ve sorun giderme sayfasına bakın.