Claude Platform Docs
MessaggiImmagini e visione

Visione

Invia immagini a Claude tramite l’API e scopri quali limiti e costi si applicano.

Questa guida descrive come inviare immagini a Claude, i limiti e i costi applicabili e dove trovare indicazioni per i flussi di lavoro basati su coordinate.


Inviare immagini a Claude

Usa 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.
  • Playground nella Claude Console. Aggiungi immagini direttamente a qualsiasi blocco di messaggio User.
  • Richiesta API. Consulta gli esempi seguenti.

Sull’API, fornisci le immagini a Claude come blocchi di contenuto image usando uno dei tre tipi di sorgente:

  1. Un’immagine codificata in base64 incorporata nel corpo della richiesta
  2. Un riferimento URL a un’immagine ospitata online
  3. Un file_id restituito dalla Files API (carica una volta, fai riferimento molte volte)

Esempio di immagine codificata in base64

image1_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"
image1_media_type = "image/png"

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image1_media_type,
                        "data": image1_data,
                    },
                },
                {"type": "text", "text": "Describe this image."},
            ],
        }
    ],
)
print(message)

Esempio di immagine basata su URL

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://platform.claude.com/docs/images/vision-example.jpg",
                    },
                },
                {"type": "text", "text": "Describe this image."},
            ],
        }
    ],
)
print(message)

Esempio di immagine con Files API

Per le immagini che userai ripetutamente o quando vuoi evitare l’overhead della 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.

Per seguire gli esempi con l’immagine che utilizzano, scarica prima l’immagine di esempio nella tua directory di lavoro. Ogni esempio carica quel file, vision-example.jpg, e poi vi fa riferimento tramite il file_id restituito dal caricamento:

client = anthropic.Anthropic()

# Carica il file immagine
with open("vision-example.jpg", "rb") as f:
    file_upload = client.files.upload(file=("vision-example.jpg", f, "image/jpeg"))

# Usa il file caricato in un messaggio
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {"type": "file", "file_id": file_upload.id},
                },
                {"type": "text", "text": "Describe this image."},
            ],
        }
    ],
)

print(message.content)

Consulta gli esempi della Messages APIAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro) per ulteriore codice di esempio e dettagli sui parametri.

Immagini multiple

Puoi includere più immagini in una singola richiesta e Claude le analizza congiuntamente. Questo è utile per confrontare immagini, chiedere informazioni sulle differenze o lavorare con una sequenza come le pagine di un documento. Quando invii diverse immagini, introduci ciascuna con una breve etichetta testuale (Image 1:, Image 2: e così via) in modo da poterle richiamare per nome nel tuo prompt e nei turni successivi.

image1_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"
image2_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGNgYPgPAAEDAQAIicLsAAAAAElFTkSuQmCC"

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Image 1:"},
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image1_data,
                    },
                },
                {"type": "text", "text": "Image 2:"},
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image2_data,
                    },
                },
                {"type": "text", "text": "How are these images different?"},
            ],
        }
    ],
)
print(message)

In una conversazione multi-turno, aggiungi nuove immagini nei turni user successivi allo stesso modo. Claude ha accesso a ogni immagine dei turni precedenti, quindi domande di follow-up come “Queste sono simili alle prime due?” funzionano senza includere nuovamente le immagini precedenti nel contenuto del nuovo turno.


Limiti e costi delle immagini

Limiti delle richieste

Il numero massimo di immagini per ciascun messaggio o richiesta è:

  • 20 per ciascun messaggio su claude.ai
  • 100 per ciascuna richiesta tramite l’API, per i modelli con una “context window” (finestra di contesto) di 200k token
  • 600 per ciascuna richiesta tramite l’API, per tutti gli altri modelli

Le dimensioni massime per ciascuna immagine sono 8000x8000 px.

