Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Piirangud: vormingud, suurus ja limiidid

Õppetund 4 / 12 Värskendatud 30. juuli 2026 Algajatele
Sellel lehel
  1. Põhireeglid
  2. Lubatud pildiformaadid
  3. Maksimaalne suurus: 20 MiB
  4. Piltide arv päringu kohta: piiramatu
  5. Ühilduvad mudelid
  6. Veakäsitlus
  7. Peamised punktid

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