Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Restrizzjonijiet: Formati, Daqs u Limiti

Lezzjoni 4 / 12 Aġġornat 30 ta’ Lulju 2026 Bidbieni
F'din il-paġna
  1. Regoli Bażiċi
  2. Formati tal-Immaġni Aċċettati
  3. Daqs Massimu: 20 MiB
  4. Numru ta’ Immaġnijiet għal Kull Talba: Illimitat
  5. Mudelli Kompatibbli
  6. Ġestjoni tal-Iżbalji
  7. Punti Ewlenin

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