Vision : analyser des images avec Grok

La compréhension d’images avec Chat Completions

Les modèles Grok (à partir de grok-4.5) intègrent des capacités de vision qui permettent d’analyser, décrire et raisonner sur des images. Cette fonctionnalité s’utilise via le format tableau du champ content, en combinant des objets text et image_url.

Les cas d’usage sont nombreux : extraction de texte depuis des documents scannés (OCR), analyse de graphiques, description d’interfaces utilisateur, comparaison visuelle, ou encore interprétation de schémas techniques.

Envoyer une image via URL

La manière la plus simple est de fournir l’URL publique de l’image :

from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1"
)

response = client.chat.completions.create(
    model="grok-4.20-0309-reasoning",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Décris ce que tu vois sur cette image."},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/photo-architecture.jpg",
                        "detail": "high"
                    }
                }
            ]
        }
    ]
)

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

L’image est téléchargée par les serveurs xAI au moment de la requête. Elle doit être accessible publiquement.

Envoyer une image en base64

Pour les images locales ou privées, utilisez l’encodage base64 :

import base64

def encode_image(image_path: str) -> str:
    with open(image_path, "rb") as f:
        return base64.b64encode(f.read()).decode("utf-8")

image_data = encode_image("capture-ecran.png")

response = client.chat.completions.create(
    model="grok-4.20-0309-reasoning",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Quel est le texte visible sur cette capture ?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/png;base64,{image_data}"
                    }
                }
            ]
        }
    ]
)

Le format de l’URL est data:image/{format};base64,{donnees} où {format} est jpeg, jpg ou png.

Niveaux de détail : auto, low et high

Le paramètre detail contrôle la résolution à laquelle le modèle analyse l’image :

detail: “low”

{
  "type": "image_url",
  "image_url": {
    "url": "https://example.com/icone.png",
    "detail": "low"
  }
}

L’image est réduite à une résolution basse avant l’analyse. C’est le mode le plus rapide et le moins coûteux en tokens. Utilisez-le pour des images simples : icônes, logos, schémas basiques.

detail: “high”

{
  "type": "image_url",
  "image_url": {
    "url": "https://example.com/document-scan.jpg",
    "detail": "high"
  }
}

L’image est analysée à haute résolution. Le modèle peut lire du texte petit, identifier des détails fins et analyser des zones spécifiques. C’est le mode recommandé pour les documents, les captures d’écran et les photographies détaillées.

detail: “auto”

Le modèle choisit automatiquement le niveau de détail en fonction de la taille et de la complexité de l’image. C’est la valeur par défaut si vous omettez le paramètre.

Analyser plusieurs images

Vous pouvez envoyer plusieurs images dans un seul message pour des tâches de comparaison ou d’analyse croisée :

response = client.chat.completions.create(
    model="grok-4.20-0309-reasoning",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Compare ces deux versions du design. Quelles sont les différences ?"},
                {"type": "image_url", "image_url": {"url": "https://example.com/v1.png", "detail": "high"}},
                {"type": "image_url", "image_url": {"url": "https://example.com/v2.png", "detail": "high"}}
            ]
        }
    ]
)

Il n’y a pas de limite sur le nombre d’images par requête, mais chaque image consomme des tokens supplémentaires.

Contraintes techniques

Gardez en tête ces limites lors de l’utilisation de la vision :

• Taille maximale : 20 MiB par image
• Formats supportés : JPG, JPEG et PNG uniquement
• Modèles compatibles : grok-4 et supérieur (les modèles plus anciens ne supportent pas la vision)
• Tokens : les images consomment des tokens qui s’ajoutent au coût textuel de la requête

Points clés à retenir

• La vision s’utilise via le format tableau du champ content avec des objets image_url
• Les images peuvent être envoyées par URL publique ou encodées en base64
• Trois niveaux de détail : auto (défaut), low (rapide/économique) et high (détaillé)
• Taille maximale de 20 MiB par image, formats JPG et PNG uniquement
• Plusieurs images peuvent être envoyées dans un seul message pour des comparaisons