Einschränkungen: Formate, Größe und Limits
Auf dieser Seite
Grundregeln
Bevor Sie Grok-Vision in Ihre Anwendungen integrieren, müssen Sie die technischen Einschränkungen der xAI-API kennen. Das Ignorieren dieser Limits führt zu stillen Fehlern oder abgelehnten Anfragen, die in der Produktion schwer zu debuggen sind.
Akzeptierte Bildformate
Die xAI-API akzeptiert zwei Bildformate (drei Dateierweiterungen: .jpg, .jpeg, .png):
- JPG (oder JPEG) – das häufigste Format für Fotografien
- PNG – geeignet für Screenshots, Diagramme und Bilder mit Text
Alle anderen Formate werden abgelehnt. Wenn Sie mit WebP, GIF, BMP, TIFF, SVG oder HEIC-Bildern arbeiten, müssen Sie diese vor dem Senden konvertieren:
from PIL import Image
def convert_to_jpeg(source_path, output_path):
img = Image.open(source_path)
# Konvertieren in RGB (erforderlich für JPEG)
if img.mode in ("RGBA", "P"):
img = img.convert("RGB")
img.save(output_path, "JPEG", quality=90)
Häufiger Fehlerfall: RGBA-Bilder
PNG-Dateien mit Transparenz (Alpha-Kanal) werden so akzeptiert. Wenn Sie sie jedoch in JPEG konvertieren, müssen Sie den Alpha-Kanal vorher entfernen, da JPEG keine Transparenz unterstützt.
Maximale Größe: 20 MiB
Jedes Bild darf 20 MiB (20.971.520 Bytes) nicht überschreiten. Darüber hinaus lehnt die API die Anfrage ab.
Dieses Limit gilt:
- Für die heruntergeladene Datei im Fall einer URL
- Für die dekodierten Daten im Fall von Base64 (nicht die codierte Zeichenkette selbst, die ca. 33 % länger ist)
Größe vor dem Senden prüfen
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"Bild zu groß: {size_mib:.1f} MiB "
f"(max {max_mib} MiB)"
)
return size_mib
Komprimieren, wenn notwendig
Für Bilder, die dem Limit nahekommen, können Sie die JPEG-Qualität reduzieren:
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
Anzahl der Bilder pro Anfrage: Unbegrenzt
Im Gegensatz zu anderen Vision-APIs, die die Anzahl der Bilder pro Anfrage begrenzen, stellt die xAI-API keine Begrenzung dar. Sie können in einer einzigen Anfrage so viele Bilder senden, wie benötigt werden.
Beachten Sie jedoch Folgendes:
- Jedes Bild verbraucht zwischen 256 und 1792 Tokens
- Der Gesamtkontext des Modells hat eine maximale Größe
- Mehr Bilder = höhere Latenz und Kosten
Praktische Empfehlung
Obwohl das Limit theoretisch unbegrenzt ist, sollten Sie vernünftig bleiben:
# Best Practice: Verarbeitung 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": "Beschreiben Sie jedes Bild kurz."
})
response = client.responses.create(
model="grok-4.5",
input=input_data
)
results.append(response)
return results
Kompatible Modelle
Die Bilderkennung ist auf grok-4.5 und höher verfügbar. Frühere Modelle unterstützen diese Funktion nicht.
Prüfen Sie immer das im Code verwendete Modell:
VISION_MODELS = ["grok-4.5", "grok-4.20-0309-reasoning"]
def supports_vision(model):
return any(model.startswith(m) for m in VISION_MODELS)
Fehlerbehandlung
Antizipieren Sie Fehler im Zusammenhang mit Einschränkungen, indem Sie Bilder vor dem Senden validieren:
def validate_image(path):
errors = []
# Format prüfen
extension = path.lower().rsplit(".", 1)[-1]
if extension not in ("jpg", "jpeg", "png"):
errors.append(f"Ununterstütztes Format: {extension}")
# Größe prüfen
size_mib = os.path.getsize(path) / (1024 * 1024)
if size_mib > 20:
errors.append(f"Zu groß: {size_mib:.1f} MiB (max 20)")
# Prüfen, ob es ein echtes Bild ist
try:
img = Image.open(path)
img.verify()
except Exception:
errors.append("Beschädigte Datei oder kein gültiges Bild")
return errors
Kernaussagen
- Nur JPG/JPEG- und PNG-Formate werden akzeptiert – konvertieren Sie andere Formate
- Maximale Größe: 20 MiB pro Bild – komprimieren Sie bei Bedarf
- Die Anzahl der Bilder pro Anfrage ist unbegrenzt, aber jedes Bild verbraucht Tokens
- Nur grok-4.5 und höhere Modelle unterstützen Vision
- Validieren Sie Bilder immer vor dem Senden, um stille Fehler zu vermeiden