gpt-image-2 Bildgenerierung und Bildbearbeitung

OpenAI-kompatible gpt-image-2 Text-zu-Bild- und Bildbearbeitungs-API: mit Umstellung von base_url sofort einsetzbar, Endpunkte in mehreren Regionen, einheitliche Abrechnung mit Ihrem QCode-Key

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), 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:

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:

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 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:

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¶

Generations-Endpunkt /v1/images/generations¶

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

Anfragetext:

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

Felder:

Edits-Endpunkt /v1/images/edits¶

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

Felder:

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)¶

{
  "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:

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

Codebeispiele¶

Python (OpenAI SDK, empfohlen)¶

Text-zu-Bild:

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):

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):

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:

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:

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):

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:

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):

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¶

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 — 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:

• $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):

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¶

Online-Playground¶

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 — vollständige Liste der QCode.cc-Einträge, Protokollpfade, curl-Smoketest
• Abrechnung — Tarife, Kontingente, Kostenregeln