Content format: simple string and object array

Two formats for the content field

The content field of each message accepts two different formats in the xAI Chat Completions API. The choice depends on what you send the model: plain text or multimodal content (text + images).

String format: the most common case

For purely text messages, the content field is a simple string:

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

This is the format you’ll use in the vast majority of cases. It’s simple, readable, and sufficient for all text interactions with Grok.

For the system message, the string format is nearly always used:

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

Array format: multimodal content

When you need to send images along with text, the content field becomes an array of typed objects. Each object has a type field indicating its 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"
      }
    }
  ]
}

Available object types

The content array accepts two object types:

• text: a text block with the text property
• image_url: a reference to an image with the image_url property

You can combine as many objects as needed in a single message. For example, to ask the model to compare two 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"}}
  ]
}

The detail parameter for images

Each image_url object accepts an optional detail parameter that controls the analysis resolution:

• auto: the model automatically chooses the detail level (default value)
• low: fast and economical analysis, sufficient for simple images (icons, basic diagrams)
• high: detailed analysis, recommended for complex images (documents, photographs, interfaces)

{
  "type": "image_url",
  "image_url": {
    "url": "https://example.com/document-scan.jpg",
    "detail": "high"
  }
}

The choice of detail level directly impacts the number of tokens consumed and therefore the cost of the request.

When to use which format?

The rule is simple:

• Text only → string format (simpler, more readable)
• Text + images → array format (required for multimodal)
• Images only → array format with only image_url objects

An array format with a single text object is functionally equivalent to the string format, but unnecessarily verbose:

// Equivalent but unnecessarily complex
{"content": [{"type": "text", "text": "Hello"}]}

// Prefer this form
{"content": "Hello"}

Technical constraints for images

Before sending images to the xAI API, keep these limits in mind:

• Maximum size: 20 MiB per image
• Accepted formats: JPG, JPEG, PNG only (no GIF, WebP, or SVG)
• Count: no limit on the number of images per request
• Compatible models: grok-4.5 and higher only

Images can be provided via a public URL or encoded in base64 within the URL itself (format data:image/jpeg;base64,...).

Key takeaways

• The content field accepts a simple string (text) or an object array (multimodal)
• The array format uses objects with a type field: "text" or "image_url"
• The detail parameter (auto, low, high) controls the analysis resolution for images
• Images are limited to 20 MiB in JPG/PNG and require grok-4.5 or higher
• Use the string format when sending text only—it’s more readable and simpler