GPT-Image-2 görsel oluşturma | API Belgeleri

# GPT-Image-2 Image Generation

Generate images or edit reference images with gpt-image-2 and receive results in the current JSON response or SSE connection.

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

`gpt-image-2` supports image generation and reference-image editing for product images, poster drafts, illustrations, social assets, high-resolution visuals, style transfer, and multi-reference fusion.

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

## Authentication

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Quick Start

```json
{
  "model": "gpt-image-2",
  "prompt": "A minimal black wireless earbud product poster on a white background, clean studio lighting, no text",
  "n": 1,
  "size": "2048x1152",
  "resolution": "2k",
  "quality": "low"
}
```

## Pricing comparison scope

RequestBeam's published **1K / 2K / 4K** image tiers are *RequestBeam selling prices*, not official fixed per-image OpenAI rates. The [OpenAI pricing documentation](https://developers.openai.com/api/docs/pricing) describes image/text-token and processing-tier charges; realized cost depends on size, quality, reference inputs, and output. Comparing the two merely because both mention `1k` or `2k` is not a like-for-like discount calculation.

To avoid an unsupported savings claim, the old aggregate-provider `USD per image` reference and discount badge are intentionally hidden for GPT Image 2. The RequestBeam price remains visible and its billing contract is unchanged. For a defensible future comparison, record the exact model, endpoint, image quality, size, input conditions, official source URL, and the date the reference was verified. Check your account's effective price before making a paid call.

## Body

### `model` (string, required, Default: gpt-image-2)

Image model ID. Use `gpt-image-2`.

### `prompt` (string, required)

Image prompt. Describe the subject, scene, composition, style, material, lighting, colors, and whether text should appear.

### `n` (integer, Default: 1)

Number of images to generate. The current `gpt-image-2` public contract only supports `1`. Other values return `400` before reservation.

### `size` (string, Default: auto)

Output aspect ratio or pixel dimensions.

Common values:

- `1:1`
- `4:3`
- `16:9`
- `9:16`
- `1024x1024`
- `1536x1024`
- `1024x1536`
- `2048x2048`
- `2048x1152`
- `3840x2160`
- `2160x3840`
- `auto`

### `quality` (string, Default: auto)

Output quality. Supported values include `low`, `medium`, `high`, and `auto`.

### `resolution` (string, Default: 1k)

Output resolution tier. Supported values are `1k`, `2k`, and `4k`.

It can be combined with `size`, for example `size: "16:9"` and `resolution: "2k"`.

### `image_urls` (array<string>)

Reference images used for instruction-based editing or multi-image fusion.

- Up to 16 images.
- Each image can be up to 20 MB, with a 256 MB total input limit.
- Publicly accessible image URLs are supported.
- Base64 data URIs such as `data:image/...;base64,...` are supported.
- URLs and base64 data URIs can be mixed in the same array.

### `output_format` (string, Default: png)

Output format. Supported values include `png`, `jpeg`, and `webp`.

### `stream` (boolean, Default: false)

Whether to return Server-Sent Events.

## Reference Images And Editing

Reference-image editing uses the same JSON endpoint. Add `image_urls` and describe what to preserve and change in `prompt`:

```json
{
  "model": "gpt-image-2",
  "prompt": "Keep the product unchanged, replace the background with a dark blue studio, and add soft rim lighting",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "size": "1:1",
  "resolution": "2k"
}
```

Multiple references can provide the subject, composition, or visual style:

```json
{
  "model": "gpt-image-2",
  "prompt": "Use the product from the first image and the composition from the second image to create a clean ecommerce hero image",
  "image_urls": [
    "https://example.com/product.png",
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  ],
  "size": "4:3",
  "resolution": "2k"
}
```

Current public contract boundaries:

- Whole-image editing, style transfer, and multi-reference fusion are supported through `image_urls`.
- There is no separate `POST https://api.apihop.ai/openai/v1/images/edits` route.
- `multipart/form-data` uploads are not accepted. Convert local images to base64 data URIs or upload them to accessible URLs first.
- Mask-based inpainting is unsupported. Sending `mask`, `mask_url`, or `maskUrl` returns `400` before reservation.

