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ötigen | Endpunkt | Verwendung bei | Nicht geeignet für |
|---|---|---|---|
| Text-zu-Bild | POST /v1/images/generations | Der Benutzer beginnt nur mit Text | Bearbeitung einer bestehenden GPT Image-Datei |
| Bild-zu-Bild | POST /v1/images/generations | Das Modell akzeptiert operation: "image-to-image" und Bild-URLs | Modelle, die Multipart-Edit-Input erfordern |
| Bildbearbeitung | POST /v1/images/edits | Ein unterstütztes Bearbeitungsmodell ändert ein bestehendes Bild | Referenzgenerierung im Nano Banana-Stil |
| Variation | POST /v1/images/variations | Eine bestehende Integration nutzt bereits die Variations-API | Ein neues Referenzbild-Feature |
| Status | GET /v1/tasks/{id} | Eine Erstellungsantwort liefert task_id, status: "pending" oder poll_url | Die 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-imageoderimage-edit. - Den vom Modell erwarteten Anfrage-Endpunkt.
- Wie Referenzen gesendet werden:
image_url,image_urls,reference_image_urls, Multipartimageoder JSONimages[]. - Ob das Modell
size,aspect_ratio,resolution,quality,background,output_formatoderresponse_formatakzeptiert.
Modellspezifische Felder
- Anfragen im Stil von
gpt-image-2verwenden OpenAI-ähnliche Felder fürsize,qualityund Bearbeitungen. Für Generierungen und Bearbeitungen mit diesem Modell akzeptiertbackgrounddie Werteautooderopaque;transparentwird nicht unterstützt. Lassen Sie optionale Felder weg, um automatische Standardwerte zu verwenden. - Gemini- und Nano Banana-Bildfamilien verwenden normalerweise
aspect_ratio; senden Sieresolutionnur, wenn die Modelldetails dies explizit angeben. Bei Modellen mit Auflösungsstufen wird einesizevon1K,2Koder4Kalsresolutiongesendet; eine Stufe, die vonresolutionabweicht, wird abgelehnt. - Nano Banana Bild-zu-Bild gehört auf
/v1/images/generationsmitoperation: "image-to-image"und Referenzbild-URLs. /v1/images/generationsakzeptiert keinimages[]oderfile_idauf oberster Ebene; dies sind Strukturen für den Bearbeitungsablauf.- Remote-Bildreferenzen müssen öffentliche
http- oderhttps-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[]miturloderb64_jsonzurück. - Asynchrone Antworten geben
id,task_id,statusund normalerweise einepoll_urlzurück. Senden Sie"async": truebei 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ückgegebenenidodertask_idauf. - Verwenden Sie eine synchrone Anfrage, wenn Sie
b64_jsonbenö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-Keydie 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 einen409-Fehler mitidempotent_response_not_replayablezurückgeben. Überprüfen Sie ohne Schlüssel, ob eine Aufgabe erstellt wurde, bevor Sie es erneut versuchen. - Verwenden Sie Usage und
billing_transaction_idfür die endgültige Abrechnung.
Häufige Fehler
| Symptom | Wahrscheinliche Ursache | Lösung |
|---|---|---|
400 mit param: "model" | Fehlendes explizites Modell | Fragen Sie /v1/models?recommended_for=image ab und senden Sie model |
| Nicht unterstütztes Feld | Feld ist für dieses Modell nicht dokumentiert | Entfernen Sie das Feld oder wählen Sie ein Modell/Endpunkt, das es dokumentiert |
Kein b64_json bei asynchronem Ergebnis | Asynchrone Bildaufgaben geben URL-orientierte Ergebnisse zurück | Verwenden Sie den synchronen Modus für Base64-Ausgabe |
| Referenzbild abgelehnt | Falscher Endpunkt oder private/abgelaufene URL | Passen Sie die dokumentierte Referenzstruktur des Modells an und verwenden Sie erreichbare URLs |
API-Referenz
| Thema | Referenz |
|---|---|
| Bild erstellen | Bild erstellen |
| Bild bearbeiten | Bild bearbeiten |
| Bildvariation erstellen | Bildvariation erstellen |
| Bildstatus abrufen | Bildstatus abrufen |
| Aufgabenstatus abrufen | Aufgabenstatus abrufen |