Format du contenu : string simple et tableau d'objets

Deux formats pour le champ content

Le champ content de chaque message accepte deux formats différents dans l’API Chat Completions de xAI. Le choix du format dépend de ce que vous envoyez au modèle : du texte simple ou un contenu multimodal (texte + images).

Format string : le cas le plus courant

Pour les messages purement textuels, le champ content est une simple chaîne de caractères :

{
  "role": "user",
  "content": "Explique-moi le fonctionnement d'un transformer."
}

C’est le format que vous utiliserez dans la grande majorité des cas. Il est simple, lisible et suffisant pour toutes les interactions textuelles avec Grok.

Pour le message system, le format string est quasi systématique :

{
  "role": "system",
  "content": "Tu es un expert en architecture logicielle. Réponds en français avec des exemples de code Python."
}

Format tableau : contenu multimodal

Quand vous devez envoyer des images en plus du texte, le champ content devient un tableau d’objets typés. Chaque objet possède un champ type qui indique sa nature.

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "Que montre cette image ?"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/photo.jpg",
        "detail": "high"
      }
    }
  ]
}

Les types d’objets disponibles

Le tableau de contenu accepte deux types d’objets :

• text : un bloc de texte avec la propriété text
• image_url : une référence à une image avec la propriété image_url

Vous pouvez combiner autant d’objets que nécessaire dans un seul message. Par exemple, pour demander au modèle de comparer deux images :

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Compare ces deux schemas d'architecture."},
    {"type": "image_url", "image_url": {"url": "https://example.com/schema-v1.png"}},
    {"type": "image_url", "image_url": {"url": "https://example.com/schema-v2.png"}}
  ]
}

Le paramètre detail pour les images

Chaque objet image_url accepte un paramètre optionnel detail qui contrôle la finesse de l’analyse :

• auto : le modèle choisit automatiquement le niveau de détail (valeur par défaut)
• low : analyse rapide et économique, suffisante pour des images simples (icônes, schémas basiques)
• high : analyse détaillée, recommandée pour les images complexes (documents, photographies, interfaces)

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

Le choix du niveau de détail impacte directement le nombre de tokens consommés et donc le coût de la requête.

Quand utiliser quel format ?

La règle est simple :

• Texte uniquement → format string (plus simple, plus lisible)
• Texte + images → format tableau (obligatoire pour le multimodal)
• Images seules → format tableau avec uniquement des objets image_url

Le format tableau avec un seul objet text est fonctionnellement équivalent au format string, mais inutilement verbeux :

// Equivalent mais inutilement complexe
{"content": [{"type": "text", "text": "Bonjour"}]}

// Preferez cette forme
{"content": "Bonjour"}

Contraintes techniques des images

Avant d’envoyer des images à l’API xAI, gardez en tête ces limites :

• Taille maximale : 20 MiB par image
• Formats acceptés : JPG, JPEG, PNG uniquement (pas de GIF, WebP ou SVG)
• Nombre : pas de limite sur le nombre d’images par requête
• Modèles compatibles : grok-4.5 et supérieur uniquement

Les images peuvent être fournies via une URL publique ou encodées en base64 dans l’URL elle-même (format data:image/jpeg;base64,...).

Points clés à retenir

• Le champ content accepte une string simple (texte) ou un tableau d’objets (multimodal)
• Le format tableau utilise des objets avec un champ type : "text" ou "image_url"
• Le paramètre detail (auto, low, high) contrôle la finesse d’analyse des images
• Les images sont limitées à 20 MiB en JPG/PNG et nécessitent grok-4.5 ou supérieur
• Utilisez le format string quand vous n’envoyez que du texte — c’est plus lisible et plus simple