Vision

Questa guida descrive come lavorare con le immagini in Claude, incluse le best practice, gli esempi di codice e i limiti da tenere a mente.

Come utilizzare la vision

Utilizza le capacità di visione di Claude tramite:

claude.ai. Carica un'immagine come faresti con un file, oppure trascina e rilascia un'immagine direttamente nella finestra della chat.
Il Console Workbench. Un pulsante per aggiungere immagini appare in alto a destra di ogni blocco di messaggi Utente.
Richiesta API. Consulta gli esempi in questa guida.

Prima di caricare

Nozioni di base e limiti

Puoi includere più immagini in una singola richiesta: fino a 20 per claude.ai, e fino a 600 per le richieste API (100 per i modelli con una finestra di contesto di 200k token). Claude analizza tutte le immagini fornite quando formula la sua risposta. Questo può essere utile per confrontare o mettere a confronto le immagini.

Se invii un'immagine più grande di 8000x8000 px, viene rifiutata. Se invii più di 20 immagini in una singola richiesta API, questo limite è di 2000x2000 px.

Sebbene l'API supporti fino a 600 immagini per richiesta, i limiti di dimensione della richiesta (32 MB per gli endpoint standard; inferiore su alcune piattaforme di terze parti) possono essere raggiunti prima. Per molte immagini, considera di caricarle con la Files API e di fare riferimento tramite file_id per mantenere piccoli i payload delle richieste.

