Skip to main content
Chaque opération qui transforme une image existante — Magic Edit, img2img, variations, redimensionnement, upscale, suppression d’arrière-plan et vectorisation — prend son image source de la même manière. Cette page couvre les trois modes d’entrée, leurs limites et la façon dont le serveur récupère une URL.

​
Les trois modes de source

En REST, chaque image source est exactement l’une des suivantes :

image_id

Une image que le créateur de la clé a générée, éditée ou téléversée dans Samsa. Aucun téléversement nécessaire ; le serveur la lit par id. L’image d’un autre membre n’est pas lisible par ta clé.

url

Une URL https publique que le serveur télécharge sous sa protection SSRF. Voir Récupération des URL ci-dessous.

base64

Octets d’image en ligne, envoyés en base64 avec un mime_type.
Fournis une seule par source. N’en envoyer aucune, ou plusieurs, est un 422 validation_error.
Exemples de source

​
Limites de taille et de format

La limite de 10 Mo porte sur l’image décodée. Pour une source base64, la chaîne encodée est d’abord bornée (une chaîne plus longue décode nécessairement au-delà de la limite), puis les octets décodés sont vérifiés. Des octets qui ne sont pas une image lisible sont rejetés en 422 avant toute facturation. La limite de pixels est indépendante de la limite de taille : une source très compressée peut rester sous 10 Mo et dépasser quand même 32 MP — dans ce cas, POST /images/resizes renvoie un 422 avec param: image avant tout rendu. Cette limite de 33 554 432 pixels pour l’image raster source est spécifique au redimensionnement.

​
Sources multiples (img2img)

La plupart des opérations prennent une seule image source. Img2img accepte 1 à 14 images sources dans une requête — passe-les dans le tableau images, et l’ordre des sources est préservé :
Chaque élément suit la même règle d’un seul choix. Une requête avec plus de sources que le moteur n’autorise est un 422.

​
MCP : image_id ou image_url uniquement

Les outils MCP acceptent une source en image_id ou image_url uniquement — il n’y a pas d’entrée base64 en MCP. Référence plutôt l’image par id ou par URL publique :
Cela s’applique à chaque outil MCP qui prend une image source : edit_image, img2img, create_variations, resize_image, upscale_image, remove_background et vectorize_image.

​
Récupération des URL

Lorsque tu passes une url (REST) ou image_url (MCP), le serveur la télécharge sous une protection SSRF stricte avant de l’utiliser :
  • https uniquement, port 443 uniquement. Tout autre schéma ou port est rejeté.
  • Adresses publiques uniquement. Le nom d’hôte est résolu et chaque IP obtenue est vérifiée ; les plages privées, loopback, link-local et partagées/CGNAT sont refusées.
  • Les redirections sont revalidées. L’auto-suivi est désactivé ; jusqu’à 3 sauts de redirection sont suivis manuellement, et chaque saut est revérifié avec la même protection.
  • Liste blanche de content-type. Seules les réponses jpeg, png et webp sont acceptées, et la limite de 10 Mo est appliquée aux octets diffusés (un Content-Length déclaré n’est jamais cru seul).
  • Budget de temps. Un timeout de connexion d’environ 5 s et un budget global souple d’horloge murale d’environ 30 s couvrent tout le téléchargement, y compris les redirections.
Toute récupération qui échoue à une protection est un 422 validation_error nommant le champ fautif — jamais une erreur serveur. Héberge une source quelque part de publiquement accessible en https, ou envoie-la en base64 (REST).

​
Voir aussi

Tarification

Ce que coûte chaque opération, y compris le tableau par opération.

Serveur MCP

Les mêmes opérations en tant qu’outils — avec la règle de source id/url uniquement.

Erreurs

L’enveloppe d’erreur et chaque code, y compris validation_error.

Opérations d'images

Les six opérations et leurs contrats de requête/réponse complets.