Téléversement d'images

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, d’un img2img, de variations, d’un redimensionnement, d’un upscale, d’une suppression d’arrière-plan, d’une vectorisation ou d’une génération image-to-video. Le MCP server propose le même flux sous forme de deux outils, prepare_image_upload et complete_image_upload — voir Outils MCP. Les uploads sont gratuits — ils ne coûtent aucun credit.

Les trois étapes

Préparer

Appelle POST /images/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.

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.

Finaliser

Appelle POST /images/uploads/{image_id}/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.

# 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 "<upload_url>"

# 3. Complete within the hour
curl -X POST https://api.samsa.ai/public/v1/images/uploads/<image_id>/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` 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 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 — 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 — 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. 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.

Vue d'ensemble

Points de terminaison

Téléversement d'images

Les trois étapes

Limites

Cycle de vie et erreurs

Scope et propriété

Provenance

​Les trois étapes

​Limites

​Cycle de vie et erreurs

​Scope et propriété

​Provenance

Les trois étapes

Limites

Cycle de vie et erreurs

Scope et propriété

Provenance