Medienleitfäden

Bildgenerierung

Bilder generieren oder bearbeiten sowie fertige Dateien oder asynchrone Aufgaben verarbeiten

TokenLab unterstützt Text-zu-Bild, Bild-zu-Bild und Bildbearbeitung. Die Parameter unterscheiden sich je nach Modell. Überprüfen Sie daher die Anforderungsfelder des ausgewählten Modells, bevor Sie die Anfrage senden.

Einen Endpunkt wählen

Was Sie benötigenEndpunktVerwendung beiNicht geeignet für
Text-zu-BildPOST /v1/images/generationsDer Benutzer beginnt nur mit TextBearbeitung einer bestehenden GPT Image-Datei
Bild-zu-BildPOST /v1/images/generationsDas Modell akzeptiert operation: "image-to-image" und Bild-URLsModelle, die Multipart-Edit-Input erfordern
BildbearbeitungPOST /v1/images/editsEin unterstütztes Bearbeitungsmodell ändert ein bestehendes BildReferenzgenerierung im Nano Banana-Stil
VariationPOST /v1/images/variationsEine bestehende Integration nutzt bereits die Variations-APIEin neues Referenzbild-Feature
StatusGET /v1/tasks/{id}Eine Erstellungsantwort liefert task_id, status: "pending" oder poll_urlDie Erstellungsantwort enthält bereits die finalen data[]

Senden Sie immer model; Bild-APIs wählen kein Standardmodell für Sie aus.

Ein Modell wählen

Finden Sie aktuelle Bildmodelle mit:

curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"

Öffnen Sie die Details des ausgewählten Modells, um Folgendes zu bestätigen:

  • Die unterstützte Operation, wie z. B. text-to-image, image-to-image oder image-edit.
  • Den vom Modell erwarteten Anfrage-Endpunkt.
  • Wie Referenzen gesendet werden: image_url, image_urls, reference_image_urls, Multipart image oder JSON images[].
  • Ob das Modell size, aspect_ratio, resolution, quality, background, output_format oder response_format akzeptiert.

Modellspezifische Felder

  • Anfragen im Stil von gpt-image-2 verwenden OpenAI-ähnliche Felder für size, quality und Bearbeitungen. Für Generierungen und Bearbeitungen mit diesem Modell akzeptiert background die Werte auto oder opaque; transparent wird nicht unterstützt. Lassen Sie optionale Felder weg, um automatische Standardwerte zu verwenden.
  • Gemini- und Nano Banana-Bildfamilien verwenden normalerweise aspect_ratio; senden Sie resolution nur, wenn die Modelldetails dies explizit angeben. Bei Modellen mit Auflösungsstufen wird eine size von 1K, 2K oder 4K als resolution gesendet; eine Stufe, die von resolution abweicht, wird abgelehnt.
  • Nano Banana Bild-zu-Bild gehört auf /v1/images/generations mit operation: "image-to-image" und Referenzbild-URLs.
  • /v1/images/generations akzeptiert kein images[] oder file_id auf oberster Ebene; dies sind Strukturen für den Bearbeitungsablauf.
  • Remote-Bildreferenzen müssen öffentliche http- oder https-URLs sein. Senden Sie keine URLs aus privaten Netzwerken, eingebettete Anmeldedaten, URL-Fragmente oder signierte URLs, die vor Beginn der Verarbeitung ablaufen könnten.

Beispiel für Text-zu-Bild

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean product photo of a ceramic coffee cup on a walnut desk",
    "size": "1024x1024",
    "response_format": "url"
  }'

Beispiel für Referenzbilder

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "operation": "image-to-image",
    "prompt": "Keep the product shape, change the background to a bright studio setup",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

Das Bild abrufen

Bildantworten können synchron oder asynchron sein:

  • Synchrone Antworten geben die finalen data[] mit url oder b64_json zurück.
  • Asynchrone Antworten geben id, task_id, status und normalerweise eine poll_url zurück. Senden Sie "async": true bei einem Modell, das öffentliche asynchrone Ausführung unterstützt, um eine Aufgabe zu erhalten, anstatt auf das Bild zu warten.
  • Um eine asynchrone Aufgabe zu überprüfen, rufen Sie GET /v1/tasks/{id} mit der zurückgegebenen id oder task_id auf.
  • Verwenden Sie eine synchrone Anfrage, wenn Sie b64_json benötigen; asynchrone Bildergebnisse verwenden URLs.

Bild-Ergebnis-URLs sind TokenLab-Medien-Ergebnis-URLs, die 30 Tage lang gültig bleiben. media_retention.items meldet den Speicherstatus jedes Elements sowie expires_at; die Antwort kann media_retention weglassen, wenn der Speicherstatus nicht rechtzeitig bekannt ist, wobei die URL dennoch funktioniert. Inline-Base64-Ergebnisse fallen nicht unter diese URL-Kopieraufbewahrung. Das manuelle Speichern eines Bildes in der Media Library verleiht ihm einen separaten Lebenszyklus. Siehe Datenaufbewahrung.

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"

Speichern Sie die zurückgegebene Bild-URL, die Aufgaben-ID, das Modell sowie Ihre eigene Benutzer-/Job-ID dauerhaft. Hören Sie auf, den Status abzufragen, sobald ein Endstatus erreicht ist.

Vor dem Start

  • Validieren Sie Benutzereingaben vor dem Aufruf von TokenLab: Prompt-Länge, Bildanzahl, Erreichbarkeit der URL und Dateityp.
  • Setzen Sie HTTP-Timeouts hoch genug für synchrone Anfragen mit hoher Auflösung. Verwenden Sie async: true, wo das Modell dies für lange Aufgaben unterstützt.
  • Speichern Sie request_id, task_id, poll_url, Modell, Endpunkt und die gesendeten Feldnamen.
  • Wenn eine Bildanfrage eine Aufgabe zurückgibt, macht ein Idempotency-Key die Erstellungsanfrage sicher für Wiederholungen: Senden Sie nach einem Client-Timeout dieselbe Anfrage mit demselben Schlüssel, um diese Aufgabe zu erhalten. Bei einer Anfrage, die das Bild direkt zurückgibt, kann eine Wiederholung mit demselben Schlüssel einen Aufgabenstatus anstatt des Bildes oder einen 409-Fehler mit idempotent_response_not_replayable zurückgeben. Überprüfen Sie ohne Schlüssel, ob eine Aufgabe erstellt wurde, bevor Sie es erneut versuchen.
  • Verwenden Sie Usage und billing_transaction_id für die endgültige Abrechnung.

Häufige Fehler

SymptomWahrscheinliche UrsacheLösung
400 mit param: "model"Fehlendes explizites ModellFragen Sie /v1/models?recommended_for=image ab und senden Sie model
Nicht unterstütztes FeldFeld ist für dieses Modell nicht dokumentiertEntfernen Sie das Feld oder wählen Sie ein Modell/Endpunkt, das es dokumentiert
Kein b64_json bei asynchronem ErgebnisAsynchrone Bildaufgaben geben URL-orientierte Ergebnisse zurückVerwenden Sie den synchronen Modus für Base64-Ausgabe
Referenzbild abgelehntFalscher Endpunkt oder private/abgelaufene URLPassen Sie die dokumentierte Referenzstruktur des Modells an und verwenden Sie erreichbare URLs

API-Referenz

ThemaReferenz
Bild erstellenBild erstellen
Bild bearbeitenBild bearbeiten
Bildvariation erstellenBildvariation erstellen
Bildstatus abrufenBildstatus abrufen
Aufgabenstatus abrufenAufgabenstatus abrufen

Auf dieser Seite