> ## Documentation Index > Fetch the complete documentation index at: https://docs.samsa.ai/llms.txt > Use this file to discover all available pages before exploring further. # Bild-Uploads > Lade eine lokale Bilddatei hoch und erhalte eine image_id, die du als Quelle in Edits, Bildoperationen und Image-to-Video nutzen kannst. Lade eine lokale Bilddatei zu Samsa hoch und erhalte eine **`image_id`**. Nutze die `image_id` als Quellbild für einen [Magic Edit](/de/api-reference/edits/create.md), [img2img](/de/api-reference/image-ops/img2img.md), [Variationen](/de/api-reference/image-ops/variations.md), [Resize](/de/api-reference/image-ops/resize.md), [Upscale](/de/api-reference/image-ops/upscale.md), [Hintergrundentfernung](/de/api-reference/image-ops/remove-background.md), [Vektorisierung](/de/api-reference/image-ops/vectorize.md) oder eine [Image-to-Video-Generierung](/de/api-reference/videos/generate.md). Der MCP server bietet denselben Flow als zwei Tools, `prepare_image_upload` und `complete_image_upload` — siehe [MCP-Tools](/de/mcp-server/tools.md). Uploads sind **kostenlos** — sie kosten keine Credits. ## Die drei Schritte **1. Vorbereiten** Rufe [`POST /images/uploads/prepare`](/de/api-reference/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`](/de/api-reference/uploads/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. ```bash theme={null} # 1. Prepare: send the EXACT file size curl -X POST https://api.samsa.ai/public/v1/images/uploads/prepare \ -H "Authorization: Bearer $SAMSA_API_KEY" \ -H "Content-Type: application/json" \ -d "{\"filename\": \"photo.png\", \"content_type\": \"image/png\", \"size_bytes\": $(wc -c < photo.png)}" # -> {"image_id": "...", "upload_url": "https://...", "expires_at": "...", "max_bytes": 10485760, "allowed_content_types": [...]} # 2. PUT the raw bytes (same Content-Type, no Authorization header) curl -X PUT -H "Content-Type: image/png" --data-binary @photo.png "" # 3. Complete within the hour curl -X POST https://api.samsa.ai/public/v1/images/uploads//complete \ -H "Authorization: Bearer $SAMSA_API_KEY" # -> {"image_id": "...", "status": "completed", "filename": "photo.png", "content_type": "image/png", "size_bytes": 4718592, "width": 2048, "height": 1536} ``` `curl --data-binary @file` sendet die echte Dateilänge, daher passt sie immer zu `size_bytes`, wenn du dieselbe Datei gemessen hast. ## Limits | Regel | Wert | | - | - | | Akzeptierte Formate | `image/jpeg`, `image/png`, `image/webp` | | Max. Dateigröße | **10 MB** (10.485.760 Bytes) | | Max. Pixel | **32 MP** (33.554.432 Pixel, Breite × Höhe) | | `size_bytes` | Erforderlich. Die exakte Dateigröße — sie wird in die `upload_url` signiert, daher wird ein `PUT` mit jeder anderen Länge abgelehnt | | Gültigkeit der `upload_url` | **1 Stunde** — rufe complete innerhalb dieser Stunde auf | | Uploads, die auf ihren Abschluss warten | Höchstens **20** pro Nutzer ([`429 too_many_pending_uploads`](/de/guides/errors#too_many_pending_uploads) darüber) | 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`](/de/guides/errors#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`](/de/guides/errors#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`](/de/guides/errors#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`](/de/guides/errors#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](/de/guides/content-provenance.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.