Anche quando si utilizza la Files API, le richieste con molte immagini di grandi dimensioni possono fallire prima di raggiungere il conteggio di 600 immagini. Riduci le dimensioni delle immagini o le dimensioni dei file (ad esempio, tramite downsampling) prima di caricarle (vedi Valutare la dimensione dell'immagine).

Valutare la dimensione dell'immagine

Per prestazioni ottimali, ridimensiona le immagini prima di caricarle se sono troppo grandi. Se il lato lungo dell'immagine è superiore a 1568 pixel, o se l'immagine supera ~1.600 token, viene prima ridimensionata, preservando le proporzioni, fino a rientrare nei limiti di dimensione.

Se l'immagine di input è troppo grande e deve essere ridimensionata, aumenta la latenza del time-to-first-token, senza alcun beneficio per la qualità dell'output. Le immagini molto piccole, inferiori a 200 pixel su qualsiasi lato, possono degradare la qualità dell'output.

Per migliorare il time-to-first-token, considera di ridimensionare le immagini a non più di 1,15 megapixel (e entro 1568 pixel in entrambe le dimensioni).

Ecco una tabella delle dimensioni massime delle immagini accettate dall'API che non verranno ridimensionate per i rapporti di aspetto comuni. Con Claude Sonnet 4.6, queste immagini utilizzano circa 1.600 token e circa $4,80/1k immagini.

Rapporto di aspetto	Dimensione immagine
1:1	1092x1092 px
3:4	951x1268 px
2:3	896x1344 px
9:16	819x1456 px
1:2	784x1568 px

Calcolare i costi delle immagini

Ogni immagine che includi in una richiesta a Claude conta verso il tuo utilizzo di token. Per calcolare il costo approssimativo, moltiplica il numero approssimativo di token dell'immagine per il prezzo per token del modello che stai utilizzando.

Se la tua immagine non ha bisogno di essere ridimensionata, puoi stimare il numero di token utilizzati tramite questo algoritmo: tokens = (width px * height px)/750

Ecco esempi di tokenizzazione approssimativa e costi per diverse dimensioni di immagini nei limiti di dimensione dell'API basati sul prezzo per token di Claude Sonnet 4.6 di $3 per milione di token di input:

Dimensione immagine	# di Token	Costo / immagine	Costo / 1k immagini
200x200 px(0,04 megapixel)	~54	~$0,00016	~$0,16
1000x1000 px(1 megapixel)	~1334	~$0,004	~$4,00
1092x1092 px(1,19 megapixel)	~1590	~$0,0048	~$4,80

Garantire la qualità dell'immagine

Quando fornisci immagini a Claude, tieni presente quanto segue per ottenere i migliori risultati:

Formato immagine: Utilizza un formato immagine supportato: JPEG, PNG, GIF o WebP.
Chiarezza dell'immagine: Assicurati che le immagini siano chiare e non troppo sfocate o pixelate.
Testo: Se l'immagine contiene testo importante, assicurati che sia leggibile e non troppo piccolo. Evita di ritagliare il contesto visivo chiave solo per ingrandire il testo.

Esempi di prompt

Molte delle tecniche di prompting che funzionano bene per le interazioni basate su testo con Claude possono essere applicate anche ai prompt basati su immagini.

Questi esempi dimostrano le strutture di prompt best practice che coinvolgono le immagini.

Proprio come posizionare documenti lunghi prima della query migliora i risultati nei prompt di testo, Claude funziona meglio quando le immagini vengono prima del testo. Le immagini posizionate dopo il testo o interpolate con il testo funzionano comunque bene, ma se il tuo caso d'uso lo consente, preferisci una struttura immagine-poi-testo.

Informazioni sugli esempi di prompt

I seguenti esempi dimostrano come utilizzare le capacità di visione di Claude utilizzando vari linguaggi di programmazione e approcci. Puoi fornire immagini a Claude in tre modi:

Come immagine codificata in base64 nei blocchi di contenuto image
Come riferimento URL a un'immagine ospitata online
Utilizzando la Files API (carica una volta, usa più volte)

I prompt di esempio base64 utilizzano queste variabili:

Di seguito sono riportati esempi di come includere immagini in una richiesta all'API Messages utilizzando immagini codificate in base64 e riferimenti URL:

Esempio di immagine codificata in base64

Esempio di immagine basata su URL

Esempio di immagine con Files API

Per le immagini che utilizzerai ripetutamente o quando vuoi evitare il sovraccarico di codifica, usa la Files API. Carica l'immagine una volta, poi fai riferimento al file_id restituito nei messaggi successivi invece di inviare nuovamente i dati base64.

Nelle conversazioni multi-turno e nei flussi di lavoro agentici, ogni richiesta invia nuovamente l'intera cronologia della conversazione. Se le immagini sono codificate in base64, i byte completi dell'immagine vengono inclusi nel payload ad ogni turno, il che può aumentare significativamente le dimensioni della richiesta e la latenza man mano che la conversazione cresce. Caricare le immagini sulla Files API e referenziarle tramite file_id mantiene i payload delle richieste ridotti indipendentemente da quante immagini si accumulano nella cronologia della conversazione.

Consulta gli esempi dell'API Messages per ulteriori esempi di codice e dettagli sui parametri.

Limitazioni

Sebbene le capacità di comprensione delle immagini di Claude siano all'avanguardia, ci sono alcune limitazioni di cui essere consapevoli:

Identificazione delle persone: Claude non può essere utilizzato per nominare persone nelle immagini e si rifiuta di farlo.
Accuratezza: Claude può allucinare o commettere errori nell'interpretare immagini di bassa qualità, ruotate o molto piccole sotto i 200 pixel.
Ragionamento spaziale: Le capacità di ragionamento spaziale di Claude sono limitate. Potrebbe avere difficoltà con compiti che richiedono una localizzazione precisa o layout, come leggere il quadrante di un orologio analogico o descrivere le posizioni esatte dei pezzi degli scacchi.
Conteggio: Claude può fornire conteggi approssimativi degli oggetti in un'immagine, ma potrebbe non essere sempre preciso, specialmente con grandi numeri di oggetti piccoli.
Immagini generate dall'IA: Claude non sa se un'immagine è generata dall'IA e potrebbe essere errato se interrogato. Non fare affidamento su di esso per rilevare immagini false o sintetiche.
Contenuti inappropriati: Claude non elabora immagini inappropriate o esplicite che violano la Politica di Uso Accettabile.
Applicazioni sanitarie: Sebbene Claude possa analizzare immagini mediche generali, non è progettato per interpretare scansioni diagnostiche complesse come TC o risonanze magnetiche. Gli output di Claude non devono essere considerati un sostituto della consulenza medica professionale o della diagnosi.

Rivedi e verifica sempre attentamente le interpretazioni delle immagini di Claude, specialmente per casi d'uso ad alto rischio. Non utilizzare Claude per compiti che richiedono precisione assoluta o analisi di immagini sensibili senza supervisione umana.

FAQ

Approfondisci la visione

Pronto per iniziare a costruire con le immagini usando Claude? Ecco alcune risorse utili:

Cookbook multimodale: Questo cookbook contiene suggerimenti su come iniziare con le immagini e tecniche di best practice per garantire le migliori prestazioni con le immagini. Scopri come puoi fare prompt efficaci a Claude con le immagini per svolgere compiti come interpretare e analizzare grafici o estrarre contenuto dai moduli.
Riferimento API: Documentazione per l'API Messages, inclusi esempi di chiamate API che coinvolgono immagini.

Se hai altre domande, contatta il team di supporto. Puoi anche unirti alla community degli sviluppatori per connetterti con altri creatori e ottenere aiuto dagli esperti di Anthropic.

    # Per le immagini basate su URL, puoi usare l'URL direttamente nella tua richiesta JSON

    # Per le immagini codificate in base64, devi prima codificare l'immagine
    # Esempio di come codificare un'immagine in base64 in bash:
    BASE64_IMAGE_DATA=$(curl -s "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg" | base64)

    # I dati codificati possono ora essere utilizzati nelle tue chiamate API

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "model": "claude-opus-4-6",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "$BASE64_IMAGE_DATA"
          }
        },
        {
          "type": "text",
          "text": "Describe this image."
        }
      ]
    }
  ]
}
EOF

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "url",
              "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
            }
          },
          {
            "type": "text",
            "text": "Describe this image."
          }
        ]
      }
    ]
  }'

# Prima, carica la tua immagine sulla Files API
curl -X POST https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -F "[email protected]"

# Poi usa il file_id restituito nel tuo messaggio
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "file",
              "file_id": "file_abc123"
            }
          },
          {
            "type": "text",
            "text": "Describe this image."
          }
        ]
      }
    ]
  }'

Come utilizzare la vision

Prima di caricare

Nozioni di base e limiti

Valutare la dimensione dell'immagine

Calcolare i costi delle immagini

Garantire la qualità dell'immagine

Esempi di prompt

Informazioni sugli esempi di prompt

Esempio di immagine codificata in base64

Esempio di immagine basata su URL

Esempio di immagine con Files API

Esempio: Un'immagine

Limitazioni

FAQ

Quali tipi di file immagine supporta Claude?

Claude può leggere URL di immagini?

Approfondisci la visione

Esempio: Immagini multiple

Esempio: Immagini multiple con un prompt di sistema

Esempio: Quattro immagini in due turni di conversazione

C'è un limite alla dimensione del file immagine che posso caricare?

Quante immagini posso includere in una richiesta?

Claude legge i metadati delle immagini?

Posso eliminare le immagini che ho caricato?

Dove posso trovare dettagli sulla privacy dei dati per i caricamenti di immagini?

Cosa fare se l'interpretazione delle immagini di Claude sembra errata?

Claude può generare o modificare immagini?