> ## 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. # Téléversement d'images > Téléverse un fichier image local pour obtenir un image_id à utiliser comme source dans les éditions, les opérations d'images et l'image-to-video. Téléverse un fichier image local vers Samsa et obtiens un **`image_id`**. Utilise l'`image_id` comme image source d'un [Magic Edit](/fr/api-reference/edits/create.md), d'un [img2img](/fr/api-reference/image-ops/img2img.md), de [variations](/fr/api-reference/image-ops/variations.md), d'un [redimensionnement](/fr/api-reference/image-ops/resize.md), d'un [upscale](/fr/api-reference/image-ops/upscale.md), d'une [suppression d'arrière-plan](/fr/api-reference/image-ops/remove-background.md), d'une [vectorisation](/fr/api-reference/image-ops/vectorize.md) ou d'une [génération image-to-video](/fr/api-reference/videos/generate.md). Le MCP server propose le même flux sous forme de deux outils, `prepare_image_upload` et `complete_image_upload` — voir [Outils MCP](/fr/mcp-server/tools.md). Les uploads sont **gratuits** — ils ne coûtent aucun credit. ## Les trois étapes **1. Préparer** Appelle [`POST /images/uploads/prepare`](/fr/api-reference/uploads/prepare) avec le `filename`, le `content_type` et la taille **exacte** du fichier dans `size_bytes`. La réponse te donne l'`image_id` et une `upload_url` presignée. **2. PUT du fichier** Fais un `PUT` des octets bruts du fichier vers `upload_url` avec le même `Content-Type`. N'envoie pas d'en-tête `Authorization` vers cette URL. **3. Finaliser** Appelle [`POST /images/uploads/{image_id}/complete`](/fr/api-reference/uploads/complete) dans l'heure. Samsa vérifie le fichier et renvoie l'image avec sa `width` et sa `height` mesurées. L'`image_id` est utilisable à partir de ce moment. ```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` envoie la longueur réelle du fichier, donc elle correspond toujours à `size_bytes` si tu as mesuré le même fichier. ## Limites | Règle | Valeur | | - | - | | Formats acceptés | `image/jpeg`, `image/png`, `image/webp` | | Taille max. du fichier | **10 Mo** (10 485 760 octets) | | Pixels max. | **32 MP** (33 554 432 pixels, largeur × hauteur) | | `size_bytes` | Requis. La taille exacte du fichier — elle est signée dans `upload_url`, donc un `PUT` de toute autre longueur est rejeté | | Validité de `upload_url` | **1 heure** — appelle complete dans cette heure | | Uploads en attente de finalisation | Au plus **20** par utilisateur ([`429 too_many_pending_uploads`](/fr/guides/errors#too_many_pending_uploads) au-delà) | Le fichier doit être au format que tu as déclaré dans `content_type`. `width` et `height` sont des indications optionnelles au moment du prepare : Samsa ne les utilise que pour refuser tôt une image de plus de 32 MP. Les dimensions stockées sont toujours mesurées à partir des octets téléversés. Un upload jamais finalisé est supprimé après l'expiration de son URL. ## Cycle de vie et erreurs * **Inutilisable avant complete.** Tant que complete n'a pas réussi, l'`image_id` renvoie [`404 not_found`](/fr/guides/errors#not_found) partout. * **Complete est idempotent.** Le rappeler renvoie le même résultat et ne change rien. Un `PUT` ultérieur vers la même `upload_url` ne remplace pas une image finalisée. * **`422 validation_error`** — il n'y a pas encore de fichier, ou le fichier est vide, a une taille différente de `size_bytes`, est trop grand, est illisible, est d'un autre format ou dépasse 32 MP. Samsa supprime un fichier refusé : fais un `PUT` d'un fichier valide vers la même `upload_url` tant qu'elle est valide, puis rappelle complete. * **`404 not_found`** — l'`image_id` est inconnu, expiré, appartient à un autre utilisateur, ou n'a pas été créé par prepare. * **[`409 upload_in_progress`](/fr/guides/errors#upload_in_progress)** — un autre appel complete pour le même upload est en cours. Réessaie dans quelques secondes ; si cela dure plusieurs minutes, prépare un nouvel upload. * **[`429 too_many_pending_uploads`](/fr/guides/errors#too_many_pending_uploads)** — tu as 20 uploads en attente de finalisation. Finalise-les, ou attends que ceux non finalisés expirent (voir `Retry-After`). ## Scope et propriété Les deux endpoints acceptent une clé avec **l'un** des scopes `images.edit`, `images.transform` ou `videos.generate` — les scopes des opérations qui prennent un `image_id` source. Il n'y a pas de scope d'upload séparé, donc les clés existantes fonctionnent. Une clé sans aucun des trois reçoit [`403 missing_scope`](/fr/guides/errors#missing_scope). L'image téléversée appartient à l'**utilisateur appelant** — le créateur de la clé API, ou l'utilisateur d'un token OAuth. Les autres membres de ton organisation ne peuvent pas utiliser son `image_id`. ## Provenance Une image téléversée n'est **pas** marquée comme générée par IA : Samsa ne l'a pas produite. Une image qu'une opération Samsa produit à partir d'un upload est une sortie modifiée par IA et est marquée comme toute autre édition — voir [Provenance du contenu](/fr/guides/content-provenance.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.