Restrizzjonijiet: Formati, Daqs u Limiti
F'din il-paġna
Regoli Bażiċi
Qabel tintegra l-viżjoni ta’ Grok fl-applikazzjonijiet tiegħek, trid tkun taf ir-restrizzjonijiet tekniċi imposti mill-API ta’ xAI. Jekk tinjora dawn il-limiti, se jkollok żbalji silenzjużi jew talbiet miċħuda li jkunu diffiċli biex tiddibuggjahom fil-produzzjoni.
Formati tal-Immaġni Aċċettati
L-API ta’ xAI taċċetta żewġ formati ta’ fajls tal-immaġni (tliet estensjonijiet: .jpg, .jpeg, .png):
- JPG (jew JPEG) — l-aktar format komuni għar-ritratti
- PNG — adattat għas-screenshots, djanjrammi u immaġnijiet b’test
Il-formati l-oħra kollha jiġu miċħuda. Jekk taħdem b’immaġnijiet WebP, GIF, BMP, TIFF, SVG jew HEIC, trid tikkonvertihom qabel ma tibgħathom:
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)
Żball Komuni: Immaġnijiet RGBA
Fajls PNG b’trasparenza (kanal alpha) huma aċċettati kif inhuma. Madankollu, jekk tikkonvertihom għal JPEG, trid tneħħi l-kanal alpha l-ewwel għax JPEG ma jappoġġjax it-trasparenza.
Daqs Massimu: 20 MiB
Kull immaġni m’għandhiex taqbeż 20 MiB (20,971,520 byte). Lil hinn minn hekk, l-API tiċħad it-talba.
Dan il-limitu japplika:
- Għall-fajl imniżżel fil-każ ta’ URL
- Għad-data dekodifikata fil-każ ta’ Base64 (mhux għall-katina encoded innifisha, li hija ~33% itwal)
Iċċekkja d-Daqs Qabel Tibgħat
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
Ikkompressa Jekk Meħtieġ
Għal immaġnijiet qrib il-limitu, tista’ tnaqqas il-kwalità tal-JPEG:
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
Numru ta’ Immaġnijiet għal Kull Talba: Illimitat
B’differenza minn APIs oħra tal-viżjoni li jillimitaw in-numru ta’ immaġnijiet għal kull talba, l-API ta’ xAI ma timponi l-ebda limitu. Tista’ tibgħat kemm-il immaġni trid f’talba waħda.
Madankollu, ftakar li:
- Kull immaġni tikkonsma bejn 256 u 1792 token
- Il-kuntest totali tal-mudell għandu daqs massimu
- Aktar immaġnijiet = latenza u kost ogħla
Rakkomandazzjoni Prattika
Għalkemm il-limitu huwa teoretikament illimitat, ibqa’ raġonevoli:
# 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
Mudelli Kompatibbli
Il-fehim tal-immaġnijiet huwa disponibbli fuq grok-4.5 u ogħla. Mudelli aktar bikrin ma jappoġġjawx din il-karatteristika.
Dejjem iċċekkja l-mudell użat fil-kodiċi tiegħek:
VISION_MODELS = ["grok-4.5", "grok-4.20-0309-reasoning"]
def supports_vision(model):
return any(model.startswith(m) for m in VISION_MODELS)
Ġestjoni tal-Iżbalji
Ipprevedi żbalji relatati mar-restrizzjonijiet billi tivvalida l-immaġnijiet qabel ma tibgħathom:
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
Punti Ewlenin
- Biss il-formati JPG/JPEG u PNG huma aċċettati — ikkonverti l-oħrajn
- Daqs massimu: 20 MiB għal kull immaġni — ikkompressa jekk meħtieġ
- In-numru ta’ immaġnijiet għal kull talba huwa illimitat iżda kull immaġni tikkonsma tokens
- Biss il-mudelli grok-4.5 u ogħla jappoġġjaw il-viżjoni
- Dejjem ivvalida l-immaġnijiet qabel ma tibgħathom biex tevita żbalji silenzjużi