Indelingsformaat van inhoud: eenvoudige tekenreeks en objectenmatrix
Op deze pagina
Twee formaten voor het veld content
Het veld content van elk bericht accepteert twee verschillende formaten in de xAI Chat Completions API. De keuze hangt af van wat u naar het model stuurt: platte tekst of multimodale inhoud (tekst + afbeeldingen).
Tekenreeksformaat: het meest voorkomende geval
Voor puur tekstberichten is het veld content een eenvoudige tekenreeks:
{
"role": "user",
"content": "Explain how a transformer works."
}
Dit is het formaat dat u in de overgrote meerderheid van de gevallen zult gebruiken. Het is eenvoudig, leesbaar en voldoende voor alle tekstinteracties met Grok.
Voor het system-bericht wordt bijna altijd het tekenreeksformaat gebruikt:
{
"role": "system",
"content": "You are a software architecture expert. Respond in English with Python code examples."
}
Matrixformaat: multimodale inhoud
Wanneer u afbeeldingen samen met tekst moet verzenden, wordt het veld content een matrix van getypeerde objecten. Elk object heeft een veld type dat de aard ervan aangeeft.
{
"role": "user",
"content": [
{
"type": "text",
"text": "What does this image show?"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/photo.jpg",
"detail": "high"
}
}
]
}
Beschikbare objecttypen
De inhoudsmatrix accepteert twee objecttypen:
text: een tekstblok met de eigenschaptextimage_url: een verwijzing naar een afbeelding met de eigenschapimage_url
U kunt zoveel objecten combineren als nodig is in één bericht. Om het model bijvoorbeeld te vragen twee afbeeldingen te vergelijken:
{
"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"}}
]
}
De parameter detail voor afbeeldingen
Elk image_url-object accepteert een optionele parameter detail die de analyseresolutie bepaalt:
auto: het model kiest automatisch het detailniveau (standaardwaarde)low: snelle en zuinige analyse, voldoende voor eenvoudige afbeeldingen (pictogrammen, basisdiagrammen)high: gedetailleerde analyse, aanbevolen voor complexe afbeeldingen (documenten, foto’s, interfaces)
{
"type": "image_url",
"image_url": {
"url": "https://example.com/document-scan.jpg",
"detail": "high"
}
}
De keuze van het detailniveau heeft directe invloed op het aantal verbruikte tokens en dus op de kosten van het verzoek.
Wanneer welk formaat gebruiken?
De regel is eenvoudig:
- Alleen tekst → tekenreeksformaat (eenvoudiger, leesbaarder)
- Tekst + afbeeldingen → matrixformaat (vereist voor multimodaal)
- Alleen afbeeldingen → matrixformaat met alleen
image_url-objecten
Een matrixformaat met één enkel text-object is functioneel equivalent aan het tekenreeksformaat, maar onnodig uitgebreid:
// Equivalent maar onnodig complex
{"content": [{"type": "text", "text": "Hello"}]}
// Geef de voorkeur aan deze vorm
{"content": "Hello"}
Technische beperkingen voor afbeeldingen
Houd rekening met deze limieten voordat u afbeeldingen naar de xAI API stuurt:
- Maximale grootte: 20 MiB per afbeelding
- Geaccepteerde formaten: alleen JPG, JPEG, PNG (geen GIF, WebP of SVG)
- Aantal: geen limiet op het aantal afbeeldingen per verzoek
- Compatibele modellen: alleen grok-4.5 en hoger
Afbeeldingen kunnen worden aangeleverd via een openbare URL of base64-gecodeerd binnen de URL zelf (formaat data:image/jpeg;base64,...).
Belangrijkste punten
- Het veld
contentaccepteert een eenvoudige tekenreeks (tekst) of een objectenmatrix (multimodaal) - Het matrixformaat gebruikt objecten met een veld
type:"text"of"image_url" - De parameter
detail(auto,low,high) bepaalt de analyseresolutie voor afbeeldingen - Afbeeldingen zijn beperkt tot 20 MiB in JPG/PNG en vereisen grok-4.5 of hoger
- Gebruik het tekenreeksformaat wanneer u alleen tekst verstuurt; dit is leesbaarder en eenvoudiger