Formats d'images : URL et Base64

Corrigé le 3 novembre 2026. Avec l’API Responses, les objets input_image et input_text se placent dans le content d’un message {"role": "user", ...}, et non directement dans input. L’exemple Python appelait client.responses.create() sur le client de xai-sdk, qui n’a pas cette méthode, et écrivait la clé d’API dans le code : il utilise maintenant user(...) et image(...) du SDK, avec la clé lue dans l’environnement. Ajout de la mise en garde de xAI sur le stockage de l’historique. Code vérifié avec xai-sdk 1.21.0. Source : Image Understanding.

Envoyer des images à Grok

Les modèles Grok à partir de grok-4.5 intègrent des capacités de vision. Vous pouvez envoyer une ou plusieurs images dans vos requêtes API et le modèle les analysera pour répondre à vos questions. C’est ce qu’on appelle la compréhension d’images, ou vision multimodale.

Avant de plonger dans les cas d’usage, il est essentiel de maîtriser les deux formats d’envoi d’images supportés par l’API xAI.

URL directe

La méthode la plus simple consiste à fournir l’URL publique d’une image. Le modèle la téléchargera et l’analysera automatiquement.

Avec l’API Responses (endpoint principal) :

{
  "model": "grok-4.5",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_image",
          "image_url": "https://exemple.com/photo-produit.jpg"
        },
        {
          "type": "input_text",
          "text": "Décris cette image en détail."
        }
      ]
    }
  ]
}

xAI conseille, quand vous envoyez des images, de ne pas faire stocker l’historique de la requête et de la réponse sur ses serveurs, faute de quoi la requête peut échouer : avec l’API Responses, passez "store": false.

Avec l’API Chat Completions (legacy, compatible OpenAI) :

{
  "model": "grok-4.5",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "https://exemple.com/photo-produit.jpg"
          }
        },
        {
          "type": "text",
          "text": "Décris cette image en détail."
        }
      ]
    }
  ]
}

L’URL doit pointer vers un fichier image accessible publiquement. Si l’image est derrière une authentification ou un CDN protégé, utilisez plutôt le format Base64.

Base64 encodé (Data URI)

Le second format consiste à encoder l’image directement dans la requête sous forme de chaîne Base64 précédée d’un préfixe MIME. C’est la méthode idéale quand vous travaillez avec des images locales, des captures d’écran ou des fichiers générés dynamiquement.

{
  "type": "input_image",
  "image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
}

Le préfixe data:image/jpeg;base64, indique au modèle le type MIME de l’image. Adaptez-le selon le format :

• data:image/jpeg;base64, pour les fichiers JPG/JPEG
• data:image/png;base64, pour les fichiers PNG

Encoder une image en Python

import base64

with open("photo.jpg", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

image_url = f"data:image/jpeg;base64,{image_data}"

Encoder en JavaScript/Node.js

import { readFileSync } from 'fs';

const imageData = readFileSync('photo.jpg').toString('base64');
const imageUrl = `data:image/jpeg;base64,${imageData}`;

Différences clés entre URL et Base64

Mixer texte et images

Le content d’un message accepte un tableau mixte d’objets input_image et input_text, dans n’importe quel ordre : vous pouvez alterner librement texte et images. Avec le SDK natif de xAI, le même message se construit avec user(), qui accepte à la suite du texte et des images créées par image() :

from xai_sdk import Client
from xai_sdk.chat import image, user

client = Client()  # clé lue dans XAI_API_KEY

chat = client.chat.create(model="grok-4.5")
chat.append(
    user(
        "Compare ces deux photos :",
        image(image_url="https://exemple.com/photo1.jpg", detail="high"),
        image(image_url="https://exemple.com/photo2.jpg", detail="high"),
        "Quelles sont les différences principales ?",
    )
)

response = chat.sample()
print(response.content)

image() accepte une URL publique comme une Data URI Base64.

Points clés à retenir

• Deux formats d’images sont supportés : URL directe et Base64 (Data URI)
• Les formats acceptés sont JPG, JPEG et PNG uniquement
• Chaque image ne doit pas dépasser 20 MiB
• Le nombre d’images par requête est illimité
• L’API Responses place des input_image dans le content d’un message ; Chat Completions utilise des parties image_url ; le SDK xAI, image() dans user()
• Privilégiez l’URL pour les images publiques et le Base64 pour les fichiers locaux