Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Vision: analizzare le immagini con Grok

Lezione 7 di 12 Aggiornata il 30 luglio 2026 Sviluppatore
In questa pagina
  1. Comprensione delle immagini con Chat Completions
  2. Inviare un’immagine tramite URL
  3. Inviare un’immagine in Base64
  4. Livelli di dettaglio: auto, low e high
  5. Analizzare più immagini
  6. Vincoli tecnici
  7. Punti chiave

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 content con oggetti image_url
  • Le immagini possono essere inviate tramite URL pubblico o codificate in base64
  • Tre livelli di dettaglio: auto (predefinito), low (veloce/economico) e high (dettagliato)
  • Dimensione massima di 20 MiB per immagine, solo formati JPG e PNG
  • È possibile inviare più immagini in un singolo messaggio per confronti