# gpt-image-2 Bildgenerierung und Bildbearbeitung

QCode.cc stellt einen `gpt-image-2`-Dienst bereit, dessen **Anfrage- und Antwortformate mit der OpenAI Images API kompatibel sind** (einige Parameter verhalten sich anders – siehe [Unterschiede zur offiziellen OpenAI API](#differences-vs-the-official-openai-api)), und deckt zwei Endpunkte ab:

- **Text-zu-Bild** `POST /v1/images/generations` — JSON-Anfrage, Bilder allein aus Text erzeugen
- **Bildbearbeitung** `POST /v1/images/edits` — Multipart-Upload von 1–8 Quellbildern (optionale Maske), Neulackieren / Ändern / Kompositieren gemäß Prompt (seit Mai 2026 verfügbar)

`gpt-image-2` ist OpenAIs neuestes Bildmodell (veröffentlicht April 2026) und bietet derzeit die **stärkste In-Bild-Textdarstellung aller öffentlichen Modelle** – es kann englische und chinesische Zeichen zuverlässig innerhalb generierter Bilder darstellen.

> ℹ️ OpenAI hat gpt-image-2.5 am 08.09.2026 veröffentlicht (API-Modellnamen `gpt-image-2.5-flare` / `gpt-image-2.5-sunburst`). Dieser Dienst akzeptiert `gpt-image-2.5`, `gpt-image-2.5-flare` und `gpt-image-2.5-sunburst` als **Kompatibilitäts-Modellnamen**, sodass Clients, die bereits für die neuen Namen konfiguriert sind, unverändert funktionieren. **Derzeit werden alle diese Namen von gpt-image-2 bedient** – Ausgabe, Latenz und Preis entsprechen `gpt-image-2`; die Qualitätsstufen `xhigh` / `max` werden als `high` behandelt, und 2.5-exklusive Funktionen wie 4K / beliebige Auflösungen sind noch nicht verfügbar. Das `model`-Feld in den Antworten lautet `gpt-image-2`.

Was QCode.cc zusätzlich bietet:

- **Funktioniert mit dem OpenAI SDK** – `base_url` ändern und fertig; Anfrage- und Antwortformate entsprechen OpenAI (einschließlich des Multipart-Edits-Endpunkts); einige Parameter verhalten sich anders, siehe Vergleichstabelle am Ende
- **Zugriff in mehreren Regionen**: globales Smart Routing (api) / Asien (Korea / Taiwan / Hongkong) / Nordamerika & Europa (Los Angeles) – wählen Sie den dem Netzwerk nächstgelegenen Einstiegspunkt
- **Ein einziger API-Key**: nutzen Sie Ihren bestehenden QCode.cc `cr_`-Key weiter – gleiches Kontingent wie für Claude Code, Codex und Gemini CLI
- **Einheitliche Nutzungsansicht**: Bildaufrufe und Chat-Aufrufe werden in Ihrem Dashboard zusammengeführt, zusätzlich gibt es eine dedizierte Self-Service-Nutzungsseite
- **Gemeinsames Kontingent über Endpunkte hinweg**: `generations` und `edits` teilen sich dasselbe Limit von 100 Bildern pro Key und Tag sowie das Limit von 2 gleichzeitigen Anfragen

Typische Anwendungsfälle: Plakaterstellung, Illustrationen, Produktbilder, UI-Mockups, Social-Media-Assets, **Bildbearbeitung (lokales Inpainting / Mehrbild-Komposition / Hintergrundtausch / originalgetreue Restaurierung)**.

---

## Schnellstart

### Text-zu-Bild (`generations`)

Drei Zeilen Python für Ihr erstes Bild:

```python
from openai import OpenAI
import base64

client = OpenAI(
    base_url="https://api.qcode.cc/qcode-img/v1",
    api_key="cr_YOUR_QCODE_API_KEY",
    timeout=180.0,  # typically 45-80s per image, occasionally over 100s; set at least 180s
)

result = client.images.generate(
    model="gpt-image-2",
    prompt="A cyberpunk Tokyo street at night, neon reflecting in rain puddles",
    size="1024x1024",
    quality="low",
    n=1,
)

with open("output.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))
```

### Bildbearbeitung (`edits`)

Bestehendes Bild hochladen + Prompt, optional mit Maske für lokales Inpainting:

```python
from openai import OpenAI
import base64

client = OpenAI(
    base_url="https://api.qcode.cc/qcode-img/v1",
    api_key="cr_YOUR_QCODE_API_KEY",
    timeout=180.0,
)

result = client.images.edit(
    model="gpt-image-2",
    image=open("cat.png", "rb"),
    mask=open("mask.png", "rb"),          # optional: PNG alpha; transparent area = repaint region
    prompt="put a tiny crown on the cat",
    size="1024x1024",
    quality="high",
)

with open("edited.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))
```

> ⚠️ **Setzen Sie timeout ≥ 180 s immer explizit**: die Standard-Timeout des OpenAI SDK ist zu kurz. Die Inferenz von `gpt-image-2` ist deutlich langsamer als bei früherem Text-zu-Bild (siehe [Latenz & Timeout](#latency-timeout-settings) unten).

---
## Endpunkte

Der Dienst `gpt-image-2` (sowohl `generations` als auch `edits`) ist über jeden QCode.cc-Zugangspunkt verfügbar. Hängen Sie einfach `/qcode-img/v1` an die Base-URL an:

| Ihr Standort | Empfohlene base_url | Protokoll | Hinweise |
|---|---|---|---|
| China | `https://api.qcode.cc/qcode-img/v1` | HTTPS | Standardempfehlung |
| HK / SEA | `https://asia.qcode.cc/qcode-img/v1` | HTTPS | Asien-Knoten (Korea / Taiwan / Hongkong, nächstliegend) |
| Nordamerika / Europa | `https://us.qcode.cc/qcode-img/v1` | HTTPS | US-RY2-Knoten (Los Angeles) |

Alle Zugangspunkte leiten an denselben Dienst und dasselbe Abrechnungssystem weiter — Nutzung und Kontingent sind einheitlich. Kein Zugangspunkt begrenzt eine einzelne Anfrage auf 100 Sekunden; der Server wartet bis zu 180 Sekunden pro Anfrage.

> `qcode-img` ist das Pfadpräfix für Bildgenerierung und -bearbeitung, parallel zu `/api` (Anthropic), `/openai/v1` (OpenAI chat) und `/gemini` (Gemini).

---

## API-Referenz

### Allgemeine Request-Header

| Header | Erforderlich | Wert |
|---|---|---|
| `Authorization` | ✓ | `Bearer cr_xxxxxxxxxxxxxxxx` (Ihr QCode.cc API-Key) |
| `Content-Type` | ✓ | `application/json` (generations)<br/>`multipart/form-data` (edits) |

### Generations-Endpunkt `/v1/images/generations`

**Endpunkt**: `POST {base_url}/images/generations`
**Content-Type**: `application/json`

Anfragetext:

```json
{
  "model": "gpt-image-2",
  "prompt": "A small ceramic vase with sunflower, photorealistic",
  "size": "1024x1024",
  "quality": "low",
  "n": 1
}
```

Felder:

| Feld | Typ | Erforderlich | Standard | Werte |
|---|---|---|---|---|
| `model` | string | ✗ | `gpt-image-2` | `gpt-image-2` (akzeptiert auch `gpt-image-2-low` / `-medium` / `-high`, gleichbedeutend mit der Einstellung `quality`; sowie die Kompatibilitätsnamen `gpt-image-2.5` / `gpt-image-2.5-flare` / `gpt-image-2.5-sunburst`, die derzeit alle von gpt-image-2 bedient werden); jeder andere Modellname führt zu `400 unsupported_model` |
| `prompt` | string | ✓ | — | Bildbeschreibung, **mehrsprachig** (inkl. Englisch & Chinesisch) |
| `size` | string | ✗ | `1024x1024` | `auto` / `1024x1024` / `1024x1536` / `1536x1024` / `2048x2048`; ungültige Werte führen zu `422`. **Die Ausgabegröße wird vom Modell anhand des Prompts bestimmt** (gemessene Werte wie 1254×1254, 1370×1148), `size` ist nur ein Absichtshinweis |
| `quality` | string | ✗ | `medium` | `low` / `medium` / `high` (`xhigh` / `max` werden als `high` behandelt); **zurzeit hat dies kaum Auswirkung auf Ausgabequalität oder Latenz**, die Abrechnung erfolgt nach tatsächlichem Verbrauch (siehe [Abrechnung](#billing)) |
| `n` | integer | ✗ | 1 | Bilder pro Aufruf (1 – 4); **> 4 führt zu 400** (keine stille Kürzung) |
| `background` | string | ✗ | `auto` | `auto` / `opaque`; `transparent` führt zu 400 (das Modell kann keinen Alpha-Kanal erzeugen) |
| `response_format` | string | ✗ | `b64_json` | nur `b64_json`; die Angabe `url` führt zu 400 |
| `output_compression` | integer | ✗ | — | `0 – 100`, gilt für JPEG / WebP; Werte außerhalb des Bereichs führen zu 400 |
| `stream` / `partial_images` | — | ✗ | — | Noch nicht unterstützt; die Angabe führt zu 400 |

### Edits-Endpunkt `/v1/images/edits`

**Endpunkt**: `POST {base_url}/images/edits`
**Content-Type**: `multipart/form-data` (Datei-Uploads erfordern form-data, nicht JSON)

Felder:

| Feld | Typ | Erforderlich | Standard | Werte / Hinweise |
|---|---|---|---|---|
| `model` | string | ✗ | `gpt-image-2` | Kann weggelassen werden; der Edits-Endpunkt verwendet immer `gpt-image-2` |
| `image` | file (× N) | ✓ | — | Quelldatei (PNG / JPEG / WebP); **1 – 8 Bilder unterstützt** für Mehrbildkomposition (denselben Feldnamen wiederholen: `-F image=@a.png -F image=@b.png`) |
| `mask` | file | ✗ | — | PNG-Alpha-Maske; **transparenter Bereich = neu zu zeichnender Bereich**; Maskenauflösung muss mit `image` übereinstimmen (wird automatisch skaliert); gilt für Einzelbildbearbeitung |
| `prompt` | string | ✓ | — | Bearbeitungsanweisung (mehrsprachig) |
| `size` | string | ✗ | `auto` | `auto` / `1024x1024` / `1024x1536` / `1536x1024` / `2048x2048`. **Die Ausgabegröße wird vom Modell anhand des Prompts bestimmt (gemessene Werte wie 1254×1254, 1370×1148); `size` ist nur ein Absichtshinweis.** Ungültige Werte führen zu 422 |
| `quality` | string | ✗ | `auto` | `auto` / `low` / `medium` / `high` (`xhigh` / `max` werden als `high` behandelt); derzeit kaum Auswirkung auf das Ergebnis |
| `n` | integer | ✗ | 1 | Bilder pro Aufruf (1 – 4); **> 4 führt zu 400** (keine stille Kürzung) |
| `background` | string | ✗ | `auto` | `auto` / `opaque`. **`transparent` wird von gpt-image-2 nicht unterstützt** (das Modell kann keinen Alpha-Kanal erzeugen; die Angabe führt zu 400) |
| `output_format` | string | ✗ | `png` | `png` / `jpeg` / `webp` |
| `output_compression` | integer | ✗ | — | `0 – 100`, gilt für JPEG / WebP (bei PNG ignoriert); **Werte außerhalb des Bereichs führen zu 400** |
| `input_fidelity` | string | ✗ | — | Muss nicht angegeben werden: das Modell verarbeitet Eingabebilder immer mit hoher Präzision; die Angabe `low` / `high` wird ignoriert, jeder andere Wert führt zu 400 |
| `response_format` | string | ✗ | `b64_json` | nur `b64_json` akzeptiert (die Angabe `url` führt zu 400) |
| `user` | string | ✗ | — | Kennung des Endbenutzers (wird durchgereicht, zur Missbrauchserkennung auf Anbieterseite) |

**Upload-Größenlimits**: Einzelne Datei ≤ 25 MB; Gesamtgröße aller Dateien ≤ 50 MB (bei Überschreitung wird `413 image_too_large` zurückgegeben).

### Antwort (für beide Endpunkte identisch)

```json
{
  "created": 1777135432,
  "data": [
    {
      "b64_json": "iVBORw0KGgo...(base64 PNG/JPEG/WebP, 1-3 MB)",
      "revised_prompt": "A small ceramic vase with sunflower..."
    }
  ]
}
```

- `b64_json`: base64-kodierte Bilddaten; direkt rendern mit `<img src="data:image/<format>;base64,...">`
- `revised_prompt`: die verbesserte Version Ihres ursprünglichen Prompts durch das Modell (Anzeige optional)

### Fehlerantworten

Fehler folgen dem Standard-OpenAI-Schema:

```json
{
  "error": {
    "type": "rate_limit_error",
    "code": "image_daily_limit",
    "message": "Daily image generation count limit reached..."
  }
}
```

| HTTP | code | Bedeutung | Abgerechnet |
|---|---|---|---|
| 400 | `invalid_json` / `missing_prompt` | Anfragetext ist kein gültiges JSON / `prompt` fehlt | Nein |
| 400 | `unsupported_model` | Modellname nicht unterstützt (`gpt-image-2` und die Kompatibilitätsnamen `gpt-image-2.5` / `-flare` / `-sunburst` werden unterstützt; `gpt-image-1`, `dall-e-3` usw. liefern diesen Fehler) | Nein |
| 400 | `stream_not_supported` | `stream=true` oder `partial_images` wurde angegeben | Nein |
| 400 | `unsupported_background` / `unsupported_response_format` / `unsupported_n` / `unsupported_output_compression` | Parameterwert nicht unterstützt (siehe Parameter-Tabelle des jeweiligen Endpunkts) | Nein |
| 400 | `invalid_multipart` / `invalid_content_type` | Ungültiges Formular am Edits-Endpunkt (muss `multipart/form-data` sein) | Nein |
| 400 | `content_policy_violation` und ähnliche | Inhaltsmoderation hat die Anfrage abgelehnt; Prompt oder Bild ändern | Nein |
| 401 | `invalid_api_key` / `key_disabled` / `key_expired` | API-Key ungültig / deaktiviert / abgelaufen | Nein |
| 413 | `image_too_large` | Einzelne Datei > 25 MB oder Gesamtgröße aller Dateien > 50 MB | Nein |
| 422 | `unsupported_size` | `size`-Wert nicht unterstützt (gültige Werte siehe Parameter-Tabelle des jeweiligen Endpunkts) | Nein |
| 429 | `crs_daily_exhausted` / `crs_total_exhausted` | Das Tages- oder Gesamtbudget Ihres Kontos ist aufgebraucht | Nein |
| 429 | `image_daily_limit` | Tägliches Limit von 100 Bildern pro API-Key erreicht (gemeinsam für `generations` und `edits`; Erhöhung auf Anfrage) | Nein |
| 429 | `concurrency_exhausted` | Limit von 2 gleichzeitigen Anfragen pro API-Key erreicht (Erhöhung auf Anfrage) | Nein |
| 501 | `endpoint_not_implemented` | Der Edits-Endpunkt ist vorübergehend für Wartungsarbeiten geschlossen | Nein |
| 503 | `image_provider_unavailable` | Der Bilddienst ist vorübergehend nicht verfügbar; die Antwort enthält `Retry-After` — Behandlung gemäß [Timeout und Wiederholung](#timeout-and-retry) | Nein |
| 503 | `service_overloaded` / `billing_backend_unavailable` | Dienst ausgelastet / Abrechnungs-Backend vorübergehend nicht verfügbar, später erneut versuchen | Nein |
| 504 | `upstream_timeout` | Eine Bearbeitungsanfrage wurde innerhalb von 180 Sekunden nicht abgeschlossen | Nein |

---
## Codebeispiele

### Python (OpenAI SDK, empfohlen)

**Text-zu-Bild:**

```python
from openai import OpenAI
import base64

client = OpenAI(
    base_url="https://api.qcode.cc/qcode-img/v1",
    api_key="cr_YOUR_QCODE_API_KEY",
    timeout=180.0,
)

result = client.images.generate(
    model="gpt-image-2",
    prompt="A cyberpunk Tokyo street at night, neon reflecting in rain puddles",
    size="1024x1024",
    quality="low",
    n=1,
)

img_bytes = base64.b64decode(result.data[0].b64_json)
with open("output.png", "wb") as f:
    f.write(img_bytes)
print("Saved output.png")
```

**Bildbearbeitung (Einzelbild + Masken-Inpainting):**

```python
from openai import OpenAI
import base64

client = OpenAI(
    base_url="https://api.qcode.cc/qcode-img/v1",
    api_key="cr_YOUR_QCODE_API_KEY",
    timeout=180.0,
)

result = client.images.edit(
    model="gpt-image-2",
    image=open("cat.png", "rb"),
    mask=open("mask.png", "rb"),
    prompt="put a tiny crown on the cat",
    size="1024x1024",
    quality="high",
    extra_body={"output_format": "png"},
)

img = base64.b64decode(result.data[0].b64_json)
with open("edited.png", "wb") as f:
    f.write(img)
```

**Bildbearbeitung (Mehrbildkomposition, 2 – 8 Bilder):**

```python
result = client.images.edit(
    model="gpt-image-2",
    image=[
        open("scene.png", "rb"),       # 1st image: scene background
        open("product.png", "rb"),     # 2nd image: product to place
    ],
    prompt="Place the product naturally into the scene, match the lighting and shadows.",
    size="1536x1024",
    quality="high",
)
```

### curl

**Text-zu-Bild:**

```bash
curl https://api.qcode.cc/qcode-img/v1/images/generations \
  -H "Authorization: Bearer cr_YOUR_QCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cyberpunk Tokyo street at night",
    "size": "1024x1024",
    "quality": "low",
    "n": 1
  }' \
  | jq -r ".data[0].b64_json" | base64 -d > output.png
```

**Bildbearbeitung:**

```bash
curl https://api.qcode.cc/qcode-img/v1/images/edits \
  -H "Authorization: Bearer cr_YOUR_QCODE_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@cat.png" \
  -F "mask=@mask.png" \
  -F "prompt=put a tiny crown on the cat" \
  -F "size=1024x1024" \
  -F "quality=high" \
  -F "output_format=png" \
  | jq -r ".data[0].b64_json" | base64 -d > edited.png
```

**Mehrbildkomposition (einfach `-F image=@` wiederholen):**

```bash
curl https://api.qcode.cc/qcode-img/v1/images/edits \
  -H "Authorization: Bearer cr_YOUR_QCODE_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@scene.png" \
  -F "image=@product.png" \
  -F "prompt=Place the product naturally into the scene" \
  -F "size=1536x1024" \
  -F "quality=high"
```

### JavaScript / Node.js / Browser

**Text-zu-Bild:**

```javascript
const r = await fetch("https://api.qcode.cc/qcode-img/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer cr_YOUR_QCODE_API_KEY",
    "Content-Type":  "application/json",
  },
  body: JSON.stringify({
    model: "gpt-image-2",
    prompt: "A cyberpunk Tokyo street at night",
    size: "1024x1024",
    quality: "low",
    n: 1,
  }),
});
const json = await r.json();
const dataUrl = "data:image/png;base64," + json.data[0].b64_json;
document.querySelector("img").src = dataUrl;
```

**Bildbearbeitung (Browser FormData):**

```javascript
const fd = new FormData();
fd.append("model", "gpt-image-2");
fd.append("image", imageFile);              // File object from <input type="file">
fd.append("mask", maskFile);                // optional
fd.append("prompt", "put a tiny crown on the cat");
fd.append("size", "1024x1024");
fd.append("quality", "high");
fd.append("output_format", "png");

const r = await fetch("https://api.qcode.cc/qcode-img/v1/images/edits", {
  method: "POST",
  headers: { "Authorization": "Bearer cr_YOUR_QCODE_API_KEY" },
  // Don't set Content-Type manually — FormData sets multipart/form-data with the boundary
  body: fd,
});
const json = await r.json();
const dataUrl = "data:image/png;base64," + json.data[0].b64_json;
document.querySelector("img").src = dataUrl;
```

---
## Kontingente

### Standardwerte

| Dimension | Standardwert | Hinweise |
|---|---|---|
| **Tägliche Bildanzahl** | 100 / Tag / API-Key | Setzt um 00:00 Pekinger Zeit zurück; **geteilt zwischen `generations` und `edits`** |
| **Parallelität** | 2 gleichzeitig | Gibt 429 `concurrency_exhausted` zurück; geteilt über beide Endpunkte |
| **Upload-Größe** (nur edits) | 25 MB Einzeldatei / 50 MB gesamt | Gibt 413 `image_too_large` zurück |
| **Kontobudget** | Geteilt mit dem `dailyCostLimit` / `totalCostLimit` Ihres QCode.cc-Kontos | Gibt 429 `crs_daily_exhausted` zurück |

Die Standardwerte decken die große Mehrheit der Nutzer ab. Wenden Sie sich an den Support, um sie zu erhöhen.

### Nutzungsabfrage

- **Dashboard** — zeigt Chat- und Bildaufrufe gemeinsam an (letzte Aktivität, heutige Kosten, kumulative Kosten, Modellverteilung)
- **Self-Service-Seite**: [https://api.qcode.cc/qcode-img/usage](https://api.qcode.cc/qcode-img/usage) — geben Sie Ihren API-Key ein, um die letzten 30 Tage der Nutzung, eine detaillierte Aufrufliste und einen ECharts-Trend einzusehen (der Key wird lokal in Ihrem Browser gespeichert, niemals hochgeladen)

---

## Abrechnung

### So funktioniert die Abrechnung

`generations` und `edits` werden gleich abgerechnet, auf Basis der **tatsächlichen Token-Nutzung**, die vom Dienst gemeldet wird:

| Abrechnungsposition | Einheitspreis |
|---|---|
| Input-Text-Tokens | $8 / 1M Tokens |
| Output-Bild-Tokens | $30 / 1M Tokens |

- **$0.08 Mindestbetrag pro Anfrage**: Liegen die tatsächlichen Kosten unter $0.08, werden $0.08 berechnet. In der Produktion verwendet ein einzelnes Ausgabebild in der Regel 500 – 1500 Bild-Tokens (Median ≈ 800: ≈ 600 bei generations, ≈ 1030 bei edits), mit tatsächlichen medianen Kosten von ≈ $0.028 und p90 ≈ $0.055, sodass **99 % der erfolgreichen Anfragen mit $0.08 / Anfrage berechnet werden**
- Der Mindestbetrag gilt **pro Anfrage**, nicht pro Bild: Bei `n=2` zahlen Sie $0.08, wenn beide Bilder zusammen weniger als $0.08 kosten
- `size` / `quality` haben keinen Einfluss auf die Abrechnung; nur die tatsächliche Nutzung zählt
- Zusätzliche Eingabebilder und `mask` am edits-Endpunkt werden **nicht separat berechnet**

### Fehler werden nicht berechnet

Jede fehlgeschlagene Anfrage wird **niemals berechnet**: 4xx / 5xx, Timeouts, Ablehnungen durch Inhaltsmoderation und Client-Verbindungsabbrüche (geschlossene Verbindungen) sind kostenlos.

### Währung

Die Kosten werden in USD abgerechnet und gemäß der Währungsrichtlinie Ihres QCode.cc-Kontos beglichen (CNY / USD).

---

## Latenz & Timeout-Einstellungen

`gpt-image-2` ist ein Inferenz-basiertes Modell und dauert deutlich länger als herkömmliche Text-to-Image-Modelle. Gemessen in der Produktion im August – September 2026 (erfolgreiche Anfragen):

| Kennzahl | generations | edits |
|---|---|---|
| Durchschnittliche Dauer | 45 – 60 s | 65 – 80 s |
| Anteil über 100 s | ca. 8 % | ca. 10 % |
| Längste | ca. 180 s | ca. 195 s |

Der `quality`-Wert hat geringen Einfluss auf die Dauer.

**Praktische Hinweise**:

- Der Standard-Timeout des OpenAI Python SDK ist zu kurz — **setzen Sie immer explizit `timeout=180.0` oder höher**
- `fetch` im Browser hat keinen Standard-Timeout; wenn Sie `AbortController` verwenden, geben Sie ihm mindestens 180 s
- Wenn die Anfrage über Ihren eigenen Reverse Proxy / Gateway geht, erhöhen Sie dessen Read-Timeout auf ≥ 180 s

---

## Timeout und Wiederholung

- **503 `image_provider_unavailable`**: Der Bilddienst ist vorübergehend nicht verfügbar, und es werden keine Kosten berechnet. Warten Sie gemäß dem `Retry-After`-Antwort-Header (Sekunden), dann wiederholen Sie die Anfrage mit exponentiellem Backoff (30 s → 60 s → 120 s) für maximal 3 Versuche; wenn es weiterhin fehlschlägt, wenden Sie sich an den Support
- **504 `upstream_timeout` / Clientseitiger Timeout**: Eine einzelne Generierung hat 180 Sekunden überschritten. Ein sofortiger erneuter Versuch ist unproblematisch; wenn weiterhin Timeouts auftreten, vereinfachen Sie den Prompt oder reduzieren Sie die Anzahl der Eingabebilder
- **429**: ein Kontingent- oder Parallelitätslimit — warten Sie gemäß dem `Retry-After`-Header; wenn es weiterhin auftritt, wenden Sie sich an den Support, um Ihre Limits zu erhöhen
- Fehlgeschlagene Anfragen werden nicht berechnet, sodass eine Wiederholung nie doppelt berechnet wird
## Tipps für Prompts

### Text-zu-Bild (`generations`)

- **Mehrsprachig**: Chinesische, englische oder gemischte Prompts funktionieren
- **Mehr Details sind besser**: Umgebung, Komposition, Licht, Stil, Aufnahmedistanz / Brennweite / Winkel
- **Markennamen / bekannte Personen vermeiden**: Das Modell verweigert möglicherweise oder liefert unscharfe Ergebnisse (OpenAI Content Policy)
- **Text im Bild**: `gpt-image-2` ist hervorragend beim Rendern von englischen / chinesischen Texten in Bildern (Plakattitel, Slogans, Beschilderungen) — einfach den wörtlichen Text in den Prompt setzen, keine besondere Syntax erforderlich
- **Content Moderation**: Ein Prompt, der gegen die Content Policy verstößt, gibt 400 zurück (z. B. `content_policy_violation`) und wird nicht abgerechnet

Beispiel:

```
A vintage poster in Bauhaus style, bold black text "MORNING COFFEE" centered,
warm orange and cream color palette, geometric shapes, slightly textured paper background
```

### Bildbearbeitung (`edits`)

- **Die Maske sagt „wo“, nicht „was“**: Transparenter Bereich = neu zu zeichnende Region, undurchsichtiger Bereich bleibt erhalten. Der Prompt beschreibt, was gezeichnet werden soll. Die Auflösung der Maske muss zu `image` passen (das System skaliert neu).
- **Bei mehreren Eingabebildern die Rolle jedes Bildes im Prompt benennen** — z. B. „Das erste Bild ist die Szene, das zweite Bild ist das Produkt, das darin platziert werden soll“ — `gpt-image-2` liest Eingaben in Reihenfolge.
- **`input_fidelity` muss nicht übergeben werden**: gpt-image-2 verarbeitet Eingabebilder immer mit hoher Qualität und bewahrt automatisch Gesichter / Logos / Texte / Produktdetails (Angabe von `low` / `high` wird ignoriert, jeder andere Wert gibt 400 zurück).
- **Ohne Maske** wird das gesamte Bild gemäß dem Prompt neu gezeichnet (die semantische Struktur bleibt erhalten, aber jeder Bereich kann sich ändern).

Beispiel:

```
# Local inpaint: add a crown, keep the rest unchanged
prompt = "Put a tiny golden crown on the cat's head. Keep everything else unchanged."
mask = (alpha PNG with only the head area transparent)
```

---

## Unterschiede zur offiziellen OpenAI API

| Aspekt | OpenAI offiziell | QCode.cc |
|---|---|---|
| SDK-Kompatibilität | — | ✅ Anfrage- / Antwortformate sind kompatibel, die Änderung von `base_url` genügt; die folgenden Zeilen listen die Verhaltensunterschiede auf |
| Abrechnung | Pro Token | Auf tatsächlichen Token-Verbrauch, mindestens $0.08 pro Anfrage |
| `/v1/images/generations` (Text-zu-Bild) | ✅ | ✅ |
| `/v1/images/edits` (Bildbearbeitung) | ✅ | ✅ Unterstützt die Komposition von 1 – 8 Bildern und Inpainting per Maske |
| `size` | — | Nur Hinweis; das Modell bestimmt die Ausgabegröße |
| `quality` | — | Derzeit wenig Auswirkung; Abrechnung nach tatsächlicher Nutzung |
| `background=transparent` | — | ❌ Gibt 400 zurück |
| `response_format=url` | — | ❌ Nur `b64_json` |
| `stream` + `partial_images` (inkrementelle Rückgabe) | ✅ | ⏳ Noch nicht unterstützt, die Übergabe gibt 400 zurück |
| `/v1/images/variations` (reine Varianten) | ✅ (DALL·E-Endpunkt) | ⏳ Noch nicht unterstützt (Annäherung über `edits` mit einem beschreibenden Prompt) |
| gpt-image-2.5 (`flare` / `sunburst`) | ✅ (veröffentlicht am 2026-09-08) | ✅ Akzeptiert die Kompatibilitäts-Modellnamen, **wird derzeit von gpt-image-2 bereitgestellt**; `xhigh` / `max` werden als `high` behandelt, 2.5-exklusive Funktionen (4K usw.) werden noch nicht unterstützt |

---

## Online-Playground

[https://api.qcode.cc/qcode-img/](https://api.qcode.cc/qcode-img/) — im Browser ausprobieren:

- **Sowohl Text-zu-Bild- als auch Bildbearbeitungs-Modi** sind visuell eingerichtet (hochladen, Maske zeichnen, Hintergrund / output_format wählen usw.)
- API-Key und Prompt eingeben und sofort generieren
- Umschaltung zwischen englischer / chinesischer Benutzeroberfläche
- Standardmäßig `low` Qualität
- Enthält die vollständige API-Referenz inline (curl / Python / JavaScript-Tabs + Parametertabelle + Fehlercodes)
- Ein-Klick-Download als PNG / JPEG / WebP

---

## Häufig gestellte Fragen

**F: Was tue ich bei `503 image_provider_unavailable`?**
A: Der Bilddienst ist vorübergehend nicht verfügbar, fehlgeschlagene Anfragen werden nicht abgerechnet. Warten Sie gemäß dem Header `Retry-After` und versuchen Sie es erneut (exponentielles Backoff ab 30 Sekunden, maximal 3 Versuche). Bei anhaltendem Fehler kontaktieren Sie den Support.

**F: Unterstützen Sie gpt-image-2.5 (flare / sunburst)?**
A: Sie können die Modellnamen `gpt-image-2.5`, `gpt-image-2.5-flare` und `gpt-image-2.5-sunburst` direkt verwenden, aber **sie werden derzeit von gpt-image-2 bereitgestellt**, daher sind Ausgabe, Latenz und Preis identisch mit `gpt-image-2`; die Qualitätsstufen `xhigh` / `max` werden als `high` behandelt, und 2.5-exklusive Funktionen wie 4K werden noch nicht unterstützt. Das Feld `model` in den Antworten lautet `gpt-image-2`.

**F: Warum unterscheidet sich die Ausgabegröße von dem `size`, das ich gesendet habe?**
A: Das aktuelle Modell bestimmt Komposition und Ausgabegröße aus dem Prompt selbst (z. B. 1254×1254, 1370×1148), daher ist `size` nur ein Absichtshinweis. Wenn Sie eine exakte Größe benötigen, beschneiden oder skalieren Sie das Bild lokal.

**F: Sehen `low` und `high` fast gleich aus?**
A: Ja. Derzeit hat `quality` nur wenig Auswirkung auf das Ergebnis oder die Dauer; die Abrechnung erfolgt nach tatsächlicher Nutzung, die meisten Anfragen kosten jeweils $0.08.

**F: Werden fehlgeschlagene Anfragen berechnet?**
A: Nein. 4xx / 5xx, Timeouts, Ablehnungen durch die Content Moderation und Trennungen der Clientverbindung sind kostenfrei.

---

## Verwandte Dokumentationen

- [Endpunkte & API-Pfade](/en/docs/getting-started/endpoints-and-api-paths) — vollständige Liste der QCode.cc-Einträge, Protokollpfade, curl-Smoketest
- [Abrechnung](/en/docs/reference/billing) — Tarife, Kontingente, Kostenregeln