TokenLab
API-Schlüssel erhalten
DokumentationAPI-ReferenzIntegrationen

Bilder

Bild bearbeiten

Bearbeiten Sie ein Bild anhand eines Prompts und eines Quellbildes

POST
/v1/images/edits

Übersicht

Erstellt ein bearbeitetes oder erweitertes Bild basierend auf einem Originalbild und einem Prompt.

Dieser Endpunkt unterstützt sowohl:

  • den unten dokumentierten, mit OpenAI kompatiblen multipart/form-data Upload-Ablauf
  • JSON-Anfragen, die image_url, image_urls oder offizielle images-Referenzen für unterstützte Bild-zu-Bild-Familien bereitstellen

gpt-image-2 wird hier unterstützt. Es akzeptiert Multipart-image-Uploads, JSON image_url / image_urls sowie offizielle images[]-Referenzen (image_url oder file_id) mit bis zu 16 Quellbildern. Erstellen Sie file_id-Werte zuerst über /v1/files. Setzen Sie async: true, um zuerst eine Aufgabe (Task) zurückzugeben; offizielle FLUX/BFL-Bearbeitungsmodelle verwenden ebenfalls denselben Task-Polling-Ablauf.

gpt-image-2-Bearbeitungen akzeptieren kein resolution; verwenden Sie size für die Ausgabedimensionen. background akzeptiert auto oder opaque; transparent wird nicht unterstützt. Für Multi-Image-Bearbeitungen oder Bearbeitungen mit hoher Latenz sollten Sie async: true bevorzugen und den zurückgegebenen Task abfragen (Polling).

Nano Banana Referenzbild-Anfragen (nano-banana-2, nano-banana-2.1, nano-banana-2-lite und nano-banana-pro) werden unter /v1/images/generations mit operation: "image-to-image" und image_urls bereitgestellt, nicht über diesen /v1/images/edits-Endpunkt. Bildbearbeitungsanfragen für nano-banana-2, nano-banana-2.1, nano-banana-2-lite und nano-banana-pro verwenden ebenfalls /v1/images/generations mit operation: "image-edit".

gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3.1-flash-lite-image und gemini-3-pro-image verwenden diesen Endpunkt für die Bildbearbeitung. Ihre Bild-zu-Bild-Anfragen verwenden /v1/images/generations mit operation: "image-to-image".

xAI Grok Imagine Bildbearbeitungsmodelle (grok-imagine-image, grok-imagine-image-quality und das ältere grok-imagine-image-pro) akzeptieren maximal 3 Quellbilder. Anfragen mit mehr als 3 Quellbildern schlagen bei der Eingabevalidierung mit 400 too_many_images fehl.

input_fidelity ist kein Teil der aktuell von TokenLab unterstützten Felder für gpt-image-2; lassen Sie es weg, da die Anfrage sonst 400 unsupported_parameter zurückgibt.

Anfragetext

Synchroner Anfrage-Timeout: Einige Bildanfragen geben das fertige Bild direkt zurück und warten, bis die Generierung abgeschlossen ist. Anfragen mit hoher Auflösung oder hoher Qualität können fast eine Minute oder länger dauern; setzen Sie daher Ihren HTTP-Client-Timeout auf mindestens 120s. Wenn die Erstellungsantwort status: "pending", task_id oder poll_url enthält, folgen Sie stattdessen der zurückgegebenen poll_url.

Remote-Bild-URLs: Wenn eine Multipart-Eingabe erforderlich ist, ruft TokenLab die JSON image_url, image_urls oder images[].image_url ab und sendet die Bytes als Multipart-image-Teile. URLs müssen öffentliche http/https-Adressen sein, ohne eingebettete Anmeldedaten oder Fragmente, und dürfen nicht auf localhost, private oder reservierte IP-Bereiche auflösen; jeder Redirect wird erneut geprüft. Das abgerufene Payload muss ein echtes PNG-, JPEG- oder WebP-Bild sein. Die Limits liegen bei 50 MiB pro Bild, 200 MiB insgesamt für per URL abgerufene Bilder in einer Anfrage, 30s Abruf-Timeout und bis zu 3 Redirects.

