Vincoli: Formati, Dimensioni e Limiti
In questa pagina
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