Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Vincoli: Formati, Dimensioni e Limiti

Lezione 4 di 12 Aggiornata il 30 luglio 2026 Principiante
In questa pagina
  1. Regole Fondamentali
  2. Formati Immagine Accettati
  3. Dimensione Massima: 20 MiB
  4. Numero di Immagini per Richiesta: Illimitato
  5. Modelli Compatibili
  6. Gestione degli Errori
  7. Punti chiave

Regole Fondamentali

Prima di integrare la visione di Grok nelle tue applicazioni, devi conoscere i vincoli tecnici imposti dall’API xAI. Ignorare questi limiti porta a errori silenziosi o richieste rifiutate, difficili da debuggare in produzione.

Formati Immagine Accettati

L’API xAI accetta due formati di file immagine (tre estensioni: .jpg, .jpeg, .png):

  • JPG (o JPEG) — il formato più comune per le fotografie
  • PNG — adatto per screenshot, diagrammi e immagini con testo

Tutti gli altri formati vengono rifiutati. Se lavori con immagini WebP, GIF, BMP, TIFF, SVG o HEIC, devi convertirle prima dell’invio:

from PIL import Image

def convert_to_jpeg(source_path, output_path):
    img = Image.open(source_path)
    # Converti in RGB (richiesto per JPEG)
    if img.mode in ("RGBA", "P"):
        img = img.convert("RGB")
    img.save(output_path, "JPEG", quality=90)

Errore Comune: Immagini RGBA

I file PNG con trasparenza (canale alfa) sono accettati così come sono. Tuttavia, se li converti in JPEG, devi prima rimuovere il canale alfa perché il JPEG non supporta la trasparenza.

Dimensione Massima: 20 MiB

Ogni immagine non deve superare i 20 MiB (20.971.520 byte). Oltre questo limite, l’API rifiuta la richiesta.

Questo limite si applica:

  • Al file scaricato nel caso di un URL
  • Ai dati decodificati nel caso di Base64 (non alla stringa codificata stessa, che è circa il 33% più lunga)

Controlla la Dimensione Prima dell’Invio

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"Immagine troppo grande: {size_mib:.1f} MiB "
            f"(max {max_mib} MiB)"
        )
    return size_mib

Comprimi Se Necessario

Per le immagini vicine al limite, puoi ridurre la qualità 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

Numero di Immagini per Richiesta: Illimitato

A differenza di altre API di visione che limitano il numero di immagini per richiesta, l’API xAI non impone alcun limite. Puoi inviare tutte le immagini necessarie in una singola richiesta.

Tuttavia, tieni presente che:

  • Ogni immagine consuma tra 256 e 1792 token
  • Il contesto totale del modello ha una dimensione massima
  • Più immagini = latenza e costi maggiori

Raccomandazione Pratica

Anche se il limite è teoricamente illimitato, mantieni un approccio ragionevole:

# Best practice: elabora in batch
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": "Descrivi brevemente ogni immagine."
        })

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

Modelli Compatibili

La comprensione delle immagini è disponibile su grok-4.5 e versioni successive. I modelli precedenti non supportano questa funzionalità.

Controlla sempre il modello utilizzato nel tuo codice:

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

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

Gestione degli Errori

Anticipa gli errori legati ai vincoli convalidando le immagini prima dell’invio:

def validate_image(path):
    errors = []

    # Controlla il formato
    extension = path.lower().rsplit(".", 1)[-1]
    if extension not in ("jpg", "jpeg", "png"):
        errors.append(f"Formato non supportato: {extension}")

    # Controlla la dimensione
    size_mib = os.path.getsize(path) / (1024 * 1024)
    if size_mib > 20:
        errors.append(f"Troppa grande: {size_mib:.1f} MiB (max 20)")

    # Controlla che sia un'immagine reale
    try:
        img = Image.open(path)
        img.verify()
    except Exception:
        errors.append("File corrotto o non un'immagine valida")

    return errors

Punti chiave

  • Sono accettati solo i formati JPG/JPEG e PNG — converti gli altri
  • Dimensione massima: 20 MiB per immagine — comprimi se necessario
  • Il numero di immagini per richiesta è illimitato, ma ogni immagine consuma token
  • Solo i modelli grok-4.5 e successivi supportano la visione
  • Convalida sempre le immagini prima dell’invio per evitare errori silenziosi