Ograničenja: formati, veličina i limiti
Na ovoj stranici
Temeljna pravila
Prije integracije Grok visiona u svoje aplikacije, moraš znati tehnička ograničenja koja nameće xAI API. Ignoriranje ovih limita dovodi do tihih grešaka ili odbijenih zahtjeva koje je u proizvodnji teško otkloniti.
Prihvaćeni formati slika
xAI API prihvaća dva formata slikovnih datoteka (tri ekstenzije: .jpg, .jpeg, .png):
- JPG (ili JPEG) — najčešći format za fotografije
- PNG — prikladan za snimke zaslona, dijagrame i slike s tekstom
Svi ostali formati se odbijaju. Ako radiš sa slikama u formatima WebP, GIF, BMP, TIFF, SVG ili HEIC, moraš ih konvertirati prije slanja:
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)
Česta zamka: RGBA slike
PNG datoteke s prozirnošću (alfa kanal) prihvaćaju se kakve jesu. Međutim, ako ih konvertiraš u JPEG, prvo moraš ukloniti alfa kanal jer JPEG ne podržava prozirnost.
Maksimalna veličina: 20 MiB
Svaka slika ne smije prelaziti 20 MiB (20.971.520 bajtova). Iznad toga, API odbija zahtjev.
Ovaj limit vrijedi:
- Za preuzetu datoteku u slučaju URL-a
- Za dekodirane podatke u slučaju Base64 (ne za sam kodirani niz, koji je ~33% duži)
Provjeri veličinu prije slanja
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
Komprimiraj ako je potrebno
Za slike blizu limita možeš smanjiti kvalitetu JPEG-a:
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
Broj slika po zahtjevu: neograničen
Za razliku od drugih vision API-ja koji ograničavaju broj slika po zahtjevu, xAI API ne nameće nikakav limit. U jednom zahtjevu možeš poslati onoliko slika koliko ti treba.
Ipak, imaj na umu da:
- Svaka slika troši između 256 i 1792 tokena
- Ukupni kontekst modela ima maksimalnu veličinu
- Više slika = veća latencija i veći trošak
Praktična preporuka
Iako je limit teoretski neograničen, ostani razuman:
# 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
Kompatibilni modeli
Razumijevanje slika dostupno je na modelima grok-4.5 i novijima. Stariji modeli ne podržavaju ovu značajku.
Uvijek provjeri model koji koristiš u kodu:
VISION_MODELS = ["grok-4.5", "grok-4.20-0309-reasoning"]
def supports_vision(model):
return any(model.startswith(m) for m in VISION_MODELS)
Rukovanje greškama
Predvidi greške vezane uz ograničenja validacijom slika prije slanja:
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
Ključne točke
- Prihvaćaju se samo formati JPG/JPEG i PNG — ostale konvertiraj
- Maksimalna veličina: 20 MiB po slici — komprimiraj ako je potrebno
- Broj slika po zahtjevu je neograničen, ali svaka slika troši tokene
- Samo modeli grok-4.5 i noviji podržavaju vision
- Uvijek validiraj slike prije slanja kako bi izbjegao tihe greške