## Request Examples

### 1:1 Product Image

```json
{
  "model": "gpt-image-2",
  "prompt": "A transparent glass cup on a light gray background, commercial product photography, soft shadow, no text",
  "n": 1,
  "size": "1024x1024",
  "resolution": "1k",
  "quality": "low",
  "output_format": "png"
}
```

### 16:9 Poster

```json
{
  "model": "gpt-image-2",
  "prompt": "A futuristic city night poster with neon lights, wet streets, cinematic composition, no text",
  "n": 1,
  "size": "2048x1152",
  "resolution": "2k",
  "quality": "medium",
  "output_format": "jpeg"
}
```

## How Results Are Returned

This OpenAI-compatible endpoint does not first return a task submission response containing `data.jobId` for later polling:

- With `stream: false`, the current HTTP request waits for completion and

returns image URLs in the JSON response.

- With `stream: true`, the current SSE connection remains open through

`image_generation.completed` and `[DONE]`.

Do not use `GET https://api.apihop.ai/v1/jobs/{id}` to retrieve results from this endpoint. Use [Get Async Job](https://apihop.ai/en/docs/api-reference/jobs) only when an asynchronous creation endpoint explicitly returns a `jobId`.

## Non-Streaming Response

The response contains image URLs. `usage` is included when the upstream route provides metering information.

```json
{
  "created": 1777270000,
  "data": [
    {
      "url": "https://image.example.com/generated/123456789012345678/0.png"
    }
  ],
  "usage": {
    "input_tokens": 20,
    "output_tokens": 1234,
    "total_tokens": 1254
  }
}
```

## Streaming Response

```text
event: image_generation.completed
data: {"type":"image_generation.completed","data":[{"index":0,"url":"https://image.example.com/generated/123456789012345678/0.png"}],"usage":{"input_tokens":20,"output_tokens":1234,"total_tokens":1254}}

data: [DONE]
```

## Size Reference

| Target Ratio | 1K Recommended | 2K Recommended | 4K Recommended |
| --- | --- | --- | --- |
| `1:1` | `1024x1024` | `2048x2048` | Not recommended |
| `3:2` | `1536x1024` | `2048x1360` | Not recommended |
| `2:3` | `1024x1536` | `1360x2048` | Not recommended |
| `4:3` | `1024x768` | `2048x1536` | Not recommended |
| `3:4` | `768x1024` | `1536x2048` | Not recommended |
| `16:9` | `1536x864` | `2048x1152` | `3840x2160` |
| `9:16` | `864x1536` | `1152x2048` | `2160x3840` |
| `21:9` | `2016x864` | `2688x1152` | `3840x1648` |
| `9:21` | `864x2016` | `1152x2688` | `1648x3840` |

## Error Response

See [Error Codes and Troubleshooting](https://apihop.ai/en/docs/api-reference/errors) for the full code reference, protocol differences, and diagnostic steps.

```json
{
  "code": 10000,
  "message": "prompt is required",
  "type": "api_error"
}
```

Common errors:

- `400`: missing required parameters or unsupported parameter combination
- `401`: authentication failed or API Key is incorrect
- `402`: insufficient balance
- `404`: model does not exist or is not enabled
- `429`: rate limit exceeded
- `5xx`: service temporarily unavailable or image generation failed

gpt-image-2; ürün görselleri, poster taslakları, illüstrasyonlar, sosyal içerikler, yüksek çözünürlüklü görseller, stil aktarımı ve çoklu referans birleştirme için görsel oluşturmayı ve referans görsel düzenlemeyi destekler.

text

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

Kimlik doğrulama

http

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Hızlı başlangıç

json

{
  "model": "gpt-image-2",
  "prompt": "A minimal black wireless earbud product poster on a white background, clean studio lighting, no text",
  "n": 1,
  "size": "2048x1152",
  "resolution": "2k",
  "quality": "low"
}

Fiyat karşılaştırmasının kapsamı

RequestBeam’in yayımladığı 1K / 2K / 4K görsel kademeleri, OpenAI’nin resmî sabit görsel başı tarifeleri değil, *RequestBeam satış fiyatlarıdır*. OpenAI fiyatlandırma belgeleri, görsel/metin tokenı ve işleme kademesi ücretlerini açıklar; gerçek maliyet boyuta, kaliteye, referans girdilere ve çıktıya bağlıdır. İkisinde de 1k veya 2k geçtiği için karşılaştırmak eş koşullarda indirim hesabı değildir.

Desteklenmeyen tasarruf iddiasından kaçınmak için eski toplu sağlayıcı USD per image referansı ve indirim rozeti GPT Image 2 için özellikle gizlenmiştir. RequestBeam fiyatı görünür kalır ve faturalandırma sözleşmesi değişmez. Gelecekte savunulabilir bir karşılaştırma için tam modeli, uç noktayı, görsel kalitesini, boyutu, girdi koşullarını, resmî kaynak URL’sini ve referansın doğrulandığı tarihi kaydedin. Ücretli çağrıdan önce hesabınızın geçerli fiyatını kontrol edin.

İstek gövdesi

modelstringzorunluVarsayılan: gpt-image-2

Görsel modeli kimliği. gpt-image-2 kullanın.

promptstringzorunlu

Görsel istemi. Konuyu, sahneyi, kompozisyonu, stili, malzemeyi, ışığı, renkleri ve metin bulunup bulunmayacağını açıklayın.

nintegerVarsayılan: 1

Oluşturulacak görsel sayısı. Mevcut gpt-image-2 genel sözleşmesi yalnızca 1 destekler. Diğer değerler rezervasyondan önce 400 döndürür.

sizestringVarsayılan: auto

Çıktı en boy oranı veya piksel boyutları.

Yaygın değerler:

1:1
4:3
16:9
9:16
1024x1024
1536x1024
1024x1536
2048x2048
2048x1152
3840x2160
2160x3840
auto

qualitystringVarsayılan: auto

Çıktı kalitesi. Desteklenen değerler low, medium, high ve auto içerir.

resolutionstringVarsayılan: 1k

Çıktı çözünürlüğü kademesi. Desteklenen değerler 1k, 2k ve 4k.

size ile birleştirilebilir; örneğin size: "16:9" ve resolution: "2k".

image_urlsarray<string>

Talimatla düzenleme veya çoklu görsel birleştirmede kullanılan referans görseller.

En fazla 16 görsel.
Her görsel en fazla 20 MB, toplam girdi sınırı 256 MB olabilir.
Herkese açık görsel URL’leri desteklenir.
data:image/...;base64,... gibi Base64 veri URI’leri desteklenir.
Aynı dizide URL’ler ve Base64 veri URI’leri karıştırılabilir.

output_formatstringVarsayılan: png

Çıktı biçimi. Desteklenen değerler png, jpeg ve webp içerir.

streambooleanVarsayılan: false

Server-Sent Events döndürülüp döndürülmeyeceği.

Referans görseller ve düzenleme

Referans görsel düzenleme aynı JSON uç noktasını kullanır. image_urls ekleyin ve prompt içinde korunacak ve değiştirilecek öğeleri açıklayın:

json

{
  "model": "gpt-image-2",
  "prompt": "Keep the product unchanged, replace the background with a dark blue studio, and add soft rim lighting",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "size": "1:1",
  "resolution": "2k"
}

Birden fazla referans konuyu, kompozisyonu veya görsel stili sağlayabilir:

json

{
  "model": "gpt-image-2",
  "prompt": "Use the product from the first image and the composition from the second image to create a clean ecommerce hero image",
  "image_urls": [
    "https://example.com/product.png",
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  ],
  "size": "4:3",
  "resolution": "2k"
}

Mevcut genel sözleşme sınırları:

Tüm görseli düzenleme, stil aktarımı ve çoklu referans birleştirme image_urls üzerinden desteklenir.
Ayrı bir POST https://api.apihop.ai/openai/v1/images/edits rotası yoktur.
multipart/form-data yüklemeleri kabul edilmez. Yerel görselleri önce Base64 veri URI’lerine dönüştürün veya erişilebilir URL’lere yükleyin.
Maske tabanlı inpainting desteklenmez. mask, mask_url veya maskUrl göndermek rezervasyondan önce 400 döndürür.

İstek örnekleri

1:1 ürün görseli

json

{
  "model": "gpt-image-2",
  "prompt": "A transparent glass cup on a light gray background, commercial product photography, soft shadow, no text",
  "n": 1,
  "size": "1024x1024",
  "resolution": "1k",
  "quality": "low",
  "output_format": "png"
}

16:9 poster

json

{
  "model": "gpt-image-2",
  "prompt": "A futuristic city night poster with neon lights, wet streets, cinematic composition, no text",
  "n": 1,
  "size": "2048x1152",
  "resolution": "2k",
  "quality": "medium",
  "output_format": "jpeg"
}

Sonuçların döndürülmesi

Bu OpenAI uyumlu uç nokta, daha sonra sorgulamak için önce data.jobId içeren bir görev gönderim yanıtı döndürmez:

stream: false ile mevcut HTTP isteği tamamlanmayı bekler ve JSON yanıtında görsel URL’leri döndürür.
stream: true ile mevcut SSE bağlantısı image_generation.completed ve [DONE] boyunca açık kalır.

Bu uç noktanın sonuçlarını almak için GET https://api.apihop.ai/v1/jobs/{id} kullanmayın. Asenkron işi sorgulama yalnızca asenkron oluşturma uç noktası açıkça jobId döndürdüğünde kullanılmalıdır.

Akışsız yanıt

Yanıt görsel URL’leri içerir. Üst sağlayıcı rotası ölçüm bilgisi sağlıyorsa usage dahil edilir.

json

{
  "created": 1777270000,
  "data": [
    {
      "url": "https://image.example.com/generated/123456789012345678/0.png"
    }
  ],
  "usage": {
    "input_tokens": 20,
    "output_tokens": 1234,
    "total_tokens": 1254
  }
}

Akışlı yanıt

text

event: image_generation.completed
data: {"type":"image_generation.completed","data":[{"index":0,"url":"https://image.example.com/generated/123456789012345678/0.png"}],"usage":{"input_tokens":20,"output_tokens":1234,"total_tokens":1254}}

data: [DONE]

Boyut başvurusu

Hedef oran	1K önerisi	2K önerisi	4K önerisi
`1:1`	`1024x1024`	`2048x2048`	Önerilmez
`3:2`	`1536x1024`	`2048x1360`	Önerilmez
`2:3`	`1024x1536`	`1360x2048`	Önerilmez
`4:3`	`1024x768`	`2048x1536`	Önerilmez
`3:4`	`768x1024`	`1536x2048`	Önerilmez
`16:9`	`1536x864`	`2048x1152`	`3840x2160`
`9:16`	`864x1536`	`1152x2048`	`2160x3840`
`21:9`	`2016x864`	`2688x1152`	`3840x1648`
`9:21`	`864x2016`	`1152x2688`	`1648x3840`

Hata yanıtı

Tam kod başvurusu, protokol farkları ve tanılama adımları için Hata kodları ve sorun giderme sayfasına bakın.

json

{
  "code": 10000,
  "message": "prompt is required",
  "type": "api_error"
}

Yaygın hatalar:

400: zorunlu parametre eksik veya parametre birleşimi desteklenmiyor
401: kimlik doğrulama başarısız veya API anahtarı yanlış
402: yetersiz bakiye
404: model yok veya etkin değil
429: hız sınırı aşıldı
5xx: hizmet geçici olarak kullanılamıyor veya görsel oluşturma başarısız