Skip to main content

Übersicht

Für Coding-Agenten zuerst die aktuelle empfohlene Bild-Shortlist mit GET /v1/models?recommended_for=image ermitteln und dann das ausgewählte model explizit an diesen Endpunkt senden. gpt-image-2 ist ein GPT-Image-Modell mit tokenbasierter Abrechnung. TokenLab rechnet nach der offiziellen OpenAI-Usage-Aufschlüsselung für Texteingabe, Bildeingabe, gemeldete Cache-Eingabe und Bildausgabe-Token ab; es wird nicht als Festpreis-pro-Bild-Modell behandelt. Für die Bilderzeugung mit gpt-image-2 unterstützt der öffentliche Vertrag prompt, n, size, quality, response_format, async, background, output_format, output_compression oder compression, moderation und user. background akzeptiert auto oder opaque; transparent wird nicht unterstützt. Wenn size oder quality fehlt, verwendet TokenLab auto; eigene size-Werte müssen dem unten beschriebenen flexiblen WIDTHxHEIGHT-Vertrag entsprechen. input_fidelity gehört nicht zum aktuellen öffentlichen TokenLab-Vertrag für gpt-image-2; lassen Sie es weg, sonst gibt die Anfrage 400 unsupported_parameter zurück.

Hinweise zum Modellverhalten

Google-Gemini-Bildfamilien verwenden keinen gemeinsamen Auswahlvertrag:
  • gemini-3.1-flash-image, gemini-3-pro-image und nano-banana-pro unterstützen aspect_ratio sowie resolution (1k, 2k, 4k) für ihre öffentlichen Text-zu-Bild- und Image-Edit/Image-to-Image-Operationen.
  • nano-banana-2 unterstützt im aktuellen TokenLab-Vertrag aspect_ratio sowie resolution (1k, 2k, 4k) nur für Text-zu-Bild-Generierung.
  • gemini-2.5-flash-image, nano-banana und nano-banana-edit unterstützen aspect_ratio, bieten aber keine öffentliche Auswahl von resolution.
  • Verwenden Sie für Nano-Banana-Referenzbild-Anfragen nano-banana-edit oder nano-banana-pro auf diesem Endpunkt (/v1/images/generations) mit operation: "image-to-image" und image_urls. Senden Sie Nano-Banana-Referenzbild-Anfragen nicht an /v1/images/edits.
  • Bei Nano-Banana-Image-to-Image-Anfragen darf nano-banana-pro resolution (1k, 2k, 4k) enthalten; nano-banana-edit muss es weglassen. nano-banana und nano-banana-2 sind im aktuellen Modelldetails Text-zu-Bild-Modelle.
  • Referenzbilder können an diesem Endpunkt als JSON image_url / image_urls oder als multipart-image-Datei übergeben werden. /v1/images/generations akzeptiert weder images[] noch file_id; /v1/files-Referenzen gelten nur für /v1/images/edits-Modelle, die images[].file_id ausdrücklich dokumentieren.
Bei Google-Bildfamilien bevorzugen Sie aspect_ratio und senden Sie resolution nur, wenn das Modell es ausdrücklich unterstützt. xAI-Grok-Imagine-Bildmodelle (grok-imagine-image, grok-imagine-image-quality und das legacy grok-imagine-image-pro) unterstützen aspect_ratio sowie resolution (1k, 2k). grok-imagine-image-pro bleibt als Kompatibilitäts-ID für grok-imagine-image-quality erhalten.

Anfragekörper

