Format du contenu : string simple et tableau d'objets

Deux formats pour le champ content

Le champ content de chaque message accepte deux formats differents dans l’API Chat Completions de xAI. Le choix du format depend de ce que vous envoyez au modele : 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 chaine de caracteres :

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

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

Pour le message system, le format string est quasi systematique :

{
  "role": "system",
  "content": "Tu es un expert en architecture logicielle. Reponds en francais 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 types. Chaque objet possede 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 propriete text
• image_url : une reference a une image avec la propriete image_url

Vous pouvez combiner autant d’objets que necessaire dans un seul message. Par exemple, pour demander au modele 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 parametre detail pour les images

Chaque objet image_url accepte un parametre optionnel detail qui controle la finesse de l’analyse :

• auto : le modele choisit automatiquement le niveau de detail (valeur par defaut)
• low : analyse rapide et economique, suffisante pour des images simples (icones, schemas basiques)
• high : analyse detaillee, recommandee 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 detail impacte directement le nombre de tokens consommes et donc le cout de la requete.

Quand utiliser quel format ?

La regle 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 equivalent 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 a l’API xAI, gardez en tete ces limites :

• Taille maximale : 20 MiB par image
• Formats acceptes : JPG, JPEG, PNG uniquement (pas de GIF, WebP ou SVG)
• Nombre : pas de limite sur le nombre d’images par requete
• Modeles compatibles : grok-4 et superieur uniquement

Les images peuvent etre fournies via une URL publique ou encodees en base64 dans l’URL elle-meme (format data:image/jpeg;base64,...).

Points cles a 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 parametre detail (auto, low, high) controle la finesse d’analyse des images
• Les images sont limitees a 20 MiB en JPG/PNG et necessitent grok-4 ou superieur
• Utilisez le format string quand vous n’envoyez que du texte — c’est plus lisible et plus simple