Rajoitukset: muodot, koko ja rajat
Tällä sivulla
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