Timeout für synchrone Anfragen: Einige Bildanfragen geben das endgültige Bild inline zurück und warten dafür, bis die Generierung abgeschlossen ist. Hochauflösende oder hochwertige Anfragen können fast eine Minute oder länger dauern; setzen Sie das Timeout Ihres HTTP-Clients daher auf mindestens 120s. Wenn die Create-Antwort status: "pending", task_id oder poll_url enthält, folgen Sie stattdessen der zurückgegebenen poll_url.
string
erforderlich
Zu verwendendes Modell (z. B. gpt-image-2, flux-pro, qwen-image-plus oder nano-banana-pro). Die aktuelle Empfehlungsliste erhalten Sie mit GET /v1/models?recommended_for=image.
string
erforderlich
Textbeschreibung des gewünschten Bildes.
string
Öffentliche HTTPS-Referenzbild-URL für Image-to-Image-Generierung. Setzen Sie bei Nano-Banana-Referenzbild-Anfragen operation auf image-to-image; nano-banana-pro darf resolution enthalten, während nano-banana-edit es weglassen sollte.
string[]
Öffentliche HTTPS-Referenzbild-URLs. Verwenden Sie dieses Feld für ein oder mehrere Referenzbilder in JSON-Anfragen. file_id und images[] werden an diesem Endpunkt nicht unterstützt.
string[]
Zusätzliche modellspezifische Referenzbild-URLs für Anbieter, die primäre Eingabebilder von Referenzen unterscheiden.
file
Multipart-Referenzbilddatei für Image-to-Image-Generierung. Verwenden Sie dies, wenn das Quellbild privat ist oder Header-Authentifizierung benötigt. Dies ist keine /v1/files-file_id; dieser Endpunkt akzeptiert keine file_id.
integer
Standard:"1"
Anzahl der zu generierenden Bilder (1-10, modellabhängig).
string
Standard:"1024x1024"
Bildgröße. Verwenden Sie dieses Feld für OpenAI-ähnliche Bildfamilien und andere Modelle, die exakte Pixelgrößen akzeptieren.Für gpt-image-2 akzeptiert size auto oder WIDTHxHEIGHT. Benutzerdefinierte Abmessungen müssen auf beiden Seiten Vielfache von 16 sein, die längste Kante darf höchstens 3840px betragen, das Verhältnis lange/kurze Kante höchstens 3:1, und die Gesamtpixelzahl muss zwischen 655,360 und 8,294,400 liegen. aspect_ratio und resolution gehören derzeit nicht zum öffentlichen TokenLab-Vertrag für gpt-image-2.Für Google-Gemini-Bildfamilien wird size als Kompatibilitätsalias behandelt und auf den öffentlichen aspect_ratio-Vertrag des Modells sowie, falls unterstützt, auf resolution abgebildet. Für diese Modelle sollten Sie vorzugsweise aspect_ratio direkt senden.
string
Modellabhängiger Seitenverhältnis-Selektor.Häufige Werte für Google-Bildfamilien sind 1:1, 16:9, 9:16, 3:2 und 2:3.
string
Modellabhängiger Auflösungs-Selektor.Unterstützt auf gemini-3.1-flash-image und gemini-3-pro-image für Text-zu-Bild und Image-Edit, auf nano-banana-pro für Text-zu-Bild und Image-to-Image sowie auf nano-banana-2 nur für Text-zu-Bild. Typische Werte sind 1k, 2k und 4k. Senden Sie diesen Parameter nicht an reine Aspect-Ratio-Gemini-Bildfamilien, außer das Modell dokumentiert ihn ausdrücklich. Für xAI-Grok-Imagine-Bildmodelle verwenden Sie 1k oder 2k.
string
Standard:"standard"
Bildqualität. GPT-Image-Modelle wie gpt-image-2 verwenden auto, low, medium oder high. Andere Bildfamilien können anbieterspezifische Werte verwenden; prüfen Sie die Metadaten des ausgewählten Modells, bevor Sie Nicht-Standardwerte senden.
string
Standard:"url"
Antwortformat: url oder b64_json. Standard ist url.Bei Azure Official- oder Azure-kompatiblen gpt-image-2-Anfragen erhält TokenLab Bilddaten als b64_json. Bei url-Anfragen lädt TokenLab jedes Bild in das CDN hoch und gibt data[].url zurück. Wenn der CDN-Speicher nicht verfügbar ist oder der Upload fehlschlägt, schlägt die Anfrage fehl, statt in eine Base64-Antwort umgewandelt zu werden. Bei b64_json wird das rohe Base64 zurückgegeben.
boolean
Standard:"false"
Auf true setzen, um mit gpt-image-2 oder offiziellen FLUX/BFL-Bildmodellen zuerst eine Aufgabe zu erstellen. Abgeschlossene Async-Bildaufgaben liefern unabhängig vom angeforderten response_format URLs; verwenden Sie synchrone Anfragen, wenn Sie b64_json benötigen.
string
Optionaler Stil-Selektor. Senden Sie ihn nur, wenn das ausgewählte Modell ihn ausdrücklich dokumentiert; lassen Sie ihn für gpt-image-2 weg, sofern die Modellmetadaten nichts anderes sagen.
string
Eine eindeutige Kennung für den Endbenutzer.

Antwort

Inline-Antwort

integer
Unix-Zeitstempel der Erstellung.
array
Array der generierten Bilder.Jedes Objekt enthält:
  • url (string): URL des generierten Bildes
  • b64_json (string): Base64-kodiertes Bild (falls angefordert)
  • revised_prompt (string): Optionale vom Anbieter zurückgegebene Prompt-Überarbeitung, wenn das Upstream-Modell sie meldet

Antwort für asynchrone Aufgaben

Setzen Sie async: true mit gpt-image-2 oder offiziellen FLUX/BFL-Bildmodellen, um eine Aufgabe zu erstellen, statt im Create-Request auf das endgültige Bild zu warten. Die Antwort enthält status: "pending", task_id und poll_url. Fragen Sie /v1/tasks/{task_id} ab, bis die Aufgabe completed oder failed erreicht. Asynchrone Bildaufgaben liefern nur die endgültigen Bild-URLs. Wenn Sie rohe b64_json-Bilddaten benötigen, verwenden Sie eine synchrone Anfrage. Beim Erstellen der Aufgabe kann der geschätzte Betrag reserviert werden. Abgeschlossene Aufgaben werden nach tatsächlicher Nutzung abgerechnet; fehlgeschlagene oder abgelaufene Aufgaben werden freigegeben oder erstattet.
integer
Unix-Zeitstempel der Erstellung.
string
Eindeutige Aufgaben-ID zum Abfragen.
string
Anfänglicher Status: pending.
string
Relative URL zum Abfragen der Ergebnisse, zum Beispiel /v1/tasks/{id}.
array
Leer, solange die Aufgabe aussteht. Abgeschlossene Bildaufgaben geben generierte Bild-URLs in data[].url zurück.
Wenn du status: "pending" erhältst, verwende poll_url oder GET /v1/tasks/{task_id}, um das Ergebnis abzurufen.

Verfügbare Modelle

Dies sind aktuelle Beispielmodelle, kein fester Katalog. Nutzen Sie GET /v1/models?recommended_for=image oder die Models-Seite für aktuelle Verfügbarkeit und Preise. Behandeln Sie ein Modell nicht statisch als immer synchron oder immer asynchron. Wenn die Create-Antwort status: "pending" zurückgibt, folgen Sie poll_url und pollen Sie bis zum Abschluss.

Task-basierte Antworten behandeln

Prüfen Sie bei Bildmodellen immer, ob die Antwort status: "pending" enthält: