Beperkingen: Indelingen, Grootte en Limieten
Op deze pagina
Basisregels
Voordat u Grok Vision in uw toepassingen integreert, moet u bekend zijn met de technische beperkingen die de xAI API oplegt. Het negeren van deze limieten leidt tot stille fouten of geweigerde verzoeken die in productie lastig te debuggen zijn.
Geaccepteerde Afbeeldingsindelingen
De xAI API accepteert twee afbeeldingsbestandsindelingen (drie extensies: .jpg, .jpeg, .png):
- JPG (of JPEG) — de meest voorkomende indeling voor foto’s
- PNG — geschikt voor screenshots, diagrammen en afbeeldingen met tekst
Alle andere indelingen worden geweigerd. Als u werkt met WebP-, GIF-, BMP-, TIFF-, SVG- of HEIC-afbeeldingen, moet u deze converteren voordat u ze verzendt:
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)
Veelgemaakte Fout: RGBA-afbeeldingen
PNG-bestanden met transparantie (alfakanaal) worden zonder meer geaccepteerd. Als u ze echter naar JPEG converteert, moet u eerst het alfakanaal verwijderen, omdat JPEG geen transparantie ondersteunt.
Maximale Grootte: 20 MiB
Elke afbeelding mag niet groter zijn dan 20 MiB (20.971.520 bytes). Daarboven weigert de API het verzoek.
Deze limiet is van toepassing op:
- Het gedownloade bestand in het geval van een URL
- De gedecodeerde gegevens in het geval van Base64 (niet de gecodeerde string zelf, die ongeveer 33% langer is)
Controleer de Grootte Voor Verzending
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
Comprimeer Indien Nodig
Voor afbeeldingen die dicht bij de limiet zitten, kunt u de JPEG-kwaliteit verlagen:
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
Aantal Afbeeldingen per Verzoek: Onbeperkt
In tegenstelling tot andere vision-API’s die het aantal afbeeldingen per verzoek beperken, legt de xAI API geen limiet op. U kunt zoveel afbeeldingen verzenden als nodig is in één enkel verzoek.
Houd er echter rekening mee dat:
- Elke afbeelding tussen de 256 en 1792 tokens verbruikt
- De totale context van het model een maximale grootte heeft
- Meer afbeeldingen = hogere latentie en kosten
Praktische Aanbeveling
Hoewel de limiet theoretisch onbeperkt is, blijf redelijk:
# 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
Compatibele Modellen
Afbeeldingsbegrip is beschikbaar op grok-4.5 en hoger. Eerdere modellen ondersteunen deze functie niet.
Controleer altijd welk model in uw code wordt gebruikt:
VISION_MODELS = ["grok-4.5", "grok-4.20-0309-reasoning"]
def supports_vision(model):
return any(model.startswith(m) for m in VISION_MODELS)
Foutafhandeling
Anticipeer op fouten gerelateerd aan beperkingen door afbeeldingen te valideren voordat u ze verzendt:
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
Belangrijkste punten
- Alleen de indelingen JPG/JPEG en PNG worden geaccepteerd — converteer andere
- Maximale grootte: 20 MiB per afbeelding — comprimeer indien nodig
- Het aantal afbeeldingen per verzoek is onbeperkt, maar elke afbeelding verbruikt tokens
- Alleen modellen grok-4.5 en hoger ondersteunen vision
- Valideer afbeeldingen altijd voordat u ze verzendt om stille fouten te voorkomen