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

Gunakan gpt-image-2.5-flare untuk pembuatan gambar cepat atau gpt-image-2.5-sunburst untuk penyuntingan presisi. Periksa GET https://api.apihop.ai/v1/models untuk ketersediaan dengan API key Anda.

Permintaan

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	Nilai
`model`	Wajib: `gpt-image-2.5-flare` atau `gpt-image-2.5-sunburst`
`prompt`	Teks wajib yang menjelaskan gambar atau penyuntingan
`n`	Bilangan bulat dari 1 hingga 4; bawaan 1
`size`	`auto`, rasio aspek, atau dimensi piksel seperti `1600x1200`
`resolution`	`1k` (bawaan), `2k`, `4k`; diabaikan untuk ukuran piksel yang persis
`quality`	`low`, `medium`, `high`, `xhigh`, `max`, `auto` (bawaan)
`image_urls`	Hingga 16 URL gambar HTTP(S) yang dapat diakses publik
`output_format`	`png` (bawaan), `jpeg`, `webp`
`output_compression`	Bilangan bulat dari 0 hingga 100 untuk JPEG atau WebP
`background`	`auto`, `opaque`, `transparent`; transparan memerlukan PNG atau WebP
`moderation`	`low` (bawaan), `auto`
`stream`	`false` (bawaan) untuk JSON, `true` untuk peristiwa penyelesaian SSE

Rasio aspek yang didukung: 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. Dimensi piksel yang persis harus kelipatan 16, tidak memiliki sisi di atas 3840 piksel, memiliki rasio aspek maksimal 3:1, dan total 655,360 hingga 8,294,400 piksel. Contohnya, keluaran persegi 4k adalah 2880x2880, bukan 4096x4096.

Gambar Referensi

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

Referensi menggunakan endpoint pembuatan JSON ini. Unggah gambar lokal ke penyimpanan Anda sendiri terlebih dahulu. URI data Base64, unggahan multipart, mask, dan endpoint /images/edits terpisah berada di luar kontrak publik model ini.

Respons

Koneksi HTTP menunggu hingga selesai; klien tidak melakukan polling tugas upstream. Respons JSON mencakup URL gambar akhir dan penggunaan token yang tersedia:

json

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

Dengan stream: true, tunggu image_generation.completed dan [DONE] pada koneksi yang sama. Pratinjau gambar parsial tidak dijamin.

Harga

Penagihan menggunakan token aktual masukan teks, masukan teks dalam cache, masukan gambar, masukan gambar dalam cache, dan keluaran gambar. Kedua varian memiliki harga token yang sama. Katalog model menampilkan harga Anda saat ini dan harga referensi OpenAI secara terpisah. Gambar bukan unit harga tetap: panjang prompt, referensi, ukuran, kualitas, dan jumlah memengaruhi total. Reservasi sementara direkonsiliasi setelah selesai. Memilih kualitas secara eksplisit membuat perkiraan penggunaan lebih jelas.

Parameter tidak valid mengembalikan 400; kegagalan autentikasi mengembalikan 401; saldo tidak cukup mengembalikan 402. Model yang tidak tersedia mengembalikan 404, batas laju mengembalikan 429, dan kegagalan pembuatan mengembalikan 5xx. Jangan otomatis mengirim ulang permintaan yang status penyelesaiannya tidak diketahui.

Lihat Kode Kesalahan dan Pemecahan Masalah untuk kode kesalahan, kegagalan streaming, dan batas percobaan ulang.