Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Rajoitukset: muodot, koko ja rajat

Oppitunti 4 / 12 Päivitetty 30. heinäkuuta 2026 Aloittelija
Tällä sivulla
  1. Perussäännöt
  2. Hyväksytyt kuvamuodot
  3. Enimmäiskoko: 20 MiB
  4. Kuvien määrä pyyntöä kohden: rajoittamaton
  5. Yhteensopivat mallit
  6. Virheenkäsittely
  7. Keskeiset asiat

Perussäännöt

Ennen kuin integroit Grok Visionin sovelluksiisi, sinun on tunnettava xAI-rajapinnan asettamat tekniset rajoitukset. Näiden rajojen huomiotta jättäminen johtaa hiljaisiin virheisiin tai hylättyihin pyyntöihin, joita voi olla vaikea vianetsiä tuotantoympäristössä.

Hyväksytyt kuvamuodot

xAI-rajapinta hyväksyy kaksi kuvatiedostomuotoa (kolme tiedostopäätettä: .jpg, .jpeg, .png):

  • JPG (tai JPEG) – yleisin valokuvien muoto
  • PNG – sopii kuvakaappauksiin, kaavioihin ja tekstiä sisältäviin kuviin

Kaikki muut muodot hylätään. Jos työskentelet WebP-, GIF-, BMP-, TIFF-, SVG- tai HEIC-kuvien kanssa, sinun on muunnettava ne ennen lähetystä:

from PIL import Image

def convert_to_jpeg(source_path, output_path):
    img = Image.open(source_path)
    # Muunna RGB-muotoon (vaaditaan JPEGille)
    if img.mode in ("RGBA", "P"):
        img = img.convert("RGB")
    img.save(output_path, "JPEG", quality=90)

Yleinen sudenkuoppa: RGBA-kuvat

Läpinäkyvyyttä (alfakanava) sisältävät PNG-tiedostot hyväksytään sellaisinaan. Jos kuitenkin muunnat ne JPEG-muotoon, sinun on poistettava alfakanava ensin, sillä JPEG ei tue läpinäkyvyyttä.

Enimmäiskoko: 20 MiB

Yhden kuvan koko ei saa ylittää 20 MiB:tä (20 971 520 tavua). Tämän rajan ylittyessä rajapinta hylkää pyynnön.

Tämä raja koskee:

  • Ladattua tiedostoa URL-osoitteen tapauksessa
  • Purettua dataa Base64-tapauksessa (ei itse koodattua merkkijonoa, joka on noin 33 % pidempi)

Tarkista koko ennen lähetystä

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"Kuva on liian suuri: {size_mib:.1f} MiB "
            f"(enintään {max_mib} MiB)"
        )
    return size_mib

Pakkaa tarvittaessa

Kuville, jotka ovat lähellä kokorajaa, voit vähentää JPEG-laatuasetusta:

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

Kuvien määrä pyyntöä kohden: rajoittamaton

Toisin kuin muut vision-rajapinnat, jotka rajoittavat kuvien määrää pyyntöä kohden, xAI-rajapinta ei aseta rajoitusta. Voit lähettää niin monta kuvaa kuin tarvitset yhdessä pyynnössä.

Muista kuitenkin, että:

  • Jokainen kuva kuluttaa 256–1792 tokenia
  • Mallin kokonaiskontekstilla on enimmäiskoko
  • Enemmän kuvia = suurempi viive ja korkeammat kustannukset

Käytännön suositus

Vaikka raja on teoreettisesti olematon, pysy kohtuullisuuksissa:

# Paras käytäntö: käsittele erissä
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": "Kuvaile lyhyesti jokainen kuva."
        })

        response = client.responses.create(
            model="grok-4.5",
            input=input_data
        )
        results.append(response)
    return results

Yhteensopivat mallit

Kuvien ymmärtäminen on saatavilla malleissa grok-4.5 ja uudemmat. Vanhemmat mallit eivät tue tätä ominaisuutta.

Tarkista koodissasi aina käytettävä malli:

VISION_MODELS = ["grok-4.5", "grok-4.20-0309-reasoning"]

def supports_vision(model):
    return any(model.startswith(m) for m in VISION_MODELS)

Virheenkäsittely

Ennakoi rajoituksiin liittyvät virheet validoimalla kuvat ennen lähetystä:

def validate_image(path):
    errors = []

    # Tarkista muoto
    extension = path.lower().rsplit(".", 1)[-1]
    if extension not in ("jpg", "jpeg", "png"):
        errors.append(f"Ei-tuettu muoto: {extension}")

    # Tarkista koko
    size_mib = os.path.getsize(path) / (1024 * 1024)
    if size_mib > 20:
        errors.append(f"Liian suuri: {size_mib:.1f} MiB (enintään 20)")

    # Tarkista, että kyseessä on aitokuva
    try:
        img = Image.open(path)
        img.verify()
    except Exception:
        errors.append("Vioittunut tiedosto tai ei kelvollinen kuva")

    return errors

Keskeiset asiat

  • Vain JPG/JPEG- ja PNG-muodot hyväksytään – muunna muut
  • Enimmäiskoko: 20 MiB kuvaa kohden – pakkaa tarvittaessa
  • Kuvien määrä pyyntöä kohden on rajoittamaton, mutta jokainen kuva kuluttaa tokeneita
  • Vain grok-4.5 ja uudemmat mallit tukevat vision-toimintoa
  • Validoi kuvat aina ennen lähetystä välttääksesi hiljaiset virheet