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:
- Un’immagine codificata in base64 incorporata nel corpo della richiesta
- Un riferimento URL a un’immagine ospitata online
- Un
file_idrestituito 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 risoluzione | Modelli | Lato lungo massimo | Token visivi massimi |
|---|---|---|---|
| Alta risoluzione | Claude 4.7 e modelli successivi | 2.576 px | 4.784 |
| Standard | Tutti gli altri modelli | 1.568 px | 1.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 immagine | Livello standard: ridotta a | Livello standard: token | Livello alta risoluzione: ridotta a | Livello alta risoluzione: token |
|---|---|---|---|---|
| 200x200 px (0,04 megapixel) | Non ridimensionata | 64 | Non ridimensionata | 64 |
| 1000x1000 px (1 megapixel) | Non ridimensionata | 1.296 | Non ridimensionata | 1.296 |
| 1092x1092 px (1,19 megapixel) | Non ridimensionata | 1.521 | Non ridimensionata | 1.521 |
| 1920x1080 px (2,07 megapixel) | 1456x819 px | 1.560 | Non ridimensionata | 2.691 |
| 2000x1500 px (3 megapixel) | 1269x952 px | 1.564 | Non ridimensionata | 3.888 |
| 3840x2160 px (8,29 megapixel) | 1456x819 px | 1.560 | 2576x1449 px | 4.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
JPEG, PNG, GIF e WebP. Vedi Formati supportati.
Sì. Usa il tipo di sorgente url invece di base64 nel blocco di contenuto image. Vedi l’esempio di immagine basata su URL.
Sì. Consulta Limiti delle richieste per i limiti di dimensione per ciascuna immagine e per l’intera richiesta.
Fino a 600 per ciascuna richiesta API (100 per i modelli con una finestra di contesto di 200k token) e 20 per ciascun turno su claude.ai. Consulta Limiti delle richieste per i dettagli e per il limite inferiore sulle dimensioni per immagine che si applica oltre le 20 immagini.
No, Claude non analizza né riceve alcun metadato dalle immagini che gli vengono passate.
No. Consulta API e conservazione dei dati per sapere per quanto tempo vengono conservate le immagini. Se carichi le immagini con la Files API, puoi eliminarle da lì.
Consulta la pagina dell’informativa sulla privacy di Anthropic per informazioni su come vengono gestite le immagini caricate e gli altri dati. Anthropic non usa le immagini caricate per addestrare i modelli.
Se l’interpretazione dell’immagine di Claude sembra errata:
- Assicurati che l’immagine sia nitida, di alta qualità e orientata correttamente.
- Prova tecniche di prompt engineering per migliorare i risultati.
- Se il problema persiste, segnala l’output in claude.ai (pollice su/giù) o contatta il team di supporto.
Il tuo feedback aiuta a migliorare Claude!
No, Claude è esclusivamente un modello di comprensione delle immagini. Può interpretare e analizzare immagini, ma non può generare, produrre, modificare, manipolare o creare immagini.
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à
Claude API
- API
- Messages API
- Managed Agents
- Modelli
- Tutti i modelli
Amazon Bedrock
- API
- Messages API
- Modelli
- Tutti i modelli
- Nota
Solo sorgenti di immagini base64; limite per immagine di 5 MB (codificata in base64) e una dimensione totale della richiesta inferiore.
Amazon Bedrock (bedrock-runtime)
- API
- Messages API
- Modelli
- Tutti i modelli
- Nota
Solo sorgenti di immagini base64; limite per immagine di 5 MB (codificata in base64) e una dimensione totale della richiesta inferiore.
Claude Platform on AWS
- API
- Messages API
- Managed Agents
- Modelli
- Tutti i modelli
Claude Models on Google Cloud (Anthropic managed)
- API
- Messages API
- Managed Agents
- Modelli
- Tutti i modelli
Claude Models on Google Cloud (Google managed)
- API
- Messages API
- Modelli
- Tutti i modelli
- Nota
Solo sorgenti di immagini base64; limite per immagine di 5 MB (codificata in base64) e una dimensione totale della richiesta inferiore.
Microsoft Foundry
- API
- Messages API
- Modelli
- Tutti i modelli
Questa pagina ti è stata utile?