GPT Image 2.5 | API-Dokumentation

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

Verwenden Sie gpt-image-2.5-flare für schnelle Bilderzeugung oder gpt-image-2.5-sunburst für präzise Bearbeitung. Prüfen Sie mit GET https://api.apihop.ai/v1/models die Verfügbarkeit für Ihren Schlüssel.

Anfrage

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	Werte
`model`	Erforderlich: `gpt-image-2.5-flare` oder `gpt-image-2.5-sunburst`
`prompt`	Erforderlicher Text, der Bild oder Bearbeitung beschreibt
`n`	Ganzzahl von 1 bis 4; Standard 1
`size`	`auto`, Seitenverhältnis oder Pixelmaße wie `1600x1200`
`resolution`	`1k` (Standard), `2k`, `4k`; bei exakten Pixelmaßen ignoriert
`quality`	`low`, `medium`, `high`, `xhigh`, `max`, `auto` (Standard)
`image_urls`	Bis zu 16 öffentlich zugängliche HTTP(S)-Bild-URLs
`output_format`	`png` (Standard), `jpeg`, `webp`
`output_compression`	Ganzzahl von 0 bis 100 für JPEG oder WebP
`background`	`auto`, `opaque`, `transparent`; Transparenz erfordert PNG oder WebP
`moderation`	`low` (Standard), `auto`
`stream`	`false` (Standard) für JSON, `true` für SSE-Abschlussereignisse

Unterstützte Seitenverhältnisse: 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. Exakte Pixelmaße müssen Vielfache von 16 sein, dürfen keine Seite über 3840 Pixel und kein Seitenverhältnis über 3:1 haben und müssen insgesamt 655,360 bis 8,294,400 Pixel umfassen. Quadratische 4k-Ausgabe beträgt beispielsweise 2880x2880, nicht 4096x4096.

Referenzbilder

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

Referenzen verwenden diesen JSON-Generierungsendpunkt. Laden Sie lokale Bilder zuerst in Ihren eigenen Speicher. Base64-Daten-URIs, Multipart-Uploads, Masken und ein separater /images/edits-Endpunkt gehören nicht zum öffentlichen Vertrag dieses Modells.

Antwort

Die HTTP-Verbindung wartet auf den Abschluss; Clients fragen keine vorgelagerte Aufgabe ab. JSON-Antworten enthalten endgültige Bild-URLs und verfügbare Tokennutzung:

json

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

Warten Sie bei stream: true auf image_generation.completed und [DONE] in derselben Verbindung. Teilbildvorschauen werden nicht garantiert.

Preise

Abgerechnet werden tatsächliche Texteingabe-, zwischengespeicherte Texteingabe-, Bildeingabe-, zwischengespeicherte Bildeingabe- und Bildausgabetokens. Beide Varianten haben dieselben Tokenpreise. Der Modellkatalog zeigt Ihren aktuellen Preis und separat den OpenAI-Referenzpreis. Ein Bild ist keine Festpreiseinheit: Promptlänge, Referenzen, Größe, Qualität und Anzahl beeinflussen die Summe. Eine vorläufige Reservierung wird nach Abschluss abgeglichen. Eine ausdrücklich gewählte Qualität macht den erwarteten Verbrauch klarer.

Ungültige Parameter liefern 400, Authentifizierungsfehler 401, unzureichendes Guthaben 402. Ein nicht verfügbares Modell liefert 404, Ratenlimits 429 und Generierungsfehler 5xx. Senden Sie eine Anfrage mit unbekanntem Abschlussstatus nicht automatisch erneut.

Fehlercodes, Streamingfehler und Grenzen für Wiederholungen stehen unter Fehlercodes und Fehlerbehebung.