Bilder
Bild bearbeiten
Ein Bild anhand eines Prompts und eines Quellbilds bearbeiten
Ü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_urlsoder offizielleimages-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.
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.
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.
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.
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.
1Anzahl der zu generierenden Bilder (1–10, modellabhängig).
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.
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_jsonsowie indata[].url, wenn TokenLab es gespeichert hat. Wenn das Modell einen Link zurückgibt, befindet sich jedes Bild indata[].url. url: Jedes Bild befindet sich nur indata[].url.b64_json: Jedes Bild befindet sich nur indata[].b64_jsonals Base64-Daten.
Links sind TokenLab-Medienergebnis-URLs. Sie bleiben 30 Tage lang gültig. Siehe Datenaufbewahrung.
falseAuf 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.
Eine eindeutige Kennung, die Ihren Endnutzer für die Missbrauchsüberwachung darstellt.
Antwort
Unix-Zeitstempel des Zeitpunkts, an dem die Bilder erstellt wurden.
Array der generierten Bilder.
Jedes Objekt enthält:
url(string): TokenLab-Medienergebnis-URL des bearbeiteten Bildes, 30 Tage gültig. Nicht vorhanden, wennresponse_formataufb64_jsongesetzt ist. Wennresponse_formatweggelassen wird, fehlt es, falls TokenLab das Bild nicht speichern konnte.b64_json(string): Base64-Bilddaten. Vorhanden, wennresponse_formataufb64_jsongesetzt ist, oder wenn es weggelassen wird und das Modell Bild-Bytes zurückgibt.
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
{
"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 API-Key-Authentifizierung. Erstellen oder verwalten Sie API-Keys unter Dashboard > API > API Keys.
Ort: header
Header
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"
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.
1 <= length <= 255Antwort
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json