Zum Hauptinhalt springen
Lade eine lokale Bilddatei zu Samsa hoch und erhalte eine image_id. Nutze die image_id als Quellbild für einen Magic Edit, img2img, Variationen, Resize, Upscale, Hintergrundentfernung, Vektorisierung oder eine Image-to-Video-Generierung. Der MCP server bietet denselben Flow als zwei Tools, prepare_image_upload und complete_image_upload — siehe MCP-Tools. Uploads sind kostenlos — sie kosten keine Credits.

​
Die drei Schritte

1

Vorbereiten

Rufe POST /images/uploads/prepare mit dem filename, dem content_type und der exakten Dateigröße in size_bytes auf. Die Antwort gibt dir die image_id und eine presigned upload_url.
2

Die Datei per PUT senden

PUT die rohen Dateibytes an upload_url, mit demselben Content-Type. Sende an diese URL keinen Authorization-Header.
3

Abschließen

Rufe innerhalb einer Stunde POST /images/uploads/{image_id}/complete auf. Samsa prüft die Datei und gibt das Bild mit seiner gemessenen width und height zurück. Ab jetzt ist die image_id nutzbar.
curl --data-binary @file sendet die echte Dateilänge, daher passt sie immer zu size_bytes, wenn du dieselbe Datei gemessen hast.

​
Limits

Die Datei muss das Format haben, das du in content_type angegeben hast. width und height sind optionale Hinweise beim Vorbereiten: Samsa nutzt sie nur, um ein Bild über 32 MP früh abzulehnen. Die gespeicherten Abmessungen werden immer aus den hochgeladenen Bytes gemessen. Ein Upload, der nie abgeschlossen wird, wird verworfen, nachdem seine URL abgelaufen ist.

​
Lebenszyklus und Fehler

  • Vor complete nicht nutzbar. Bis complete gelingt, liefert die image_id überall 404 not_found.
  • Complete ist idempotent. Ein erneuter Aufruf gibt dasselbe Ergebnis zurück und ändert nichts. Ein späterer PUT an dieselbe upload_url ersetzt ein abgeschlossenes Bild nicht.
  • 422 validation_error — es gibt noch keine Datei, oder die Datei ist leer, hat eine andere Größe als size_bytes, ist zu groß, ist nicht lesbar, hat ein anderes Format oder liegt über 32 MP. Samsa verwirft eine abgelehnte Datei: PUT eine gültige Datei an dieselbe upload_url, solange sie gültig ist, und rufe complete dann erneut auf.
  • 404 not_found — die image_id ist unbekannt, abgelaufen, gehört einem anderen Nutzer oder wurde nicht durch prepare erstellt.
  • 409 upload_in_progress — ein anderer complete-Aufruf für denselben Upload läuft gerade. Wiederhole in ein paar Sekunden; hält es minutenlang an, bereite einen neuen Upload vor.
  • 429 too_many_pending_uploads — du hast 20 Uploads, die auf ihren Abschluss warten. Schließe sie ab oder warte, bis nicht abgeschlossene ablaufen (siehe Retry-After).

​
Scope und Eigentum

Beide Endpoints akzeptieren einen Key mit einem der Scopes images.edit, images.transform oder videos.generate — den Scopes der Operationen, die eine Quell-image_id entgegennehmen. Es gibt keinen eigenen Upload-Scope, daher funktionieren bestehende Keys. Ein Key ohne einen der drei erhält 403 missing_scope. Das hochgeladene Bild gehört dem aufrufenden Nutzer — dem Ersteller des API-Keys oder dem Nutzer eines OAuth-Tokens. Andere Mitglieder deiner Organisation können seine image_id nicht nutzen.

​
Provenienz

Ein hochgeladenes Bild wird nicht als KI-generiert gekennzeichnet: Samsa hat es nicht erzeugt. Ein Bild, das eine Samsa-Operation aus einem Upload erzeugt, ist ein KI-bearbeiteter Output und wird wie jeder andere Edit gekennzeichnet — siehe Content-Provenienz.