Skip to main content
POST
POST /v1/images/edits Der Bild-zu-Bild-Endpunkt verwendet einen Request-Body im Format multipart/form-data. Lade ein oder mehrere Referenzbilder hoch und übermittle Prompt- und Parameterfelder als Formularfelder.
Verwende https://bettertoken.ai/v1 als Base URL. Übermittle deinen BetterToken API Key über Authorization: Bearer YOUR_API_KEY.
Du kannst im Playground auf der rechten Seite Formularfelder ausfüllen und Referenzbilder hochladen und den Request dann direkt an https://bettertoken.ai/v1/images/edits senden.
Verwende für Bild-zu-Bild-Requests keinen normalen JSON-Body. Übermittle Text- und Dateifelder mit multipart/form-data.

Empfohlene Werte

Sende diese Felder in jedem Request explizit:
Verwende image für ein einzelnes Referenzbild. Verwende wiederholte image[]-Felder für mehrere Referenzbilder.

Ein Referenzbild

Mehrere Referenzbilder

Einen ausgewählten Bereich mit Maske bearbeiten

Füge das optionale Dateifeld mask hinzu, wenn du die Bearbeitung auf einen ausgewählten Bereich lenken möchtest. Der aktuelle BetterToken-Endpunkt liest eine einzelne Datei im Feld mask. Sende keine wiederholten mask[]-Felder.
  • Originalbild und Maske müssen dasselbe Dateiformat und dieselben Pixelabmessungen haben. Jede Datei muss kleiner als 50 MB sein. Verwende für maximale Kompatibilität PNG mit Alpha-Kanal für beide Dateien.
  • Die Maske muss einen Alpha-Kanal enthalten. Vollständig transparente Pixel (Alpha 0) markieren den Bereich, den das Modell neu zeichnen darf. Vollständig deckende Pixel (Alpha 255) weisen das Modell an, diesen Bereich beizubehalten.
  • Ein normales RGB-Schwarzweißbild ist keine gültige Maske, wenn es nicht tatsächlich einen Alpha-Kanal enthält.
  • Wenn du mehrere image[]-Felder sendest, wird die Maske auf das erste Eingabebild angewendet.
  • Die Maske dient dem Modell als Orientierung. Sie garantiert nicht, dass Pixel außerhalb des transparenten Bereichs absolut identisch bleiben.

Maskierte Bearbeitung mit Python

Öffne beide Dateien in einer einzigen with-Anweisung, damit Python sie nach der Anfrage schließt:

Dateien vor dem Upload prüfen

Diese minimale Pillow-Prüfung kontrolliert die erforderlichen Angaben zu Format, Abmessungen und Alpha-Kanal. Bei einer typischen lokalen Maske gibt sie außerdem eine Warnung aus, wenn der Alpha-Kanal nicht sowohl vollständig transparente als auch vollständig deckende Bereiche enthält:

Python-Beispiel

Empfohlene Größen

size steht für das erwartete Seitenverhältnis und die Größenstufe. Die tatsächlich zurückgegebenen Pixel können vom Server zugeordnet oder angepasst werden. Verwende die dekodierten Bildabmessungen, statt die Ausgabe zwangsweise auf den angeforderten Wert zuzuschneiden.

Bild speichern

Eine erfolgreiche Antwort folgt dem OpenAI-kompatiblen Bildantwortformat:
Lies data[0].b64_json und speichere es als Base64-Bildinhalt. Setze immer output_format: "png", damit du das dekodierte Bild als .png speichern kannst.

Antwortablauf

Dieser Endpunkt ist synchron. Halte nach dem Senden von POST /images/edits den aktuellen HTTP-Request offen, bis der Server antwortet. Bei erfolgreicher Generierung wird der Bildinhalt in data[0].b64_json zurückgegeben. Der Endpunkt gibt keine task_id zurück; es gibt keinen separaten Endpunkt für Statusabfragen oder das Herunterladen von Ergebnissen.

Verwandte Dokumentation

Autorisierungen

Authorization
string
header
erforderlich

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

multipart/form-data
model
enum<string>
Standard:gpt-image-2
erforderlich

Use the GPT Image 2 model ID.

Verfügbare Optionen:
gpt-image-2
Beispiel:

"gpt-image-2"

prompt
string
erforderlich

Instructions for editing the image or generating from reference images.

Beispiel:

"Use this reference image to create a more polished square product hero image while preserving the main style."

image
file

The reference image field for a single input image.

image[]
file[]

Repeat this field for each input when sending multiple reference images.

mask
file

An optional single mask file. The mask and original image must have the same format and dimensions, each file must be smaller than 50 MB, and the mask must contain an Alpha channel. For maximum compatibility, use PNG with an Alpha channel for both files. With multiple image[] inputs, the mask applies to the first image.

n
Standard:1

Use 1. Send separate requests when you need multiple output images.

Beispiel:

"1"

size
enum<string>
Standard:1024x1024

The requested image size or aspect-ratio tier. The server may map or adjust the final pixel dimensions, so inspect the decoded image for its actual size.

Verfügbare Optionen:
auto,
1024x1024,
1536x1024,
1024x1536,
1536x1152,
1152x1536,
2048x2048,
2048x1152,
3840x2160,
2160x3840
Beispiel:

"1024x1024"

response_format
enum<string>
Standard:b64_json

Use b64_json.

Verfügbare Optionen:
b64_json
Beispiel:

"b64_json"

output_format
enum<string>
Standard:png

Use png. Do not rely on jpeg or webp being returned directly in the selected format.

Verfügbare Optionen:
png
Beispiel:

"png"

Antwort

Image editing result.

created
integer
Beispiel:

1710000000

data
object[]