Se una singola richiesta API contiene più di 20 immagini, a ogni immagine di quella richiesta si applica un limite più restrittivo sulle dimensioni per immagine. Tutti i blocchi image nella richiesta contano ai fini di questa soglia, incluse le immagini dei turni precedenti della conversazione che invii nuovamente e le immagini annidate all’interno del contenuto tool_result (ad esempio, gli screenshot restituiti allo strumento computer use). Su Claude Models on Google Cloud (Google managed) e Amazon Bedrock, anche i blocchi documento come i PDF contano ai fini di questa soglia. Le immagini che superano il limite più restrittivo vengono rifiutate con un invalid_request_error il cui messaggio fa riferimento a “many-image requests” e indica il limite attuale in pixel. Per rimanere entro il limite su tutte le piattaforme, ridimensiona ciascuna immagine in modo che nessuna delle due dimensioni superi 3.000 px, oppure limita la richiesta a 20 o meno blocchi immagine e documento.

La dimensione massima per immagine è:

  • 10 MB (codificata in base64) sulla Claude API e su Claude Models on Google Cloud (Google managed).
  • 5 MB (codificata in base64) su Amazon Bedrock.
  • 10 MB su claude.ai.

Formati supportati

Claude supporta immagini JPEG, PNG, GIF e WebP (image/jpeg, image/png, image/gif, image/webp). Le animazioni non sono supportate e viene usato solo il primo fotogramma.

Risoluzione e costo in token

Claude elabora le immagini in “patch” (riquadri) anziché in pixel. Ogni patch è un blocco di 28×28 pixel dell’immagine, denominato “visual token” (token visivo). Un’immagine costa quindi ⌈width / 28⌉ × ⌈height / 28⌉ token visivi.

Ogni modello ha una risoluzione nativa massima delle immagini, espressa come limite del lato lungo e limite di token visivi. Le immagini più grandi di uno dei due limiti vengono ridotte prima dell’elaborazione; vedi Come Claude ridimensiona e aggiunge padding alle immagini per la regola esatta. L’eccezione sono gli screenshot e le immagini di zoom che restituisci ai set di strumenti computer use e browser use: l’API rifiuta un’immagine tool_result che supera i limiti del modello con un errore di validazione invece di ridurla, quindi ridimensiona quelle immagini nella tua applicazione prima di restituirle. Per fare in modo che qualsiasi altra immagine sovradimensionata venga rifiutata con un errore invece di essere ridotta, imposta il campo transformations del blocco immagine.

Livello di risoluzioneModelliLato lungo massimoToken visivi massimi
Alta risoluzioneClaude 4.7 e modelli successivi2.576 px4.784
StandardTutti gli altri modelli1.568 px1.568

Il supporto per l’alta risoluzione è automatico sui modelli elencati e non richiede alcun header beta né opt-in lato client.

La tabella seguente mostra la risoluzione ridotta e il costo in token visivi per diverse dimensioni di immagine su ciascun livello:

Dimensione immagineLivello standard: ridotta aLivello standard: tokenLivello alta risoluzione: ridotta aLivello alta risoluzione: token
200x200 px (0,04 megapixel)Non ridimensionata64Non ridimensionata64
1000x1000 px (1 megapixel)Non ridimensionata1.296Non ridimensionata1.296
1092x1092 px (1,19 megapixel)Non ridimensionata1.521Non ridimensionata1.521
1920x1080 px (2,07 megapixel)1456x819 px1.560Non ridimensionata2.691
2000x1500 px (3 megapixel)1269x952 px1.564Non ridimensionata3.888
3840x2160 px (8,29 megapixel)1456x819 px1.5602576x1449 px4.784

Quando un’immagine viene ridotta, Claude la scala alla dimensione più grande che rientra nei limiti del livello preservandone le proporzioni. Questo pone un tetto al costo in token. Per la regola precisa e un’implementazione di riferimento, vedi Come Claude ridimensiona e aggiunge padding alle immagini.

Per stimare il costo, moltiplica il numero di token per il prezzo per token del modello che stai usando. Ad esempio, al prezzo di Claude Haiku 4.5 di $1 USD per milione di token di input (livello standard), l’immagine 1000×1000 costa circa $1,30 USD ogni mille immagini. Al prezzo di Claude Opus 5.5 di $4 USD per milione (livello alta risoluzione), la stessa immagine costa circa $5,18 USD ogni mille e l’immagine 4K circa $19,14 USD ogni mille.

