Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Format du contenu : chaîne simple et tableau d'objets

Lektion 3 av 12 Uppdaterad 30 juli 2026 Utvecklare
På denna sida
  1. Deux formats pour le champ content
  2. Format chaîne : le cas le plus courant
  3. Format tableau : contenu multimodal
  4. Quand utiliser quel format ?
  5. Contraintes techniques pour les images
  6. Viktiga punkter

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 dépend de ce que tu envoies au modèle : du texte brut ou du contenu multimodal (texte + images).

Format chaîne : le cas le plus courant

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

{
  "role": "user",
  "content": "Explain how a transformer works."
}

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

Pour le message system, le format chaîne est presque toujours utilisé :

{
  "role": "system",
  "content": "You are a software architecture expert. Respond in English with Python code examples."
}

Format tableau : contenu multimodal

Lorsque tu dois envoyer des images accompagnées de texte, le champ content devient un tableau d’objets typés. Chaque objet possède un champ type indiquant sa nature.

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "What does this image show?"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/photo.jpg",
        "detail": "high"
      }
    }
  ]
}

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

Tu peux 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 these two architecture diagrams."},
    {"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 résolution 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, diagrammes 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 jetons consommés et donc le coût de la requête.

Quand utiliser quel format ?

La règle est simple :

  • Texte uniquement → format chaîne (plus simple, plus lisible)
  • Texte + images → format tableau (obligatoire pour le multimodal)
  • Images uniquement → format tableau avec seulement des objets image_url

Un format tableau contenant un seul objet text est fonctionnellement équivalent au format chaîne, mais inutilement verbeux :

// Équivalent mais inutilement complexe
{"content": [{"type": "text", "text": "Hello"}]}

// Préfère cette forme
{"content": "Hello"}

Contraintes techniques pour les images

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

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

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

Viktiga punkter

  • Le champ content accepte une chaîne 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 résolution de l’analyse pour les images
  • Les images sont limitées à 20 MiB en JPG/PNG et nécessitent grok-4.5 ou supérieur
  • Utilise le format chaîne lorsque tu envoies uniquement du texte : c’est plus lisible et plus simple