Analisi Immagini con Claude API: Guida alla Vision
Perché la Vision con Claude API nel 2026
Per anni il testo ha dominato l’interazione con i modelli di linguaggio. Nel 2026 la situazione è radicalmente diversa: Claude 3.5 Sonnet e Claude 3 Opus gestiscono input multimodali in modo nativo, permettendo di passare immagini insieme al prompt e ricevere analisi dettagliate in risposta. Questo apre scenari concreti per i developer: OCR su fatture scansionate, descrizione automatica di screenshot per test UI, moderazione di immagini caricate dagli utenti, catalogazione di prodotti da foto, analisi di grafici e dashboard.
La Claude API Vision è accessibile attraverso gli stessi endpoint che usi per il testo — nessuna libreria aggiuntiva, nessun servizio separato. Basta strutturare il messaggio con un array di contenuti che include sia testo che immagini. Il modello vede l’immagine, ragiona su di essa e risponde con la precisione che ti aspetti da Claude. Se hai già lavorato con l’automazione del workflow con Claude API, aggiungere la vision al tuo stack richiede pochissime modifiche. In questa guida vedremo tutto: struttura della richiesta, formati supportati, limiti pratici, casi d’uso reali con codice funzionante.
Come Funziona la Vision API: Struttura della Richiesta
La differenza tra una richiesta testuale e una visuale sta nel campo content del messaggio. Invece di una semplice stringa, usi un array di oggetti. Ogni oggetto ha un type che può essere text o image. Per le immagini hai due opzioni: passare l’URL pubblico dell’immagine oppure i dati base64 con il media type corrispondente.
import anthropic
import base64
from pathlib import Path
client = anthropic.Anthropic(api_key="sk-ant-...")
# Opzione 1: immagine da URL pubblico
def analizza_immagine_url(url: str, domanda: str) -> str:
message = client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "url",
"url": url,
},
},
{
"type": "text",
"text": domanda
}
],
}
],
)
return message.content[0].text
# Opzione 2: immagine locale in base64
def analizza_immagine_locale(path: str, domanda: str) -> str:
img_data = base64.standard_b64encode(
Path(path).read_bytes()
).decode("utf-8")
ext = Path(path).suffix.lower()
media_types = {
".jpg": "image/jpeg",
".jpeg": "image/jpeg",
".png": "image/png",
".gif": "image/gif",
".webp": "image/webp",
}
media_type = media_types.get(ext, "image/jpeg")
message = client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": media_type,
"data": img_data,
},
},
{
"type": "text",
"text": domanda
}
],
}
],
)
return message.content[0].text
Il parametro model è fondamentale: non tutti i modelli Claude supportano la vision. Claude 3 Haiku, Sonnet e Opus sono multimodali; i modelli Claude 2 non lo sono. Usa sempre claude-3-5-sonnet-20241022 o superiore per ottenere le migliori prestazioni di analisi visuale.
Caso d’Uso 1: OCR e Estrazione Testo da Documenti
L’estrazione di testo da immagini è uno dei casi d’uso più immediati. Fatture scansionate, ricevute, screenshot di moduli — Claude legge il contenuto con precisione sorprendente, anche in presenza di font stilizzati o layout complessi. Rispetto ai classici motori OCR, Claude capisce il contesto semantico: non si limita a trascrivere caratteri, ma comprende la struttura del documento.
Questo si integra perfettamente con workflow di automazione. Se stai già usando l’AI per automatizzare la contabilità, aggiungere l’OCR via Claude API ti permette di processare fatture in formato immagine senza passare da servizi esterni.
import anthropic
import base64
import json
from pathlib import Path
client = anthropic.Anthropic(api_key="sk-ant-...")
def estrai_dati_fattura(path_immagine: str) -> dict:
# Estrae dati strutturati da una fattura in formato immagine
img_data = base64.standard_b64encode(
Path(path_immagine).read_bytes()
).decode("utf-8")
prompt = (
"Analizza questa fattura ed estrai i seguenti dati in formato JSON:\n"
"{\n"
' \"numero_fattura\": \"...\",\n'
' \"data_emissione\": \"YYYY-MM-DD\",\n'
' \"fornitore\": {\"nome\": \"...\", \"piva\": \"...\"},\n'
' \"cliente\": {\"nome\": \"...\", \"piva\": \"...\"},\n'
' \"totale\": 0.0\n'
"}\n"
"Rispondi SOLO con il JSON, senza testo aggiuntivo."
)
message = client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=2048,
messages=[{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": img_data,
},
},
{"type": "text", "text": prompt}
],
}],
)
risposta = message.content[0].text.strip()
# Rimuovi eventuali marcatori di codice se presenti
if risposta.startswith("```"):
risposta = risposta.split("```")[1]
if risposta.startswith("json"):
risposta = risposta[4:]
return json.loads(risposta.strip())
# Test
dati = estrai_dati_fattura("fattura_esempio.png")
print(f"Fattura N. {dati['numero_fattura']} - Totale: {dati['totale']} EUR")
Il trucco fondamentale è chiedere a Claude di rispondere solo con JSON. Questo rende il parsing deterministico e affidabile. Puoi aggiungere un layer di validazione con Zod se stai costruendo una pipeline TypeScript.
Caso d’Uso 2: Analisi Screenshot e Descrizione UI
Nei progetti di test automatizzato, uno degli step più costosi è la verifica visuale delle interfacce. Claude Vision risolve elegantemente questo problema: puoi passare screenshot al modello e chiedere descrizioni, individuazione di bug visivi, confronto tra stato atteso e reale. È utile anche per generare testi alternativi (alt) automatici per le immagini — migliorando accessibilità e SEO in un solo step.
import Anthropic from "@anthropic-ai/sdk";
import fs from "fs";
import path from "path";
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
// Analizza uno screenshot e restituisce una descrizione accessibile
async function descriviScreenshot(imagePath) {
const imageBuffer = fs.readFileSync(imagePath);
const base64Image = imageBuffer.toString("base64");
const ext = path.extname(imagePath).toLowerCase();
const mediaTypeMap = {
".png": "image/png",
".jpg": "image/jpeg",
".jpeg": "image/jpeg",
".webp": "image/webp",
};
const mediaType = mediaTypeMap[ext] || "image/png";
const message = await client.messages.create({
model: "claude-3-5-sonnet-20241022",
max_tokens: 512,
messages: [
{
role: "user",
content: [
{
type: "image",
source: {
type: "base64",
media_type: mediaType,
data: base64Image,
},
},
{
type: "text",
text: "Descrivi questa schermata UI in modo conciso per un alt text accessibile.\n"
+ "Poi indica:\n"
+ "1. Componenti principali visibili\n"
+ "2. Eventuali problemi di layout o accessibilita evidenti\n"
+ "3. Testo visibile (titoli, bottoni, label)\n"
+ "\nFormato: ALT: [...] COMPONENTI: [...] PROBLEMI: [...] TESTI: [...]",
},
],
},
],
});
return message.content[0].text;
}
// Confronta due screenshot e identifica le differenze UI
async function confrontaScreenshot(pathPrima, pathDopo) {
const toBase64 = (p) => fs.readFileSync(p).toString("base64");
const message = await client.messages.create({
model: "claude-3-5-sonnet-20241022",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
{ type: "text", text: "Confronta queste due screenshot UI. Elenca TUTTE le differenze visibili." },
{ type: "image", source: { type: "base64", media_type: "image/png", data: toBase64(pathPrima) } },
{ type: "image", source: { type: "base64", media_type: "image/png", data: toBase64(pathDopo) } },
],
},
],
});
return message.content[0].text;
}
descriviScreenshot("./screenshot-homepage.png").then(console.log);
Nota l’utilizzo di più immagini nello stesso messaggio: Claude accetta fino a 20 immagini per richiesta. Questo apre la strada a confronti, sequenze di frame e analisi comparative — qualcosa che nessun OCR tradizionale potrebbe fare.
Caso d’Uso 3: Moderazione Contenuti e Classificazione Immagini
Le piattaforme che accettano upload di immagini dagli utenti hanno bisogno di un layer di moderazione. Claude Vision gestisce questa pipeline con un approccio contestuale: non applica solo regole rigide, ma valuta l’immagine nel contesto del tuo prodotto. Questo si collega bene a workflow n8n o Make — se usi già n8n con Claude, aggiungere un nodo di vision check richiede solo di configurare l’HTTP Request con il payload giusto.
import anthropic
import base64
import json
from pathlib import Path
from dataclasses import dataclass
from typing import Literal
client = anthropic.Anthropic(api_key="sk-ant-...")
@dataclass
class RisultatoModerazione:
categoria: Literal["sicura", "attenzione", "rimossa"]
motivo: str
confidenza: float
tag: list
def modera_immagine(path_immagine: str,
contesto: str = "e-commerce artigianale") -> RisultatoModerazione:
img_data = base64.standard_b64encode(
Path(path_immagine).read_bytes()
).decode("utf-8")
ext = Path(path_immagine).suffix.lower().lstrip(".")
mt = {"png": "image/png", "jpg": "image/jpeg",
"jpeg": "image/jpeg", "webp": "image/webp"}
media_type = mt.get(ext, "image/jpeg")
prompt = (
f"Sei un sistema di moderazione per {contesto}.\n"
"Classifica in: sicura / attenzione / rimossa.\n"
"Rispondi in JSON: {categoria, motivo, confidenza, tag}. Solo JSON."
)
message = client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=256,
messages=[{"role": "user", "content": [
{"type": "image", "source": {
"type": "base64", "media_type": media_type, "data": img_data}},
{"type": "text", "text": prompt}
]}]
)
dati = json.loads(message.content[0].text.strip())
return RisultatoModerazione(**dati)
# Pipeline di upload sicuro
def gestisci_upload(path: str) -> bool:
r = modera_immagine(path)
if r.categoria == "sicura":
print(f"Approvata. Tag: {r.tag}")
return True
elif r.categoria == "attenzione":
print(f"Revisione richiesta: {r.motivo}")
return False
print(f"Rimossa: {r.motivo}")
return False
Analisi di Grafici e Dashboard: Vision per il Business Intelligence
Un caso d’uso meno ovvio ma estremamente potente: analizzare grafici, dashboard e report visivi. Se hai un tool di BI che genera screenshot, Claude Vision può interpretarli e produrre riepiloghi testuali, individuare trend anomali o rispondere a domande specifiche sui dati visualizzati. È utile per generare executive summary automatici o alimentare sistemi di RAG con Claude API che combinano dati testuali e visivi.
import Anthropic from "@anthropic-ai/sdk";
import * as fs from "fs";
const client = new Anthropic();
interface AnalisiGrafico {
tipo_grafico: string;
periodo: string;
metriche_principali: Record<string, string | number>;
trend: string;
anomalie: string[];
raccomandazioni: string[];
}
async function analizzaGraficoBI(
imagePath: string,
contesto?: string
): Promise<AnalisiGrafico> {
const imageData = fs.readFileSync(imagePath).toString("base64");
const systemPrompt = `Sei un analista di business intelligence.
${contesto ? `Contesto specifico: ${contesto}` : ""}`;
const message = await client.messages.create({
model: "claude-3-5-sonnet-20241022",
max_tokens: 1024,
system: systemPrompt,
messages: [{
role: "user",
content: [
{ type: "image", source: { type: "base64",
media_type: "image/png", data: imageData } },
{ type: "text", text:
"Analizza questo grafico e restituisci JSON con:\n"
+ "{ tipo_grafico, periodo, metriche_principali, trend, anomalie, raccomandazioni }\n"
+ "Solo JSON valido." }
]
}]
});
const raw = message.content[0].type === "text" ? message.content[0].text : "";
const jsonStr = raw.replace(/^```json?\n?/, "").replace(/\n?```$/, "").trim();
return JSON.parse(jsonStr) as AnalisiGrafico;
}
// Report settimanale con multiple dashboard
async function generaReport(screenshots: string[]): Promise<string> {
const images = screenshots.map((p) => ({
type: "image" as const,
source: { type: "base64" as const,
media_type: "image/png" as const,
data: fs.readFileSync(p).toString("base64") }
}));
const message = await client.messages.create({
model: "claude-3-5-sonnet-20241022",
max_tokens: 1024,
messages: [{ role: "user", content: [
{ type: "text", text: "Produci sommario esecutivo in italiano, max 300 parole." },
...images
]}]
});
return message.content[0].type === "text" ? message.content[0].text : "";
}
export { analizzaGraficoBI, generaReport };
Il pattern delle multiple immagini in un solo prompt è particolarmente potente per report multi-pagina. Puoi passare fino a 20 screenshot e chiedere a Claude di sintetizzare l’intera sessione. Il prompt caching entra in gioco qui: se il system prompt è lungo e stabile, cachelo per ridurre i costi fino al 90%.
Limiti, Costi e Best Practice
Prima di andare in produzione con la Claude API Vision, devi conoscere i limiti operativi e le strategie per ottimizzare i costi.
- Formati supportati: JPEG, PNG, GIF, WebP. PDF e SVG non sono supportati direttamente — convertili prima in PNG.
- Dimensione massima: 5MB per immagine. Per immagini più grandi, ridimensionale prima del passaggio all’API.
- Limite per richiesta: 20 immagini per singolo messaggio (limite attuale delle API Anthropic).
- Costo token: le immagini vengono tokenizzate automaticamente. Un’immagine 1024×1024 costa circa 1.600 token di input con claude-3-5-sonnet.
- Risoluzione e qualità: immagini a bassa risoluzione riducono la precisione dell’analisi. Usa almeno 512px sul lato più corto per OCR affidabile.
- Privacy: le immagini vengono elaborate e non memorizzate da Anthropic, ma verifica la policy aggiornata prima di processare dati sensibili.
Per il calcolo dei costi, usa questa formula approssimativa: token_immagine = (larghezza × altezza) / 750. Un’immagine 800×600 = circa 640 token. Con claude-3-5-sonnet a $3 per milione di input token, analizzare 1.000 fatture costa circa $2 in soli token immagine — decisamente competitivo rispetto ai servizi OCR dedicati. Se stai costruendo un tool commerciale, combina questa analisi con le funzionalità di Tool Use per creare agenti che non solo leggono le immagini ma agiscono di conseguenza.
from PIL import Image
import io
def ottimizza_per_api(path_input: str, path_output: str,
max_size_mb: float = 4.0,
max_dim: int = 2048) -> dict:
# Ridimensiona e ottimizza prima di inviare alla Claude API
with Image.open(path_input) as img:
if img.mode in ("RGBA", "P"):
img = img.convert("RGB")
w, h = img.size
if max(w, h) > max_dim:
ratio = max_dim / max(w, h)
new_w, new_h = int(w * ratio), int(h * ratio)
img = img.resize((new_w, new_h), Image.LANCZOS)
print(f"Ridimensionata: {w}x{h} -> {new_w}x{new_h}")
quality = 90
while True:
buffer = io.BytesIO()
img.save(buffer, format="JPEG", quality=quality, optimize=True)
size_mb = len(buffer.getvalue()) / (1024 * 1024)
if size_mb <= max_size_mb or quality <= 50:
break
quality -= 10
with open(path_output, "wb") as f:
f.write(buffer.getvalue())
w_final, h_final = img.size
token_stimati = (w_final * h_final) // 750
costo_per_1k = token_stimati / 1000 * 0.003
return {
"path": path_output,
"dimensioni": f"{w_final}x{h_final}",
"size_mb": round(size_mb, 2),
"token_stimati": token_stimati,
"costo_usd_stimato": round(costo_per_1k, 6),
}
# Pipeline completa
info = ottimizza_per_api("documento_originale.tiff", "documento_ottimizzato.jpg")
print(f"Pronto per API: {info}")
FAQ e Domande Frequenti
Claude Vision funziona anche con PDF?
Attualmente Claude API non accetta file PDF nativamente come input visivo. Il workaround standard è convertire ogni pagina del PDF in un’immagine PNG (strumenti come pdf2image in Python o pdftoppm da riga di comando). Puoi poi inviare le pagine come immagini separate nella stessa richiesta, fino a un massimo di 20 immagini. Per documenti molto lunghi, dividi la chiamata in batch. Anthropic ha annunciato il supporto nativo ai PDF per alcuni modelli: verifica sempre la documentazione aggiornata su docs.anthropic.com.
Posso usare la vision in modalità streaming?
Sì, la streaming API di Claude funziona anche con input multimodali. La struttura della richiesta è identica — aggiungi stream=True in Python o stream: true in JavaScript. Questo è particolarmente utile quando stai analizzando immagini complesse e vuoi mostrare il testo di risposta progressivamente all’utente, evitando tempi di attesa percepiti come lunghi.
Come gestisco immagini in input degli utenti in modo sicuro?
Mai passare direttamente a Claude un’immagine non validata caricata da un utente. Il flusso sicuro prevede: (1) validazione del tipo MIME lato server, (2) scan antivirus se necessario, (3) ridimensionamento che strippi metadati EXIF potenzialmente sensibili, (4) passaggio all’API in base64 senza esporre URL interni. Anthropic non memorizza le immagini elaborate, ma tu sei responsabile dei dati che invii. Leggi la privacy policy di Anthropic e, se operi in Europa, verifica la conformità GDPR per i dati biometrici nelle immagini di persone.
Quale modello scegliere per la vision: Haiku, Sonnet o Opus?
La scelta dipende dal caso d’uso. Claude 3 Haiku è il più veloce ed economico: ideale per moderazione in volume, OCR semplice, classificazione rapida. Claude 3.5 Sonnet è il miglior rapporto qualità/prezzo per la maggior parte dei casi: OCR complesso, analisi di UI, estrazione dati strutturati. Claude 3 Opus ha la maggiore capacità di ragionamento visivo: usalo per analisi scientifiche, interpretazione di grafici tecnici complessi, o quando la precisione è critica. Nel confronto tra LLM del 2026 trovi un’analisi dettagliata delle differenze prestazionali.
Conclusione
La Claude API Vision trasforma qualsiasi applicazione in un sistema capace di vedere e interpretare il mondo visivo. Con poche decine di righe di codice puoi aggiungere OCR intelligente, moderazione contestuale, analisi di dashboard e descrizione automatica di interfacce. La barriera tecnica è bassa — usi gli stessi endpoint, la stessa autenticazione, lo stesso SDK che già conosci. La differenza è nell’array content del messaggio.
I casi d’uso reali sono infiniti: dai workflow di contabilità automatica all’accessibilità web, dai sistemi di e-commerce alle pipeline di test. Il passo successivo è integrare la vision con il Tool Use per costruire agenti che non solo capiscono le immagini, ma agiscono di conseguenza. Benvenuto nell’era multimodale.
Suggerimenti e Risorse
🔧 Setup rapido: Installa l’SDK ufficiale con
pip install anthropiconpm install @anthropic-ai/sdk. La vision non richiede dipendenze extra — solo le stesse librerie che usi per il testo.
💡 Pro tip: Per ridurre i costi in produzione, pre-filtra le immagini con un check rapido (dimensioni, formato, checksum) prima di inviarle all’API. Eviti chiamate inutili e risparmi token su immagini corrotte o duplicate.
🎯 Strategia avanzata: Usa il Prompt Caching con system prompt dettagliati per la vision. Se il tuo prompt supera 1024 token e lo usi ripetutamente, la cache riduce il costo di input fino al 90% sulle chiamate successive.
