Bilder

Bild bearbeiten

Ein Bild anhand eines Prompts und eines Quellbilds bearbeiten

POST
/v1/images/edits

Übersicht

Erstellt ein bearbeitetes oder erweitertes Bild anhand eines Originalbilds und eines Prompts.

Dieser Endpunkt unterstützt sowohl:

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

gpt-image-2 wird hier unterstützt. Es akzeptiert Multipart-image-Uploads, JSON-image_url / image_urls und 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 einen Task zurückzugeben; jedes Modell, das async unter seinen unterstützten Parametern auflistet, wie beispielsweise gpt-image-2 und die FLUX-Edit-Modelle, verwendet denselben Task-Polling-Ablauf.

gpt-image-2-Edits akzeptieren keine resolution; verwenden Sie size für Ausgabeabmessungen. background akzeptiert auto oder opaque; transparent wird nicht unterstützt. Bevorzugen Sie bei Bearbeitungen mit mehreren Bildern oder hoher Latenz async: true und führen Sie ein Polling für den zurückgegebenen Task durch.

Nano Banana-Referenzbild-Anfragen (nano-banana-2, nano-banana-2.1, nano-banana-2-lite und nano-banana-pro) werden auf /v1/images/generations mit operation: "image-to-image" und image_urls bereitgestellt, nicht auf diesem /v1/images/edits-Endpunkt. Image-Edit-Anfragen 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 Image-Edit. Ihre Image-to-Image-Anfragen verwenden /v1/images/generations mit operation: "image-to-image".

xAI Grok Imagine-Bildbearbeitungsmodelle akzeptieren eine begrenzte Anzahl an Quellbildern: grok-imagine-image-2.0 akzeptiert maximal 5 und grok-imagine-image maximal 3. Anfragen mit mehr Quellbildern, als das Modell akzeptiert, schlagen bei der Eingabevalidierung mit 400 too_many_images fehl. Ihre Image-to-Image-Anfragen verwenden ebenfalls diesen Endpunkt.

Die Details jedes Modells (GET /v1/models/{model}, siehe Modell abrufen) geben den Endpunkt für jede Operation in tokenlab.request_format_summary.request_endpoint_by_operation sowie die akzeptierten Felder und Limits in tokenlab.request_format_details.operation_constraints an. Eine an den falschen Endpunkt gesendete Operation gibt 400 unsupported_endpoint zurück.

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

Request-Body

Timeout für synchrone Anfragen: Einige Bildanfragen geben das finale Bild inline zurück und warten auf den Abschluss der Generierung. Anfragen mit hoher Auflösung oder hoher Qualität können fast eine Minute oder länger dauern; setzen Sie daher das Timeout Ihres HTTP-Clients auf mindestens 120s. Wenn die Erstellungsantwort status: "pending", task_id oder poll_url enthält, führen Sie stattdessen ein Polling auf GET /v1/tasks/{task_id} durch.

Remote-Bild-URLs: Wenn eine Multipart-Eingabe erforderlich ist, ruft TokenLab JSON-image_url, image_urls oder images[].image_url ab und sendet die Bytes als Multipart-image-Parts. URLs müssen öffentliche http/https-Adressen sein, ohne eingebettete Zugangsdaten oder Fragmente, und dürfen nicht zu Localhost-, privaten oder reservierten IP-Bereichen auflösen; jede Weiterleitung wird erneut überprüft. Die abgerufene Nutzlast muss ein echtes PNG-, JPEG- oder WebP-Bild sein. Die Grenzwerte liegen bei 50 MiB pro Bild, 200 MiB insgesamt für über URLs abgerufene Bilder in einer Anfrage, 30s Abruf-Timeout und bis zu 3 Weiterleitungen.

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. Das Gesamtlimit von 200 MiB umfasst alle Quellbilder und die Maske.

imagefile

Multipart-Quellbilder. Wiederholen Sie image, um mehrere GPT Image-Quellen anzugeben. Dateien müssen im Format PNG, JPEG oder WebP vorliegen, bis zu 16 Quellbilder und jeweils maximal 50 MiB. xAI Grok Imagine-Edit-Modelle verwenden dieselben Eingabefelder, begrenzen jedoch die Quellbilder: maximal 5 für grok-imagine-image-2.0 und maximal 3 für die anderen xAI-Edit-Modelle.

promptstringerforderlich

Eine Textbeschreibung der gewünschten Bearbeitung, bis zu 32.000 Zeichen. Erforderlich für jedes Modell, dessen Details prompt auflisten. Tools ohne Prompt, wie beispielsweise stability-upscale-fast, werden ohne einen solchen aufgerufen.

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 Abmessungen wie image aufweisen.

Bei JSON-Anfragen kann mask auch ein Objekt mit genau einem von image_url oder file_id sein; file_id-Werte müssen von /v1/files stammen und an dieselbe Image-Edit-Konfiguration gebunden bleiben.

