Une image refusée par une API multimodale a presque toujours une cause banale. Format, chemin contre base64, taille ou media_type mal déclaré. Méthode de diagnostic ordonnée.
Une API multimodale qui rejette une image renvoie souvent un message vague. Pourtant les causes réelles sont peu nombreuses et faciles à isoler. On les vérifie dans un ordre fixe plutôt qu’au hasard.
Format, chemin et encodage
On commence par le format. Beaucoup d’API n’acceptent qu’un sous-ensemble. PNG, JPEG, parfois WebP. Un format exotique ou un fichier mal converti échoue silencieusement. On vérifie l’extension réelle, pas celle du nom.
Vient ensuite la confusion chemin contre base64. Certaines API veulent un chemin ou une URL, d’autres le contenu encodé en base64 dans le corps de la requête. Envoyer un chemin local là où l’API attend du base64 produit une erreur opaque. On lit la spécification du champ exact.
Taille et media_type
La taille est un piège fréquent. Au-delà d’une limite en octets ou en pixels, l’image est rejetée. On redimensionne ou on recompresse avant l’envoi, sans attendre l’erreur côté serveur.
Enfin le media_type. Déclarer image/png pour un JPEG casse le décodage côté API. Le media_type doit correspondre au contenu binaire réel, pas à une supposition. Le principe à retenir. Sur une image refusée, on remonte format, encodage, taille puis media_type avant de soupçonner le modèle.