Envoyer une Image par URL — Vision et Analyse d'Images via l'API

La méthode la plus simple

Envoyer une image par URL est la manière la plus directe d’utiliser la Vision API : vous fournissez l’adresse d’une image accessible publiquement, et Mistral la télécharge pour l’analyser. Votre requête reste légère, quelques centaines d’octets, puisqu’elle ne transporte qu’un lien.

C’est la méthode à privilégier quand vos images sont déjà hébergées — CDN, stockage cloud, site web — ou quand vous travaillez sur des images publiques du web. Une équipe qui stocke déjà ses visuels produits sur un CDN n’a rien à changer à son infrastructure pour commencer à les analyser.

Format du message

Le message multimodal avec une URL d’image suit cette structure :

message = {
    "role": "user",
    "content": [
        {
            "type": "text",
            "text": "Votre question sur l'image"
        },
        {
            "type": "image_url",
            "image_url": "https://exemple.com/mon-image.jpg"
        }
    ]
}

Le champ image_url accepte toute URL HTTP ou HTTPS pointant vers un fichier image valide, aux formats JPEG, PNG, GIF ou WebP.

Exemple complet en Python

Voici un script complet, exécutable tel quel dès que votre clé est dans l’environnement, qui analyse une image publique de Wikimedia :

from mistralai import Mistral
import os

# Initialisation du client
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Image publique à analyser
url_image = "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a7/Camponotus_flavomarginatus_ant.jpg/800px-Camponotus_flavomarginatus_ant.jpg"

# Appel à l'API Vision
response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Décrivez précisément ce que vous voyez dans cette image."
                },
                {
                    "type": "image_url",
                    "image_url": url_image
                }
            ]
        }
    ]
)

print(response.choices[0].message.content)

Notez le passage de la clé par os.environ plutôt qu’en dur dans le code : c’est la seule forme acceptable dès que le script quitte votre machine.

Ajouter un prompt système

La réponse obtenue ci-dessus sera correcte mais générique — « une fourmi noire sur fond flou ». Le message système change la nature de l’analyse en assignant un rôle au modèle avant qu’il ne regarde l’image :

response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {
            "role": "system",
            "content": "Vous êtes un expert en entomologie. Analysez les images d'insectes avec précision scientifique, en identifiant l'espèce, la famille et les caractéristiques morphologiques visibles."
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Identifiez cet insecte."},
                {"type": "image_url", "image_url": url_image}
            ]
        }
    ]
)

Avec ce cadrage, la même image produit une identification taxonomique et une description morphologique. Le prompt système guide le modèle dans sa manière d’analyser l’image — c’est un levier puissant pour obtenir des réponses spécialisées, et il coûte quelques dizaines de tokens.

Conditions requises pour l’URL

L’API doit pouvoir télécharger l’image sans aucun contexte de votre session. Quatre conditions en découlent : l’URL doit être accessible publiquement, donc pas de page derrière une authentification ; elle doit pointer directement vers le fichier, et non vers une page HTML qui contient l’image ; le format doit faire partie des formats supportés (JPEG, PNG, GIF dont seule la première frame est lue, WebP) ; et la taille doit rester raisonnable, sous les 20 Mo.

La confusion la plus fréquente est celle du lien de partage. Un lien Google Drive ou Dropbox « partagé avec tous » renvoie une page HTML, pas un fichier image : l’appel échoue ou le modèle décrit une interface web. Le réflexe est de vérifier le Content-Type avant d’envoyer :

import requests

def verifier_url_image(url):
    """Vérifie qu'une URL pointe vers une image accessible."""
    try:
        response = requests.head(url, timeout=5, allow_redirects=True)
        content_type = response.headers.get("Content-Type", "")

        if response.status_code == 200 and "image" in content_type:
            taille = int(response.headers.get("Content-Length", 0))
            print(f"Image accessible : {content_type}, {taille / 1024:.0f} Ko")
            return True
        else:
            print(f"Problème : status={response.status_code}, type={content_type}")
            return False
    except requests.RequestException as e:
        print(f"Erreur de connexion : {e}")
        return False

verifier_url_image("https://exemple.com/photo.jpg")

Une requête HEAD suffit : elle récupère les en-têtes sans télécharger le fichier.

Images depuis un stockage cloud

Cette exigence d’accessibilité publique semble incompatible avec des documents confidentiels. La solution tient dans les URL pré-signées : si vos images sont dans un bucket S3, Google Cloud Storage ou Azure Blob, vous générez une adresse temporaire qui donne accès à un seul objet, pour une durée que vous fixez.

import boto3

s3 = boto3.client("s3")

# Générer une URL pré-signée valide 1 heure
url_presignee = s3.generate_presigned_url(
    "get_object",
    Params={"Bucket": "mon-bucket", "Key": "images/facture.png"},
    ExpiresIn=3600
)

# Utiliser cette URL avec l'API Vision
response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Extrayez le montant total de cette facture."},
                {"type": "image_url", "image_url": url_presignee}
            ]
        }
    ]
)

Votre bucket reste privé, l’URL expire après le délai spécifié, et vous conservez la légèreté de la requête. Ajustez ExpiresIn au plus court : quelques minutes suffisent largement pour un appel API.

Gestion des erreurs

Un appel qui dépend d’un téléchargement distant peut échouer pour des raisons qui vous échappent — image supprimée, URL expirée, serveur d’hébergement indisponible. En production, ne laissez jamais l’exception remonter brute jusqu’à l’utilisateur :

from mistralai import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

try:
    response = client.chat.complete(
        model="mistral-small-latest",
        messages=[
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": "Décrivez cette image."},
                    {"type": "image_url", "image_url": "https://exemple.com/image.jpg"}
                ]
            }
        ]
    )
    print(response.choices[0].message.content)
except Exception as e:
    print(f"Erreur : {e}")

Testez votre gestion d’erreur avec une URL volontairement fausse avant de déployer : c’est le scénario le plus fréquent et le moins souvent essayé.

Points clés à retenir

L’envoi par URL est la méthode la plus simple — une URL publique suffit
Le champ content du message est un tableau contenant des éléments text et image_url
L’URL doit pointer directement vers un fichier image accessible
Les URL pré-signées permettent d’utiliser des images privées en toute sécurité
Ajoutez toujours un prompt système pour guider l’analyse du modèle