Contraintes : formats, taille et limites

Les règles du jeu

Avant d’intégrer la vision de Grok dans vos applications, vous devez connaître les contraintes techniques imposées par l’API xAI. Ignorer ces limites entraîne des erreurs silencieuses ou des rejets de requêtes qui peuvent être difficiles à déboguer en production.

Formats d’images acceptés

L’API xAI accepte trois formats de fichiers image :

• JPG (ou JPEG) — le format le plus courant pour les photographies
• PNG — adapté aux captures d’écran, diagrammes et images avec du texte

Tous les autres formats sont rejetés. Si vous travaillez avec des images en WebP, GIF, BMP, TIFF, SVG ou HEIC, vous devez les convertir avant l’envoi :

from PIL import Image

def convertir_en_jpeg(chemin_source, chemin_sortie):
    img = Image.open(chemin_source)
    # Convertir en RGB (nécessaire pour JPEG)
    if img.mode in ("RGBA", "P"):
        img = img.convert("RGB")
    img.save(chemin_sortie, "JPEG", quality=90)

Piège courant : les images RGBA

Les fichiers PNG avec transparence (canal alpha) sont acceptés tels quels. En revanche, si vous les convertissez en JPEG, vous devez d’abord retirer le canal alpha car JPEG ne supporte pas la transparence.

Taille maximale : 20 MiB

Chaque image ne doit pas dépasser 20 MiB (20 971 520 octets). Au-delà, l’API rejette la requête.

Cette limite s’applique :

• Au fichier téléchargé dans le cas d’une URL
• Aux données décodées dans le cas du Base64 (pas la chaîne encodée elle-même, qui est ~33% plus longue)

Vérifier la taille avant l’envoi

import os

def verifier_taille(chemin_image, max_mib=20):
    taille = os.path.getsize(chemin_image)
    taille_mib = taille / (1024 * 1024)

    if taille_mib > max_mib:
        raise ValueError(
            f"Image trop lourde : {taille_mib:.1f} MiB "
            f"(max {max_mib} MiB)"
        )
    return taille_mib

Compresser si nécessaire

Pour les images proches de la limite, vous pouvez réduire la qualité JPEG :

def compresser_image(chemin, qualite=80, taille_max_mib=20):
    img = Image.open(chemin)
    buffer = io.BytesIO()
    img.save(buffer, "JPEG", quality=qualite)

    while buffer.tell() > taille_max_mib * 1024 * 1024 and qualite > 20:
        qualite -= 10
        buffer = io.BytesIO()
        img.save(buffer, "JPEG", quality=qualite)

    buffer.seek(0)
    return buffer

Nombre d’images par requête : illimité

Contrairement à d’autres API de vision qui limitent le nombre d’images par requête, l’API xAI n’impose aucune limite. Vous pouvez envoyer autant d’images que nécessaire dans une seule requête.

Cependant, gardez à l’esprit que :

• Chaque image consomme entre 256 et 1792 tokens
• Le contexte total du modèle a une taille maximale
• Plus d’images = latence plus élevée et coût plus important

Recommandation pratique

Même si la limite est théoriquement illimitée, restez raisonnable :

# Bonne pratique : traiter par lots
def analyser_lot(images, taille_lot=10):
    resultats = []
    for i in range(0, len(images), taille_lot):
        lot = images[i:i + taille_lot]
        input_data = []
        for img in lot:
            input_data.append({
                "type": "input_image",
                "image_url": img,
                "detail": "low"
            })
        input_data.append({
            "type": "input_text",
            "text": "Décris brièvement chaque image."
        })

        response = client.responses.create(
            model="grok-4",
            input=input_data
        )
        resultats.append(response)
    return resultats

Modèles compatibles

La compréhension d’images est disponible sur grok-4 et supérieur. Les modèles antérieurs ne supportent pas cette fonctionnalité.

Vérifiez toujours le modèle utilisé dans votre code :

MODELES_VISION = ["grok-4", "grok-4.20-reasoning"]

def supporter_vision(modele):
    return any(modele.startswith(m) for m in MODELES_VISION)

Gestion des erreurs

Anticipez les erreurs liées aux contraintes en validant les images avant l’envoi :

def valider_image(chemin):
    erreurs = []

    # Vérifier le format
    extension = chemin.lower().rsplit(".", 1)[-1]
    if extension not in ("jpg", "jpeg", "png"):
        erreurs.append(f"Format non supporté : {extension}")

    # Vérifier la taille
    taille_mib = os.path.getsize(chemin) / (1024 * 1024)
    if taille_mib > 20:
        erreurs.append(f"Trop lourd : {taille_mib:.1f} MiB (max 20)")

    # Vérifier que c'est une vraie image
    try:
        img = Image.open(chemin)
        img.verify()
    except Exception:
        erreurs.append("Fichier corrompu ou pas une image valide")

    return erreurs

Points clés à retenir

• Seuls les formats JPG/JPEG et PNG sont acceptés — convertissez les autres
• Taille maximale : 20 MiB par image — compressez si nécessaire
• Le nombre d’images par requête est illimité mais chaque image consomme des tokens
• Seuls les modèles grok-4 et supérieur supportent la vision
• Validez toujours les images avant l’envoi pour éviter les erreurs silencieuses