Visione

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.

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 API 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 messaggio o richiesta è:

• 20 per messaggio su claude.ai.
• 100 per richiesta sull'API, per i modelli con una "context window" (finestra di contesto) da 200k token.
• 600 per richiesta sull'API, per tutti gli altri modelli.

Le dimensioni massime per immagine sono 8000x8000 px.

Se una singola richiesta API contiene più di 20 immagini, si applica un limite di dimensioni per immagine più restrittivo a ogni immagine in quella richiesta. 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 Amazon Bedrock e Google Cloud, 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 corrente in pixel. Per rimanere sotto il limite su tutte le piattaforme, ridimensiona ogni immagine in modo che nessuna delle due dimensioni superi 2000 px, oppure mantieni la richiesta a 20 o meno blocchi immagine e documento.

La dimensione massima per immagine è:

• 10 MB (codificata in base64) quando usi direttamente la Claude API.
• 5 MB (codificata in base64) su Amazon Bedrock e Google Cloud.
• 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 vede le immagini in patch anziché in pixel. Ogni patch è un blocco di 28×28 pixel dell'immagine, chiamato token visivo. Un'immagine, quindi, costa ⌈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.

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:

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 per mille immagini. Al prezzo di Claude Opus 5 di $5 USD per milione (livello alta risoluzione), la stessa immagine costa circa $6,48 USD per mille e l'immagine 4K circa $23,92 USD per 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, punti e coordinate in pixel, vedi Coordinate e bounding box. Claude restituisce coordinate assolute in pixel relative all'immagine che vede dopo il ridimensionamento; quella guida spiega come Claude ridimensiona e aggiunge padding alle immagini e come pre-ridimensionare o riscalare in modo che le coordinate corrispondano alla tua immagine originale.

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 usato per identificare per nome le persone nelle immagini e si rifiuta di farlo.
• 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 Acceptable Use Policy.
• 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