Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Indelingsformaat van inhoud: eenvoudige tekenreeks en objectenmatrix

Les 3 van 12 Bijgewerkt op 30 juli 2026 Ontwikkelaar
Op deze pagina
  1. Twee formaten voor het veld content
  2. Tekenreeksformaat: het meest voorkomende geval
  3. Matrixformaat: multimodale inhoud
  4. Wanneer welk formaat gebruiken?
  5. Technische beperkingen voor afbeeldingen
  6. Belangrijkste punten

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 eigenschap text
  • image_url: een verwijzing naar een afbeelding met de eigenschap image_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 content accepteert 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