Constraints: Formats, Size, and Limits

Ground Rules

Before integrating Grok vision into your applications, you need to know the technical constraints imposed by the xAI API. Ignoring these limits leads to silent errors or rejected requests that can be hard to debug in production.

Accepted Image Formats

The xAI API accepts two image file formats (three extensions: .jpg, .jpeg, .png):

• JPG (or JPEG) — the most common format for photographs
• PNG — suitable for screenshots, diagrams, and images with text

All other formats are rejected. If you work with WebP, GIF, BMP, TIFF, SVG, or HEIC images, you must convert them before sending:

from PIL import Image

def convert_to_jpeg(source_path, output_path):
    img = Image.open(source_path)
    # Convert to RGB (required for JPEG)
    if img.mode in ("RGBA", "P"):
        img = img.convert("RGB")
    img.save(output_path, "JPEG", quality=90)

Common Pitfall: RGBA Images

PNG files with transparency (alpha channel) are accepted as is. However, if you convert them to JPEG, you must remove the alpha channel first because JPEG does not support transparency.

Maximum Size: 20 MiB

Each image must not exceed 20 MiB (20,971,520 bytes). Beyond this, the API rejects the request.

This limit applies:

• To the downloaded file in the case of a URL
• To the decoded data in the case of Base64 (not the encoded string itself, which is ~33% longer)

Check Size Before Sending

import os

def check_size(image_path, max_mib=20):
    size = os.path.getsize(image_path)
    size_mib = size / (1024 * 1024)

    if size_mib > max_mib:
        raise ValueError(
            f"Image too large: {size_mib:.1f} MiB "
            f"(max {max_mib} MiB)"
        )
    return size_mib

Compress If Necessary

For images close to the limit, you can reduce JPEG quality:

def compress_image(path, quality=80, max_size_mib=20):
    img = Image.open(path)
    buffer = io.BytesIO()
    img.save(buffer, "JPEG", quality=quality)

    while buffer.tell() > max_size_mib * 1024 * 1024 and quality > 20:
        quality -= 10
        buffer = io.BytesIO()
        img.save(buffer, "JPEG", quality=quality)

    buffer.seek(0)
    return buffer

Number of Images per Request: Unlimited

Unlike other vision APIs that limit the number of images per request, the xAI API imposes no limit. You can send as many images as needed in a single request.

However, keep in mind that:

• Each image consumes between 256 and 1792 tokens
• The model’s total context has a maximum size
• More images = higher latency and cost

Practical Recommendation

Even though the limit is theoretically unlimited, stay reasonable:

# Best practice: process in batches
def analyze_batch(images, batch_size=10):
    results = []
    for i in range(0, len(images), batch_size):
        batch = images[i:i + batch_size]
        input_data = []
        for img in batch:
            input_data.append({
                "type": "input_image",
                "image_url": img,
                "detail": "low"
            })
        input_data.append({
            "type": "input_text",
            "text": "Briefly describe each image."
        })

        response = client.responses.create(
            model="grok-4.5",
            input=input_data
        )
        results.append(response)
    return results

Compatible Models

Image understanding is available on grok-4.5 and higher. Earlier models do not support this feature.

Always check the model used in your code:

VISION_MODELS = ["grok-4.5", "grok-4.20-0309-reasoning"]

def supports_vision(model):
    return any(model.startswith(m) for m in VISION_MODELS)

Error Handling

Anticipate errors related to constraints by validating images before sending:

def validate_image(path):
    errors = []

    # Check format
    extension = path.lower().rsplit(".", 1)[-1]
    if extension not in ("jpg", "jpeg", "png"):
        errors.append(f"Unsupported format: {extension}")

    # Check size
    size_mib = os.path.getsize(path) / (1024 * 1024)
    if size_mib > 20:
        errors.append(f"Too large: {size_mib:.1f} MiB (max 20)")

    # Check that it is a real image
    try:
        img = Image.open(path)
        img.verify()
    except Exception:
        errors.append("Corrupted file or not a valid image")

    return errors

Key Takeaways

• Only JPG/JPEG and PNG formats are accepted — convert others
• Maximum size: 20 MiB per image — compress if necessary
• The number of images per request is unlimited but each image consumes tokens
• Only grok-4.5 and higher models support vision
• Always validate images before sending to avoid silent errors