Format du contenu : chaîne simple et tableau d'objets
På denna sida
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étextimage_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
contentaccepte 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