Le immagini ad alta risoluzione possono usare fino a circa tre volte più token visivi rispetto alla stessa immagine su un modello di livello standard. Se non hai bisogno della fedeltà aggiuntiva che l’alta risoluzione offre per computer use, comprensione degli screenshot e documenti densi, esegui il downsampling delle immagini prima dell’invio per controllare i costi in token. Per minimizzare la latenza e semplificare i flussi di lavoro basati su coordinate, preferisci ridimensionare le immagini prima di caricarle.

Indicazioni sulla qualità delle immagini

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

  • Nitidezza dell’immagine: Assicurati che le immagini siano nitide e non troppo sfocate o pixelate.
  • Testo: Se l’immagine contiene testo importante, assicurati che sia leggibile e non troppo piccolo. Evita di ritagliare contesto visivo chiave solo per ingrandire il testo.
  • Ridimensionamento: Tieni conto che la tua immagine potrebbe essere ridimensionata se è troppo grande (vedi Risoluzione e costo in token); questo potrebbe, ad esempio, rendere il testo meno leggibile. Considera di pre-ridimensionare le tue immagini, ritagliarle o entrambe le cose. Per fare in modo che un’immagine sovradimensionata venga rifiutata con un errore invece di essere ridimensionata (importante per i flussi di lavoro con coordinate), contrassegna il blocco immagine con "oversized_image": "error".
  • Compressione dell’immagine: Comprimere le immagini prima di inviarle, usando un formato con perdita come JPEG o WebP (modalità lossy), può ridurre la latenza riducendo la dimensione delle richieste. Tuttavia, questo può introdurre artefatti dannosi per le prestazioni del modello, specialmente quando vengono applicati più passaggi di compressione. Ad esempio, una forte compressione JPEG può rendere il testo difficile da leggere. Verifica che le tue impostazioni di compressione siano appropriate per il compito ispezionando le immagini effettivamente inviate all’API.

Coordinate e bounding box

Per “bounding box” (riquadri di delimitazione), punti e coordinate in pixel, consulta Coordinate e bounding box. Claude restituisce coordinate assolute in pixel relative all’immagine che elabora dopo il ridimensionamento; quella guida spiega come Claude ridimensiona e aggiunge padding alle immagini e come ridimensionarle preventivamente o riscalarle in modo che le coordinate corrispondano all’immagine originale.


Limitazioni

Sebbene le capacità di comprensione delle immagini di Claude siano avanzate, ci sono alcune limitazioni da tenere presenti:

  • Identificazione delle persone: Claude non può essere usato per nominare persone nelle immagini e si rifiuta di farlo (consulta la Politica di utilizzo).
  • Accuratezza: Claude potrebbe allucinare o commettere errori nell’interpretare immagini di bassa qualità, ruotate o molto piccole sotto i 200 pixel.
  • Ragionamento spaziale: Gli output di coordinate e localizzazione di Claude sono approssimativi. Segui le indicazioni in Coordinate e bounding box e verifica gli output prima di farvi affidamento.
  • Conteggio: Claude può fornire conteggi approssimativi degli oggetti in un’immagine ma potrebbe non essere sempre precisamente accurato, specialmente con grandi quantità di oggetti piccoli.
  • Immagini generate dall’IA: Claude non può determinare se un’immagine è generata dall’IA e potrebbe sbagliarsi 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 utilizzo.
  • Applicazioni sanitarie: Sebbene Claude possa analizzare immagini mediche generiche, non è progettato per interpretare scansioni diagnostiche complesse come TAC o risonanze magnetiche. Gli output di Claude non devono essere considerati un sostituto della consulenza o della diagnosi medica professionale.

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


Domande frequenti


Prossimi passi

Ottieni suggerimenti e tecniche di best practice per compiti come l’interpretazione di grafici e l’estrazione di contenuti da moduli.

Consulta la documentazione della Messages API, inclusi esempi di chiamate API che coinvolgono immagini.

Disponibilità

Visione (immagini)
API
  • Messages API
  • Managed Agents
Modelli
  • Tutti i modelli

Questa pagina ti è stata utile?