modelstringerforderlich

Das für die Bildbearbeitung zu verwendende Modell. Verwenden Sie gpt-image-2 für GPT Image-Edits oder ein anderes aktuelles Image-Edit-Modell, 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 Abmessungen müssen Vielfache von 16 sein, die längste Kante maximal 3840px, das Verhältnis von langer zu kurzer Seite maximal 3:1 und die Gesamtzahl der Pixel 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. Das empfohlene Format 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 sowie 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-Medienergebnis-URLs. Sie bleiben 30 Tage lang gültig. Siehe Datenaufbewahrung.

asyncbooleanStandard: false

Auf true setzen, um einen Task zurückzugeben, bevor das finale Bild bereit ist. Nur Modelle, die async unter ihren unterstützten Parametern auflisten, akzeptieren dies, beispielsweise gpt-image-2; bei jedem anderen Modell gibt die Anfrage 400 unsupported_async_mode zurück. Abgeschlossene asynchrone Edits geben unabhängig vom angeforderten response_format URLs zurück; verwenden Sie synchrone Anfragen, wenn Sie b64_json benötigen.

userstring

Eine eindeutige Kennung, die Ihren Endnutzer für die Missbrauchsüberwachung darstellt.

Antwort

createdinteger

Unix-Zeitstempel des Zeitpunkts, an dem die Bilder erstellt wurden.

dataarray

Array der generierten Bilder.

Jedes Objekt enthält:

  • url (string): TokenLab-Medienergebnis-URL des bearbeiteten Bildes, 30 Tage gültig. 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 wird und das Modell Bild-Bytes zurückgibt.
usageobject

Token-Zahlen (input_tokens, output_tokens, total_tokens und deren Details) für token-bepreiste Modelle wie gpt-image-2, sofern verfügbar.

Asynchrone Task-Antwort

Setzen Sie async: true bei einem Modell, das dies unterstützt, um einen Task zu erstellen, anstatt in der Anfrage auf das bearbeitete Bild zu warten. Die Antwort enthält status: "pending", task_id und poll_url. Führen Sie ein Polling auf /v1/tasks/{task_id} durch, bis der Task completed oder failed erreicht.

Asynchrone Edit-Tasks geben ausschließlich finale Bild-URLs zurück. Wenn Sie rohe b64_json-Bilddaten benötigen, verwenden Sie eine synchrone Anfrage.

Bei der Abrechnung kann der geschätzte Betrag reserviert werden, wenn der Task erstellt wird. Abgeschlossene Tasks werden nach tatsächlicher Nutzung abgerechnet, und fehlgeschlagene oder abgelaufene Tasks 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. Nicht erreichbare URLs, Timeouts, 403/404-Antworten, private/interne Hosts, Zugangsdaten oder Fragmente in der URL, Nicht-Bildinhalte, nicht unterstützte Formate und Größenlimit-Verletzungen geben 400 oder 413 zurück und identifizieren die image_url- / image_urls[n]-Eingabe. Der Code lautet invalid_image_url, unsupported_image_content_type, too_many_images oder bei 413 image_too_large bzw. image_input_too_large. Laden Sie für private oder durch Header geschützte Assets Multipart-image-Dateien direkt hoch oder erstellen Sie /v1/files-Referenzen.

Senden Sie einen Idempotency-Key-Header, um eine Anfrage nach einem Timeout sicher zu wiederholen; siehe Sicheres Wiederholen mit einem Idempotenzschlüssel.

Hy Image 3.5 Preview bearbeitet ein Referenzbild anhand einer schriftlichen Anweisung. Es akzeptiert ausschließlich size 1024x1024 und n 1:

{
  "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"
Idempotency-Key?string

Optionaler Schlüssel, der eine Bildanfrage sicher für Wiederholungsversuche macht, sofern die Anfrage eine Aufgabe erstellt hat. Senden Sie für jede Anfrage einen neuen eindeutigen Wert, wie z. B. eine UUID. Ein Wiederholungsversuch mit demselben Schlüssel und demselben Body gibt dann diese Aufgabe zurück und erstellt, versendet oder berechnet keine zweite Aufgabe. Bei einer Anfrage, die das Bild direkt zurückgibt, kann ein Wiederholungsversuch mit demselben Schlüssel einen Aufgabenstatus anstelle des Bildes oder 409 mit idempotent_response_not_replayable zurückgeben. Ein abweichender Body mit einem bereits akzeptierten Schlüssel wird abgelehnt; der Statuscode und Fehlercode für diesen Fall sind nicht garantiert. Ein Schlüssel mit mehr als 255 Zeichen wird ignoriert, und die Anfrage verfügt dann über keinen Idempotenz-Schutz. Siehe Sichere Wiederholungsversuche mit einem Idempotenz-Schlüssel.

Länge1 <= length <= 255

Anfragekörper

Antwort

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json