GPT-Image-Edit-API auf TokenLab: Korrekter Endpunkt und Bildeingabeformen

Bildbearbeitung ist einer der anspruchsvolleren Bereiche einer KI-Produktoberfläche: Ein Benutzer lädt ein Foto hoch, beschreibt eine Änderung und erwartet ein Ergebnis. Bearbeitungen, die mehrere Quellbilder, eine große Arbeitsfläche oder einen komplexeren Prompt nutzen, dauern länger, als ein typischer synchroner HTTP-Aufruf problemlos zulässt. Dieser Leitfaden behandelt den korrekten TokenLab-Endpunkt, die beiden unterstützten Bildeingabeformen, Multi-Image-Bearbeitungen und den asynchronen Pfad für langsame Anfragen.

Der Endpunkt

Die Bildbearbeitung befindet sich unter POST /v1/images/edits – beachten Sie den Plural edits. (Ein häufiger Fehler ist das Schreiben von /images/edit, was nicht der dokumentierte Pfad ist.)

Der Endpunkt unterstützt zwei Anfrageformen:

• Einen OpenAI-kompatiblen multipart/form-data-Upload-Ablauf.
• Eine JSON-Anfrage, die image_url, image_urls oder offizielle images[]-Referenzen für unterstützte Image-to-Image-Familien bereitstellt.

Die vollständigen Anfrage- und Antwortfelder sind in der API-Referenz zur Bildbearbeitung dokumentiert.

Was gpt-image-2 hier akzeptiert

• Multipart-image-Uploads.
• JSON-image_url oder -image_urls.
• Offizielle images[]-Referenzen, bei denen jedes Objekt genau eines von image_url oder file_id enthält.
• Bis zu 16 Quellbilder pro Anfrage.

Einige Einschränkungen, die man kennen sollte, bevor man Code schreibt:

• gpt-image-2-Bearbeitungen akzeptieren keine resolution; verwenden Sie size für Ausgabeabmessungen (entweder auto oder WIDTHxHEIGHT, mit Abmessungen in Vielfachen von 16, längste Kante maximal 3840px, Verhältnis lange/kurze Seite maximal 3:1).
• background akzeptiert auto oder opaque; transparent wird nicht unterstützt.
• input_fidelity gehört nicht zu den unterstützten Feldern für gpt-image-2; das Senden dieses Feldes gibt 400 unsupported_parameter zurück.
• Geben Sie bei JSON-Anfragen genau eines von image_url, image_urls oder images an. Jedes images[]-Objekt muss genau eines von image_url oder file_id enthalten. Werte für file_id müssen zuvor über /v1/files erstellt werden.
• Nano Banana-Referenzbild-Anfragen gehören zu /v1/images/generations mit operation: "image-to-image" und image_urls – nicht zu /v1/images/edits.

Multipart-Uploads vs. JSON-Bildreferenzen

Beide funktionieren für gpt-image-2. Wählen Sie die Variante, die dazu passt, wo Ihre Bilddaten bereits liegen.

Multipart – verwenden Sie dies, wenn die Anwendung die Datei bereithält, sei es aus einem Benutzer-Upload oder einem generierten Asset. Wiederholen Sie das Feld image, um mehrere Quellen zu senden. Dateien müssen PNG, JPEG oder WebP sein und dürfen jeweils maximal 50 MiB groß sein.

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "image=@subject.png" \
  -F "image=@background.png" \
  -F "prompt=Combine the subject with the new background." \
  -F "size=1024x1024"

JSON-Bild-URLs – verwenden Sie dies, wenn die Bilder bereits unter einer öffentlichen URL liegen oder Sie sie in einer früheren TokenLab-Anfrage generiert haben und bereits eine URL vorliegt.

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "images": [
      {"image_url": "https://example.com/subject.png"},
      {"image_url": "https://example.com/background.png"}
    ],
    "prompt": "Combine the subject with the new background.",
    "size": "1024x1024",
    "async": true
  }'

Remote-URLs müssen öffentlich über http/https erreichbar sein, ohne eingebettete Anmeldedaten oder Fragmente, und dürfen nicht zu Localhost, privaten oder reservierten IP-Bereichen auflösen. TokenLab ruft die Bytes ab und übergibt sie dem Modell als Multipart-image-Teile. Das Limit pro Bild beträgt 50 MiB; das Gesamterfassungslimit für per URL abgerufene Bilder in einer Anfrage beträgt 200 MiB; das Fetch-Timeout beträgt 30 Sekunden; bis zu 3 Weiterleitungen wird gefolgt.

Multi-Image-Bearbeitungen und asynchrones Polling