Geben Sie für JSON-Anfragen genau eines der Felder image_url, image_urls oder images an. Jedes images[]-Objekt muss genau eines der Felder image_url oder file_id enthalten. Das Gesamtlimit von 200 MiB umfasst alle Quellbilder und die Maske.

imagefile

Multipart-Quellbilder. Wiederholen Sie image, um mehrere GPT-Image-Quellen bereitzustellen. Dateien müssen PNG, JPEG oder WebP sein, bis zu 16 Quellbilder und jeweils 50 MiB. xAI Grok Imagine Bearbeitungsmodelle verwenden dieselben Eingabefelder, begrenzen Quellbilder jedoch auf 3.

promptstringerforderlich

Eine Textbeschreibung der gewünschten Bearbeitung.

maskfile | object

Ein zusätzliches Bild, dessen vollständig transparente Bereiche angeben, wo das Bild bearbeitet werden soll. Muss eine gültige PNG-Datei sein, kleiner als 50 MiB, und dieselben Dimensionen wie image haben.

Für JSON-Anfragen kann mask auch ein Objekt mit genau einem der Felder image_url oder file_id sein; file_id-Werte müssen von /v1/files stammen und an dieselbe Bildbearbeitungskonfiguration gebunden bleiben.

modelstringerforderlich

Das für die Bildbearbeitung zu verwendende Modell. Verwenden Sie gpt-image-2 für GPT-Image-Bearbeitungen oder ein anderes aktuelles Bildbearbeitungsmodell, das von GET /v1/models?recommended_for=image zurückgegeben wird.

nintegerStandard: 1

Anzahl der zu generierenden Bilder (1-10, modellabhängig).

sizestring

Die Größe des generierten Bildes. Verwenden Sie für gpt-image-2 auto oder WIDTHxHEIGHT; die Dimensionen müssen Vielfache von 16 sein, die längste Kante maximal 3840px, das Verhältnis von lang zu kurz maximal 3:1 und die Gesamtpixelzahl zwischen 655.360 und 8.294.400.

Für gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3-pro-image und gemini-3.1-flash-lite-image akzeptiert size eine Ausgabegröße aus der Größentabelle des Modells oder eine Auflösungsstufe: 1K, 2K oder 4K. TokenLab sendet eine Stufe als resolution. Eine Stufe, die das Modell nicht unterstützt, oder eine Stufe, die sich von resolution unterscheidet, gibt 400 mit dem Code invalid_image_size_contract zurück. Die empfohlene Form ist aspect_ratio mit resolution.

response_formatstring

Wie die Bilder zurückgegeben werden: url oder b64_json.

  • Weggelassen: Wenn das Modell Bild-Bytes zurückgibt, befindet sich jedes Bild in data[].b64_json und auch in data[].url, wenn TokenLab es gespeichert hat. Wenn das Modell einen Link zurückgibt, befindet sich jedes Bild in data[].url.
  • url: Jedes Bild befindet sich nur in data[].url.
  • b64_json: Jedes Bild befindet sich nur in data[].b64_json als Base64-Daten.

Links sind TokenLab-Medien-Ergebnis-URLs. Sie bleiben 30 Tage lang gültig. Siehe Datenaufbewahrung.

asyncbooleanStandard: false

Setzen Sie dies auf true bei gpt-image-2 oder offiziellen FLUX/BFL-Bearbeitungsmodellen, um eine Aufgabe zurückzugeben, bevor das endgültige Bild bereit ist. Abgeschlossene asynchrone Bearbeitungen geben unabhängig vom angeforderten response_format URLs zurück; verwenden Sie synchrone Anfragen, wenn Sie b64_json benötigen.

