Bildbearbeitung
Bilder bearbeiten, mit Masken ausbessern und Varianten mit der Images API erstellen.
Überblick
Die Images API bearbeitet ein vorhandenes Bild auf drei Arten: Gesamtbild-Bearbeitung, maskenbasiertes Inpainting und Varianten. Jeder Modus nimmt sein Quellbild (und eine optionale Maske) als hochgeladenes Asset entgegen — es gibt keinen URL- oder Inline-Weg.
Warnung
/v1/images/edits und /v1/images/variations akzeptieren nur application/json. Der veraltete multipart/form-data-Datei-Upload wurde entfernt — das Senden von multipart gibt 415 legacy_multipart_removed zurück. Ob das Bild wenige KB oder 25 MB groß ist, Quelle und Maske müssen zuerst über einen vorab signierten Upload laufen, danach übermitteln Sie JSON mit image_upload_id / mask_upload_id.
Drei Modi
| Modus | Endpunkt | Erforderlich | Wirkung |
|---|---|---|---|
| Gesamtbild-Bearbeitung | POST /v1/images/edits | model, prompt, image_upload_id | Das gesamte Bild gemäß Prompt bearbeiten |
| Masken-Inpainting | POST /v1/images/edits | das obige + mask_upload_id | Nur den maskierten Bereich ändern |
| Variante | POST /v1/images/variations | model, image_upload_id (kein Prompt) | Varianten im selben Stil erzeugen |
Die Angabe von mask_upload_id schaltet eine Bearbeitung automatisch auf Inpainting um — kein zusätzliches Flag nötig.
Ein Bild bearbeiten
Presignen und laden Sie zuerst die Quelle mit purpose=image_edit_source hoch (und für Inpainting die Maske mit purpose=image_edit_mask). Übermitteln Sie dann JSON:
| 1 | curl https://api.alltoken.ai/v1/images/edits -H "Authorization: Bearer $ALLTOKEN_API_KEY" -H "Content-Type: application/json" -d '{ |
| 2 | "model": "gpt-image-1.5", |
| 3 | "prompt": "Change the background to a sunset", |
| 4 | "image_upload_id": "upl_source...", |
| 5 | "mask_upload_id": "upl_mask...", |
| 6 | "size": "1024x1024", |
| 7 | "output_format": "png" |
| 8 | }' |
Häufige optionale Felder: size, quality, output_format, output_compression, background, moderation, n, user. Die vollständige Liste finden Sie in der Image API-Referenz.
Varianten erstellen
Varianten brauchen nur eine Quelle (hochgeladen mit purpose=image_variation_source) — keinen Prompt:
| 1 | curl https://api.alltoken.ai/v1/images/variations -H "Authorization: Bearer $ALLTOKEN_API_KEY" -H "Content-Type: application/json" -d '{ |
| 2 | "model": "gpt-image-1.5", |
| 3 | "image_upload_id": "upl_source...", |
| 4 | "n": 2 |
| 5 | }' |
Optionale Felder: size, n, output_compression, user.
Das Ergebnis abrufen
Die Erstellung gibt 202 + { id, status: "queued", ... } zurück. Alle drei Modi fragen denselben Endpunkt ab:
$curl https://api.alltoken.ai/v1/images/generations/{id} -H "Authorization: Bearer $ALLTOKEN_API_KEY"Während queued / processing enthält die Antwort next_poll_after_ms — nutzen Sie es, um die nächste Abfrage zu takten. Bei completed hat jedes data[]-Element b64_json, r2_url, r2_url_expires_at, mime_type und revised_prompt.
Warnung
b64_json wird einmalig geliefert — nur der erste completed-GET gibt es zurück, schreiben Sie es also sofort auf die Festplatte. Bevorzugen Sie r2_url (30 Tage gültig, geräteübergreifend) und behandeln Sie b64_json als Notlösung für den ersten Abruf. Nach Ablauf von r2_url gibt der GET 410 image_expired zurück. Es gibt keinen „list images"-Endpunkt — erfassen Sie die Ergebnisse selbst per task_id.
Stapelverarbeitung
Eine Anfrage verarbeitet ein Quellbild (plus eine optionale Maske). Um N Bilder zu bearbeiten, führen Sie N unabhängige dreistufige Abläufe aus — jeder mit eigenem presign → PUT → create → poll. Sie können sie gleichzeitig ausführen; beachten Sie zwei Grenzen:
- 100 ausstehende Uploads — presignen Sie nicht Hunderte von
upload_ids und lassen sie ungenutzt. - 2 GiB pro UTC-Tag — rund 80 Dateien à 25 MiB erreichen die Grenze.
Empfehlung: Halten Sie 5–10 gleichzeitige Bahnen, jede führt einen vollständigen presign → PUT → create → poll durch, bevor sie das nächste Bild aufnimmt. Die Anzahl ausstehender Uploads bleibt klein und Sie erreichen das Kontingent nie. Details zum Kontingent siehe Medien-Uploads.