Multi-Image-Bearbeitungen sind der eindeutigste Anwendungsfall für async: true. Das Senden mehrerer Bilder mit komplexen Anweisungen über einen synchronen Aufruf bedeutet, dass eine Verbindung so lange offen gehalten werden muss, wie das Modell benötigt. Setzen Sie async: true bei gpt-image-2 (und bei offiziellen FLUX/BFL-Edit-Modellen), um stattdessen einen Task zu erhalten:

{
  "created": 1706000000,
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "data": []
}

Pollen Sie die zurückgegebene poll_url oder weichen Sie auf GET /v1/tasks/{task_id} aus. Die Status lauten pending, processing, completed und failed. Ein abgeschlossener Bild-Task gibt data[].url zurück. Eine Überprüfung alle 3–5 Sekunden reicht aus; stoppen Sie bei einem finalen Status, anstatt weiter zu pollen.

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

Asynchrone Edit-Tasks geben endgültige Bild-URLs zurück, unabhängig vom angeforderten response_format. Wenn Sie rohes b64_json benötigen, verwenden Sie eine synchrone Anfrage.

Die Abrechnung kann den geschätzten Betrag reservieren, wenn der Task erstellt wird; ein abgeschlossener Task wird nach tatsächlicher Nutzung abgerechnet, und ein fehlgeschlagener oder abgelaufener Task gibt die Reservierung frei oder erstattet sie. Siehe Asynchrone Jobs und Polling für den vollständigen Lebenszyklus und Bildstatus abrufen für die Antwortfelder.

Wann welcher Modus verwendet werden sollte

Verwenden Sie async: true, wenn:

• Sie mehrere Quellbilder in einer einzigen Anfrage senden.
• Ihr Prompt oder Ihre Anweisungen so komplex sind, dass die Generierungszeit unvorhersehbar ist.
• Sie Bearbeitungen in einem Hintergrundjob, einer Warteschlange oder einem Batch-Prozess statt in einer direkten benutzerbezogenen Anfrage ausführen.

Bleiben Sie synchron, wenn:

• Sie eine Einzelbildbearbeitung mit einem kurzen Prompt durchführen.
• Ihr Client lieber schnell fehlschlägt (Fail-Fast), anstatt zu pollen.

Setzen Sie bei synchronen Aufrufen das Timeout Ihres HTTP-Clients auf mindestens 120s; Anfragen mit hoher Auflösung oder hoher Qualität können fast eine Minute oder länger dauern. Wenn die Erstellungsantwort dennoch mit status: "pending", task_id oder poll_url zurückkommt, wechseln Sie zum zurückgegebenen Polling-Ablauf.

Zu erwartende Eingabefehler

Fehler beim Abrufen von Remote-Bildern werden als Eingabefehler zurückgegeben, bevor die Generierung beginnt. Nicht erreichbare URLs, Timeouts, 403/404-Antworten, private oder interne Hosts, Anmeldedaten oder Fragmente in der URL, Nicht-Bild-Inhalte, nicht unterstützte Formate und Überschreitungen von Größenbeschränkungen geben 400 oder 413 zurück und identifizieren die fehlerhafte image_url oder image_urls[n]. Für private oder durch Header geschützte Assets laden Sie Multipart-image-Dateien direkt hoch oder erstellen Sie /v1/files-Referenzen und übergeben Sie diese als images[].file_id.

xAI Grok Imagine-Bildbearbeitungsmodelle (zum Beispiel grok-imagine-image und grok-imagine-image-quality) verwenden dieselben Eingabefelder, begrenzen Quellbilder jedoch auf 3; mehr als das gibt 400 too_many_images zurück.

Integrations-Checkliste

• Zielen Sie auf POST /v1/images/edits ab und senden Sie das model explizit.
• Wählen Sie Multipart-Uploads oder JSON-Referenzen basierend darauf, wo Ihre Bilder bereits liegen.
• Senden Sie in JSON-Anfragen genau eines von image_url, image_urls oder images[]; jeder images[]-Eintrag hat genau eines von image_url oder file_id.
• Verwenden Sie async: true für Multi-Image- oder rechenintensive Bearbeitungen; pollen Sie die zurückgegebene poll_url, bis der Task completed oder failed erreicht.
• Setzen Sie Client-Timeouts bei synchronen Anfragen auf mindestens 120 Sekunden und verarbeiten Sie eine pending-Antwort, indem Sie poll_url folgen.
• Prüfen Sie bei einem Client-Timeout, ob ein Task erstellt wurde, bevor Sie die Erstellungsanfrage wiederholen, um doppelte Gebühren zu vermeiden.

Erste Schritte

Fragen Sie GET /v1/models?recommended_for=image ab, um aktuelle Bildmodelle anzuzeigen, und öffnen Sie dann die Detailseite eines Modells, um dessen unterstützte Operationen und Anfragefelder vor dem Senden einer Anfrage zu bestätigen. Erstellen Sie einen API-Schlüssel in der Konsole, um den Edit-Endpunkt mit Ihren eigenen Bildern zu testen.