Detail parameter: auto, low, and high

Control analysis precision

When you send an image to Grok, you can control the analysis detail level using the detail parameter. This parameter directly affects response quality, processing time, and token consumption.

Understanding this parameter is crucial for optimizing costs and matching precision to each use case.

The three detail levels

The xAI API offers three values for the detail parameter:

Auto (default value)

When you don’t specify the detail parameter, the model uses auto. It automatically evaluates the necessary detail level based on the image and your prompt.

{
  "type": "input_image",
  "image_url": "https://exemple.com/photo.jpg"
}

This is the recommended behavior for most use cases. The model adapts its analysis strategy based on the perceived complexity of the image and the question asked.

Low (fast and economical)

The low mode performs a quick image analysis using fewer tokens. This is the ideal choice when you need a general understanding without going into fine details.

{
  "type": "input_image",
  "image_url": "https://exemple.com/photo.jpg",
  "detail": "low"
}

Use cases for low:

• Classify image content (landscape, portrait, document, etc.)
• Identify the main subject of a photo
• Quickly sort a batch of images
• Check if an image matches a simple criterion

High (slow and detailed)

The high mode forces an exhaustive image analysis. The model examines every zone at maximum resolution, which consumes more tokens but produces much more precise descriptions.

{
  "type": "input_image",
  "image_url": "https://exemple.com/photo.jpg",
  "detail": "high"
}

Use cases for high:

• Read fine text in an image (OCR)
• Analyze charts with detailed legends
• Detect defects in product photos
• Examine screenshots of complex interfaces

Compare the levels

Syntax by API

The detail parameter is placed differently depending on the API used.

Responses API (recommended)

response = client.responses.create(
    model="grok-4.5",
    input=[
        {
            "type": "input_image",
            "image_url": "https://exemple.com/photo.jpg",
            "detail": "high"
        },
        {
            "type": "input_text",
            "text": "Read all visible text in this image."
        }
    ]
)

Chat Completions API (legacy)

response = client.chat.completions.create(
    model="grok-4.5",
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://exemple.com/photo.jpg",
                    "detail": "high"
                }
            },
            {
                "type": "text",
                "text": "Read all visible text in this image."
            }
        ]
    }]
)

Note that in Chat Completions, detail is nested inside the image_url object, whereas in the Responses API it is at the same level as image_url.

Optimization strategy

In production, a best practice is to adapt the detail level based on the task type:

def analyser_image(image_url, tache):
    # Simple tasks → low to save costs
    if tache in ["classifier", "trier", "identifier_sujet"]:
        detail = "low"
    # Complex tasks → high for precision
    elif tache in ["ocr", "graphique", "defaut_produit"]:
        detail = "high"
    # Default → let the model decide
    else:
        detail = "auto"

    return client.responses.create(
        model="grok-4.5",
        input=[
            {"type": "input_image", "image_url": image_url, "detail": detail},
            {"type": "input_text", "text": f"Task: {tache}"}
        ]
    )

This approach lets you significantly reduce token costs on simple tasks while maintaining maximum precision where necessary.

Key takeaways

• The detail parameter controls the depth of image analysis
• auto (default) lets the model decide—this is the recommended choice
• low is fast and economical, suitable for classification tasks
• high is slow but precise, suitable for OCR and fine-grained analysis
• Adapt the detail level to the task type to optimize costs