Vision: analizzare le immagini con Grok
In questa pagina
Comprensione delle immagini con Chat Completions
I modelli Grok (a partire da grok-4.5) includono funzionalità di visione che ti permettono di analizzare, descrivere e ragionare sulle immagini. Utilizzi questa caratteristica tramite il formato ad array del campo content, combinando oggetti text e image_url.
I casi d’uso sono numerosi: estrazione di testo da documenti scansionati (OCR), analisi di grafici, descrizione di interfacce utente, confronto visivo o interpretazione di diagrammi tecnici.
Inviare un’immagine tramite URL
Il metodo più semplice consiste nel fornire l’URL pubblico dell’immagine:
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1"
)
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Descrivi cosa vedi in questa immagine."},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/photo-architecture.jpg",
"detail": "high"
}
}
]
}
]
)
print(response.choices[0].message.content)
I server xAI scaricano l’immagine al momento della richiesta. Deve essere pubblicamente accessibile.
Inviare un’immagine in Base64
Per immagini locali o private, utilizza la codifica base64:
import base64
def encode_image(image_path: str) -> str:
with open(image_path, "rb") as f:
return base64.b64encode(f.read()).decode("utf-8")
image_data = encode_image("capture-ecran.png")
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Quale testo è visibile in questo screenshot?"},
{
"type": "image_url",
"image_url": {
"url": f"data:image/png;base64,{image_data}"
}
}
]
}
]
)
Il formato dell’URL è data:image/{format};base64,{data}, dove {format} è jpeg, jpg o png.
Livelli di dettaglio: auto, low e high
Il parametro detail controlla la risoluzione con cui il modello analizza l’immagine:
detail: “low”
{
"type": "image_url",
"image_url": {
"url": "https://example.com/icone.png",
"detail": "low"
}
}
L’immagine viene ridimensionata a bassa risoluzione prima dell’analisi. Questa è la modalità più veloce e costa meno token. Utilizzala per immagini semplici: icone, loghi, diagrammi di base.
detail: “high”
{
"type": "image_url",
"image_url": {
"url": "https://example.com/document-scan.jpg",
"detail": "high"
}
}
L’immagine viene analizzata ad alta risoluzione. Il modello può leggere testi piccoli, identificare dettagli fini e analizzare aree specifiche. Questa è la modalità consigliata per documenti, screenshot e fotografie dettagliate.
detail: “auto”
Il modello sceglie automaticamente il livello di dettaglio in base alle dimensioni e alla complessità dell’immagine. Questo è il valore predefinito se ometti il parametro.
Analizzare più immagini
Puoi inviare più immagini in un singolo messaggio per compiti di confronto o analisi incrociata:
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Confronta queste due versioni del design. Quali sono le differenze?"},
{"type": "image_url", "image_url": {"url": "https://example.com/v1.png", "detail": "high"}},
{"type": "image_url", "image_url": {"url": "https://example.com/v2.png", "detail": "high"}}
]
}
]
)
Non c’è limite al numero di immagini per richiesta, ma ogni immagine consuma token aggiuntivi.
Vincoli tecnici
Tieni a mente questi limiti quando utilizzi la visione:
- Dimensione massima: 20 MiB per immagine
- Formati supportati: solo JPG, JPEG e PNG
- Modelli compatibili: grok-4 e superiori (i modelli più vecchi non supportano la visione)
- Token: le immagini consumano token che si aggiungono al costo del testo della richiesta
Punti chiave
- La visione utilizza il formato ad array del campo
contentcon oggettiimage_url - Le immagini possono essere inviate tramite URL pubblico o codificate in base64
- Tre livelli di dettaglio:
auto(predefinito),low(veloce/economico) ehigh(dettagliato) - Dimensione massima di 20 MiB per immagine, solo formati JPG e PNG
- È possibile inviare più immagini in un singolo messaggio per confronti