GPT-Image-2-Bilderzeugung | API-Dokumentation

# 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 unterstützt Bilderzeugung und Referenzbildbearbeitung für Produktbilder, Plakatentwürfe, Illustrationen, Social-Media-Material, hochauflösende Bilder, Stilübertragung und Kombination mehrerer Referenzen.

text

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

Authentifizierung

http

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Schnellstart

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

Umfang des Preisvergleichs

Die veröffentlichten Bildstufen 1K / 2K / 4K von RequestBeam sind *Verkaufspreise von RequestBeam*, keine offiziellen festen OpenAI-Preise je Bild. Die OpenAI-Preisdokumentation beschreibt Bild-/Texttoken- und Verarbeitungsstufenpreise; die tatsächlichen Kosten hängen von Größe, Qualität, Referenzeingaben und Ausgabe ab. Ein Vergleich allein wegen der Begriffe 1k oder 2k ist keine Rabattberechnung auf gleicher Grundlage.

Um unbelegte Sparversprechen zu vermeiden, sind die alte anbieterübergreifende Referenz USD per image und das Rabattabzeichen für GPT Image 2 bewusst ausgeblendet. Der RequestBeam-Preis bleibt sichtbar; sein Abrechnungsvertrag ist unverändert. Für einen belastbaren künftigen Vergleich dokumentieren Sie exaktes Modell, Endpunkt, Bildqualität, Größe, Eingabebedingungen, offizielle Quell-URL und das Datum der Referenzprüfung. Prüfen Sie vor einem kostenpflichtigen Aufruf den wirksamen Kontopreis.

Anfragekörper

modelstringerforderlichStandard: gpt-image-2

Bildmodell-ID. Verwenden Sie gpt-image-2.

promptstringerforderlich

Bildprompt. Beschreiben Sie Motiv, Szene, Komposition, Stil, Material, Beleuchtung, Farben und ob Text erscheinen soll.

nintegerStandard: 1

Anzahl zu erzeugender Bilder. Der aktuelle öffentliche gpt-image-2-Vertrag unterstützt nur 1. Andere Werte liefern vor der Reservierung 400.

sizestringStandard: auto

Ausgabeseitenverhältnis oder Pixelmaße.

Häufige Werte:

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

qualitystringStandard: auto

Ausgabequalität. Unterstützte Werte sind low, medium, high und auto.

resolutionstringStandard: 1k

Auflösungsstufe der Ausgabe. Unterstützt werden 1k, 2k und 4k.

Kombinierbar mit size, zum Beispiel size: "16:9" und resolution: "2k".

image_urlsarray<string>

Referenzbilder für anweisungsgesteuerte Bearbeitung oder Kombination mehrerer Bilder.

Bis zu 16 Bilder.
Jedes Bild darf bis zu 20 MB groß sein, bei insgesamt höchstens 256 MB Eingabe.
Öffentlich zugängliche Bild-URLs werden unterstützt.
Base64-Daten-URIs wie data:image/...;base64,... werden unterstützt.
URLs und Base64-Daten-URIs dürfen im selben Array gemischt werden.

output_formatstringStandard: png

Ausgabeformat. Unterstützte Werte sind png, jpeg und webp.

streambooleanStandard: false

Ob Server-Sent Events zurückgegeben werden.

Referenzbilder und Bearbeitung

Referenzbildbearbeitung verwendet denselben JSON-Endpunkt. Fügen Sie image_urls hinzu und beschreiben Sie in prompt, was erhalten und geändert werden soll:

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

Mehrere Referenzen können Motiv, Komposition oder visuellen Stil liefern:

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

Aktuelle Grenzen des öffentlichen Vertrags:

Ganzbildbearbeitung, Stilübertragung und Kombination mehrerer Referenzen werden über image_urls unterstützt.
Es gibt keine separate Route POST https://api.apihop.ai/openai/v1/images/edits.
Uploads mit multipart/form-data werden nicht akzeptiert. Wandeln Sie lokale Bilder zunächst in Base64-Daten-URIs um oder laden Sie sie unter erreichbaren URLs hoch.
Maskenbasiertes Inpainting wird nicht unterstützt. mask, mask_url oder maskUrl liefern vor der Reservierung 400.

Anfragebeispiele

Produktbild im Format 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"
}

Plakat im Format 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"
}

Rückgabe der Ergebnisse

Dieser OpenAI-kompatible Endpunkt liefert nicht zuerst eine Aufgabenannahme mit data.jobId für spätere Abfragen:

Bei stream: false wartet die aktuelle HTTP-Anfrage auf den Abschluss und liefert Bild-URLs in der JSON-Antwort.
Bei stream: true bleibt die aktuelle SSE-Verbindung bis image_generation.completed und [DONE] geöffnet.

Verwenden Sie nicht GET https://api.apihop.ai/v1/jobs/{id}, um Ergebnisse dieses Endpunkts abzurufen. Nutzen Sie Asynchronen Auftrag abrufen nur, wenn ein asynchroner Erstellungsendpunkt ausdrücklich eine jobId zurückgibt.

Antwort ohne Streaming

Die Antwort enthält Bild-URLs. usage wird eingeschlossen, wenn die Anbieterroute Messdaten liefert.

json

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

Streaming-Antwort

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]

Größenreferenz

Zielverhältnis	Empfehlung für 1K	Empfehlung für 2K	Empfehlung für 4K
`1:1`	`1024x1024`	`2048x2048`	Nicht empfohlen
`3:2`	`1536x1024`	`2048x1360`	Nicht empfohlen
`2:3`	`1024x1536`	`1360x2048`	Nicht empfohlen
`4:3`	`1024x768`	`2048x1536`	Nicht empfohlen
`3:4`	`768x1024`	`1536x2048`	Nicht empfohlen
`16:9`	`1536x864`	`2048x1152`	`3840x2160`
`9:16`	`864x1536`	`1152x2048`	`2160x3840`
`21:9`	`2016x864`	`2688x1152`	`3840x1648`
`9:21`	`864x2016`	`1152x2688`	`1648x3840`

Fehlerantwort

Die vollständige Codereferenz, Protokollunterschiede und Diagnoseschritte finden Sie unter Fehlercodes und Fehlerbehebung.

json

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

Häufige Fehler:

400: erforderliche Parameter fehlen oder Parameterkombination nicht unterstützt
401: Authentifizierung fehlgeschlagen oder API-Schlüssel falsch
402: unzureichendes Guthaben
404: Modell existiert nicht oder ist nicht aktiviert
429: Ratenlimit überschritten
5xx: Dienst vorübergehend nicht verfügbar oder Bilderzeugung fehlgeschlagen