Pembuatan Gambar GPT-Image-2 | Dokumentasi API

# 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

API Hop's published **1K / 2K / 4K** image tiers are *API Hop 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 API Hop 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 mendukung pembuatan gambar dan penyuntingan gambar referensi untuk gambar produk, draf poster, ilustrasi, aset media sosial, visual beresolusi tinggi, transfer gaya, dan penggabungan beberapa referensi.

text

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

Autentikasi

http

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Mulai Cepat

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

Cakupan perbandingan harga

Tingkat gambar 1K / 2K / 4K yang dipublikasikan API Hop adalah *harga jual API Hop*, bukan tarif tetap resmi OpenAI per gambar. Dokumentasi harga OpenAI menjelaskan biaya token gambar/teks dan tingkat pemrosesan; biaya aktual bergantung pada ukuran, kualitas, masukan referensi, dan keluaran. Membandingkan keduanya hanya karena sama-sama menyebut 1k atau 2k bukan perhitungan diskon dengan dasar yang setara.

Untuk menghindari klaim penghematan tanpa dasar, referensi USD per image penyedia agregat lama dan lencana diskon sengaja disembunyikan untuk GPT Image 2. Harga API Hop tetap terlihat dan kontrak penagihannya tidak berubah. Untuk perbandingan mendatang yang dapat dipertanggungjawabkan, catat model, endpoint, kualitas gambar, ukuran, kondisi masukan, URL sumber resmi, dan tanggal verifikasi referensi secara tepat. Periksa harga efektif akun Anda sebelum melakukan panggilan berbayar.

Isi

modelstringwajibBawaan: gpt-image-2

ID model gambar. Gunakan gpt-image-2.

promptstringwajib

Prompt gambar. Jelaskan subjek, adegan, komposisi, gaya, bahan, pencahayaan, warna, dan apakah teks harus muncul.

nintegerBawaan: 1

Jumlah gambar yang akan dibuat. Kontrak publik gpt-image-2 saat ini hanya mendukung 1. Nilai lainnya mengembalikan 400 sebelum reservasi.

sizestringBawaan: auto

Rasio aspek atau dimensi piksel keluaran.

Nilai umum:

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

qualitystringBawaan: auto

Kualitas keluaran. Nilai yang didukung meliputi low, medium, high, dan auto.

resolutionstringBawaan: 1k

Tingkat resolusi keluaran. Nilai yang didukung adalah 1k, 2k, dan 4k.

Dapat digabungkan dengan size, misalnya size: "16:9" dan resolution: "2k".

image_urlsarray<string>

Gambar referensi untuk penyuntingan berbasis instruksi atau penggabungan beberapa gambar.

Hingga 16 gambar.
Setiap gambar dapat berukuran hingga 20 MB, dengan batas total masukan 256 MB.
URL gambar yang dapat diakses publik didukung.
URI data Base64 seperti data:image/...;base64,... didukung.
URL dan URI data base64 dapat dicampur dalam larik yang sama.

output_formatstringBawaan: png

Format keluaran. Nilai yang didukung meliputi png, jpeg, dan webp.

streambooleanBawaan: false

Apakah mengembalikan Server-Sent Events.

Gambar Referensi dan Penyuntingan

Penyuntingan gambar referensi menggunakan endpoint JSON yang sama. Tambahkan image_urls dan jelaskan bagian yang dipertahankan serta diubah dalam 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"
}

Beberapa referensi dapat menyediakan subjek, komposisi, atau gaya visual:

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

Batas kontrak publik saat ini:

Penyuntingan seluruh gambar, transfer gaya, dan penggabungan beberapa referensi didukung melalui image_urls.
Tidak ada rute POST https://api.apihop.ai/openai/v1/images/edits terpisah.
Unggahan multipart/form-data tidak diterima. Konversi gambar lokal ke URI data base64 atau unggah ke URL yang dapat diakses terlebih dahulu.
Inpainting berbasis mask tidak didukung. Mengirim mask, mask_url, atau maskUrl mengembalikan 400 sebelum reservasi.

Contoh Permintaan

Gambar Produk 1:1

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

Poster 16:9

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

Cara Hasil Dikembalikan

Endpoint kompatibel OpenAI ini tidak terlebih dahulu mengembalikan respons pengiriman tugas berisi data.jobId untuk polling berikutnya:

Dengan stream: false, permintaan HTTP saat ini menunggu hingga selesai dan

mengembalikan URL gambar dalam respons JSON.

Dengan stream: true, koneksi SSE saat ini tetap terbuka hingga

image_generation.completed dan [DONE].

Jangan gunakan GET https://api.apihop.ai/v1/jobs/{id} untuk mengambil hasil dari endpoint ini. Gunakan Ambil Tugas Asinkron hanya ketika endpoint pembuatan asinkron secara eksplisit mengembalikan jobId.

Respons Tanpa Streaming

Respons berisi URL gambar. usage disertakan saat rute upstream menyediakan informasi pengukuran penggunaan.

json

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

Respons Streaming

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]

Referensi Ukuran

Rasio Target	Rekomendasi 1K	Rekomendasi 2K	Rekomendasi 4K
`1:1`	`1024x1024`	`2048x2048`	Tidak disarankan
`3:2`	`1536x1024`	`2048x1360`	Tidak disarankan
`2:3`	`1024x1536`	`1360x2048`	Tidak disarankan
`4:3`	`1024x768`	`2048x1536`	Tidak disarankan
`3:4`	`768x1024`	`1536x2048`	Tidak disarankan
`16:9`	`1536x864`	`2048x1152`	`3840x2160`
`9:16`	`864x1536`	`1152x2048`	`2160x3840`
`21:9`	`2016x864`	`2688x1152`	`3840x1648`
`9:21`	`864x2016`	`1152x2688`	`1648x3840`

Respons Kesalahan

Lihat Kode Kesalahan dan Pemecahan Masalah untuk referensi kode lengkap, perbedaan protokol, dan langkah diagnosis.

json

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

Kesalahan umum:

400: parameter wajib tidak ada atau kombinasi parameter tidak didukung
401: autentikasi gagal atau API Key salah
402: saldo tidak cukup
404: model tidak ada atau belum diaktifkan
429: batas laju terlampaui
5xx: layanan sementara tidak tersedia atau pembuatan gambar gagal