Piirangud: vormingud, suurus ja limiidid
Sellel lehel
Põhireeglid
Enne Grok Visioni oma rakendustesse integreerimist pead tundma xAI API kehtestatud tehnilisi piiranguid. Nende limiitide eiramine viib vaiksete vigadeni või tagasilükatud päringuteni, mida tootmiskeskkonnas on raske siluda.
Lubatud pildiformaadid
xAI API aktsepteerib kahte pildifaili formaati (kolm laiendit: .jpg, .jpeg, .png):
- JPG (või JPEG) – kõige levinum formaat fotode jaoks
- PNG – sobib ekraanitõmmete, diagrammide ja teksti sisaldavate piltide jaoks
Kõik muud formaadid lükatakse tagasi. Kui töötad WebP, GIF, BMP, TIFF, SVG või HEIC piltidega, pead need enne saatmist konverteerima:
from PIL import Image
def convert_to_jpeg(source_path, output_path):
img = Image.open(source_path)
# Teisenda RGB-ks (nõutud JPEG-i jaoks)
if img.mode in ("RGBA", "P"):
img = img.convert("RGB")
img.save(output_path, "JPEG", quality=90)
Levinud viga: RGBA-pildid
Läbipaistvusega (alfakanaliga) PNG-failid aktsepteeritakse sellisena nagu nad on. Kui aga teisendad need JPEG-iks, pead enne eemaldama alfakanali, kuna JPEG ei toeta läbipaistvust.
Maksimaalne suurus: 20 MiB
Iga pilt ei tohi ületada 20 MiB (20 971 520 baiti). Sellest suuremate failide korral lükkab API päringu tagasi.
See limiit kehtib:
- allalaaditud faili kohta URL-i kasutamisel
- dekodeeritud andmete kohta Base64 puhul (mitte kodeeritud stringi enda kohta, mis on umbes 33% pikem)
Kontrolli suurust enne saatmist
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"Pilt on liiga suur: {size_mib:.1f} MiB "
f"(maksimum {max_mib} MiB)"
)
return size_mib
Vajadusel tihenda
Limiidile lähedaste piltide puhul saad vähendada JPEG-i kvaliteeti:
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
Piltide arv päringu kohta: piiramatu
Erinevalt teistest visioon-API-dest, mis piiravad piltide arvu päringus, ei kehti xAI API-l mingit limiiti. Saad ühes päringus saata nii palju pilte kui vaja.
Siiski pea meeles, et:
- iga pilt tarbib vahemikus 256 kuni 1792 tokenit
- mudeli kogukontekstil on maksimaalne suurus
- rohkem pilte tähendab suuremat latentsust ja kulu
Praktiline soovitus
Kuigi limiit on teoreetiliselt piiramatu, jää mõistlikkuse piiridesse:
# Parim tava: töötle partiidena
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": "Kirjelda lühidalt iga pilti."
})
response = client.responses.create(
model="grok-4.5",
input=input_data
)
results.append(response)
return results
Ühilduvad mudelid
Piltide mõistmine on saadaval mudelitel grok-4.5 ja uuematel. Varasemad mudelid seda funktsiooni ei toeta.
Kontrolli alati oma koodis kasutatavat mudelit:
VISION_MODELS = ["grok-4.5", "grok-4.20-0309-reasoning"]
def supports_vision(model):
return any(model.startswith(m) for m in VISION_MODELS)
Veakäsitlus
Enneta piirangutega seotud vigu, valideerides pilte enne saatmist:
def validate_image(path):
errors = []
# Kontrolli formaati
extension = path.lower().rsplit(".", 1)[-1]
if extension not in ("jpg", "jpeg", "png"):
errors.append(f"Toetamata formaat: {extension}")
# Kontrolli suurust
size_mib = os.path.getsize(path) / (1024 * 1024)
if size_mib > 20:
errors.append(f"Liiga suur: {size_mib:.1f} MiB (maks 20)")
# Kontrolli, et tegemist on tegeliku pildiga
try:
img = Image.open(path)
img.verify()
except Exception:
errors.append("Fail on vigane või ei ole kehtiv pilt")
return errors
Peamised punktid
- Aktsepteeritakse ainult JPG/JPEG ja PNG formaate – teisenda ülejäänud
- Maksimaalne suurus: 20 MiB pildi kohta – tihenda vajadusel
- Piltide arv päringus on piiramatu, kuid iga pilt tarbib tokeneid
- Ainult mudelid grok-4.5 ja uuemad toetavad visiooni
- Valideeri pilte alati enne saatmist, et vältida vaikseid vigu