userstring

Ein eindeutiger Bezeichner für Ihren Endbenutzer zur Überwachung von Missbrauch.

Antwort

createdinteger

Unix-Zeitstempel der Erstellung der Bilder.

dataarray

Array der generierten Bilder.

Jedes Objekt enthält:

  • url (string): TokenLab-Medien-Ergebnis-URL des bearbeiteten Bildes, gültig für 30 Tage. Nicht vorhanden, wenn response_format auf b64_json gesetzt ist. Wenn response_format weggelassen wird, fehlt es, falls TokenLab das Bild nicht speichern konnte.
  • b64_json (string): Base64-Bilddaten. Vorhanden, wenn response_format auf b64_json gesetzt ist oder wenn es weggelassen wurde und das Modell Bild-Bytes zurückgibt.

Asynchrone Aufgabenantwort

Setzen Sie async: true bei gpt-image-2 oder offiziellen FLUX/BFL-Bearbeitungsmodellen, um eine Aufgabe zu erstellen, anstatt auf das bearbeitete Bild in der Anfrage 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 Bearbeitungsaufgaben geben nur endgültige Bild-URLs zurück. Wenn Sie rohe b64_json-Bilddaten benötigen, verwenden Sie eine synchrone Anfrage.

Die Abrechnung kann den geschätzten Betrag reservieren, wenn die Aufgabe erstellt wird. Abgeschlossene Aufgaben werden nach tatsächlicher Nutzung abgerechnet, fehlgeschlagene oder zeitlich abgelaufene Aufgaben werden freigegeben oder erstattet.

Anfrage

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "image=@sunlit_lounge.png" \
  -F "mask=@mask.png" \
  -F "prompt=A sunlit indoor lounge area with a pool" \
  -F "n=1" \
  -F "size=1024x1024"

Antwort

Response
{
  "created": 1706000000,
  "data": [
    {
      "url": "https://..."
    }
  ]
}

Hinweise

Fehler beim Abrufen von Remote-Bildern werden als Eingabefehler zurückgegeben, bevor die Generierung beginnt. Unerreichbare URLs, Timeouts, 403/404-Antworten, private/interne Hosts, Anmeldedaten oder Fragmente in der URL, Nicht-Bild-Inhalte, nicht unterstützte Formate und Verstöße gegen Größenbeschränkungen führen zu 400 oder 413 und identifizieren die image_url / image_urls[n]-Eingabe. Laden Sie für private oder durch Header geschützte Assets Multipart-image-Dateien direkt hoch oder erstellen Sie /v1/files-Referenzen.

Hy Image 3.5 Preview erstellt 1024-Pixel-Quadratbilder aus Text und bearbeitet Referenzbilder anhand schriftlicher Anweisungen. Es ist nützlich für das Entwerfen von Visuals und die Verfeinerung einer Komposition.

{
  "model": "hy-image-v3.5-preview",
  "prompt": "Change the table to pale blue",
  "image_url": "https://example.com/reference.png",
  "size": "1024x1024",
  "n": 1,
  "response_format": "url"
}

Autorisierung

BearerAuth
AuthorizationBearer <token>

API-Key-Authentifizierung. Erstellen oder verwalten Sie API-Keys unter Dashboard > API > API Keys.

Ort: header

Header

X-TokenLab-Delivery-Policy?string

Zustellungsrichtlinie pro Anfrage. Überschreibt die API-Key- und Workspace-Standardeinstellungen. Versucht automatisch zuerst TokenLab Verified und kann vor der Ausgabe, der Annahme der Anfrage oder der Erstellung persistenter Ressourcen einmalig auf Official umstellen.

Zulässige Werte

  • "auto"
  • "verified"
  • "official"

Anfragekörper

Antwort

application/json

application/json

application/json

application/json

application/json

application/json

Bild erstellen

Zurück

Bildvariation erstellen

Weiter