Se hai gia' usato le API di OpenAI, Google Gemini o DeepSeek e vuoi aggiungere alla cassetta degli attrezzi anche i modelli Claude di Anthropic, questa guida ti porta dalla prima chiamata fino alle funzioni avanzate: streaming, uso degli strumenti (tool use), analisi di immagini e prompt caching per risparmiare. Tutto con codice Python funzionante che puoi copiare e adattare.

A chi serve e cosa ti serve prima di iniziare

Questa guida e' pensata per chi sa gia' scrivere un minimo di Python e vuole integrare Claude in uno script, un'app o un'automazione. Non serve essere esperti di IA. I prerequisiti concreti sono tre:

  • Python 3.9 o superiore installato sul tuo computer.
  • Un account su console.anthropic.com e una chiave API (si crea in pochi clic dalla sezione API Keys).
  • Un minimo di credito sul conto: le API sono a consumo, si paga in base ai token elaborati. I prezzi aggiornati sono sulla pagina ufficiale dei prezzi di Anthropic; conviene consultarli perche' cambiano nel tempo.

Quale modello Claude scegliere per il tuo compito

Anthropic offre una famiglia di modelli con profili diversi. La scelta giusta dipende dal compito:

  • Claude Fable 5 (nome tecnico claude-fable-5): il modello di punta, per ragionamenti complessi, coding impegnativo e compiti da agente a molti passaggi. Massima qualita', costo piu' alto.
  • Claude Sonnet 5 (claude-sonnet-5): l'equilibrio tra qualita' e costo, ottimo per la maggior parte dei casi d'uso in produzione.
  • Claude Haiku 4.5 (claude-haiku-4-5): il piu' veloce ed economico, perfetto per classificazione, estrazione, risposte brevi e volumi elevati.

Consiglio come prima scelta: parti da Sonnet 5 per sviluppare e testare, poi valuta di scalare verso Haiku per le operazioni semplici ad alto volume (per risparmiare) o verso Fable per i compiti dove la qualita' del ragionamento fa davvero la differenza. E' la strategia che tiene sotto controllo la bolletta senza sacrificare i risultati dove contano.

Con l'SDK ufficiale di Anthropic bastano poche righe per la prima chiamata a Claude.

Passo 1: installazione e prima chiamata

Installa l'SDK ufficiale e imposta la chiave come variabile d'ambiente (non scriverla mai nel codice):

pip install anthropic

# su Linux/macOS
export ANTHROPIC_API_KEY="la-tua-chiave"
# su Windows PowerShell
# setx ANTHROPIC_API_KEY "la-tua-chiave"

La prima chiamata e' questa:

from anthropic import Anthropic

client = Anthropic()  # legge ANTHROPIC_API_KEY dall'ambiente

msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system="Sei un assistente che risponde in italiano, in modo chiaro e conciso.",
    messages=[
        {"role": "user", "content": "Spiega cos'e' un token in un modello linguistico, con un esempio."},
    ],
)
print(msg.content[0].text)

Nota due differenze rispetto ad altre API: il prompt di sistema si passa nel parametro system separato (non dentro la lista dei messaggi) e il parametro max_tokens e' obbligatorio: indica il tetto di token della risposta.

Passo 2: conversazioni a piu' turni

Claude non ha memoria tra una chiamata e l'altra: per mantenere il contesto devi rimandare l'intera cronologia a ogni turno. Si costruisce una lista di messaggi alternando i ruoli user e assistant:

storia = [
    {"role": "user", "content": "Consigliami un linguaggio per iniziare a programmare."},
    {"role": "assistant", "content": "Python e' un'ottima scelta per iniziare."},
    {"role": "user", "content": "Perche' proprio Python e non JavaScript?"},
]

msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=storia,
)
print(msg.content[0].text)

Passo 3: risposte in streaming

Per le interfacce chat conviene mostrare il testo mentre viene generato, invece di aspettare la risposta completa. Si usa lo streaming:

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Scrivi una breve favola sulla pazienza."}],
) as stream:
    for testo in stream.text_stream:
        print(testo, end="", flush=True)

Passo 4: far usare a Claude i tuoi strumenti (tool use)

La funzione piu' potente e' il tool use: descrivi a Claude delle funzioni che puo' chiamare (per esempio consultare un meteo, cercare in un database, fare un calcolo), e il modello decide quando invocarle. Ecco lo schema di base:

tools = [{
    "name": "get_meteo",
    "description": "Restituisce il meteo attuale per una citta'.",
    "input_schema": {
        "type": "object",
        "properties": {
            "citta": {"type": "string", "description": "Nome della citta'"}
        },
        "required": ["citta"],
    },
}]

msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "Che tempo fa a Milano?"}],
)

# Se Claude decide di usare lo strumento, lo segnala:
if msg.stop_reason == "tool_use":
    blocco = next(b for b in msg.content if b.type == "tool_use")
    print("Claude vuole chiamare:", blocco.name, "con", blocco.input)

Il flusso completo prevede che tu esegua davvero la funzione (nel tuo codice), poi rimandi il risultato a Claude con un messaggio di ruolo user contenente un blocco tool_result, e Claude formuli la risposta finale in linguaggio naturale. E' il mattone su cui si costruiscono gli agenti.

Passo 5: analizzare immagini

I modelli Claude sono multimodali: possono leggere immagini. Si passa l'immagine (in base64 o via URL) dentro il contenuto del messaggio:

import base64

with open("grafico.png", "rb") as f:
    dati = base64.standard_b64encode(f.read()).decode("utf-8")

msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {"type": "image", "source": {
                "type": "base64", "media_type": "image/png", "data": dati}},
            {"type": "text", "text": "Descrivi cosa mostra questo grafico."},
        ],
    }],
)
print(msg.content[0].text)

Passo 6: prompt caching per pagare meno

Se invii spesso lo stesso testo lungo all'inizio (per esempio un manuale, un documento di riferimento o istruzioni corpose), il prompt caching ti permette di riutilizzarlo a costo ridotto invece di pagarlo per intero a ogni chiamata. Basta marcare la porzione da mettere in cache:

msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system=[
        {"type": "text", "text": "Sei un assistente legale."},
        {"type": "text", "text": TESTO_MOLTO_LUNGO,
         "cache_control": {"type": "ephemeral"}},
    ],
    messages=[{"role": "user", "content": "Riassumi l'articolo 5."}],
)

Il primo invio scrive la cache (con un piccolo sovrapprezzo), i successivi la rileggono a una frazione del costo. Su applicazioni che riusano lo stesso contesto e' un risparmio notevole.

Errori comuni e come risolverli

  • "authentication_error" / 401: la chiave e' assente o sbagliata. Verifica che ANTHROPIC_API_KEY sia impostata nell'ambiente da cui lanci lo script.
  • "rate_limit_error" / 429: troppe richieste in poco tempo. Inserisci una pausa e riprova con backoff esponenziale; l'SDK gestisce alcuni retry in automatico.
  • Risposta troncata: hai impostato max_tokens troppo basso. Aumentalo se il testo si interrompe a meta'.
  • "invalid_request_error" sui messaggi: spesso e' l'alternanza dei ruoli non rispettata (due messaggi user di fila) o il campo system messo per errore dentro messages.

Quando conviene Claude e quando guardare altrove

I modelli Claude brillano su ragionamento lungo, scrittura curata, coding e compiti da agente con tool use. Se il tuo caso d'uso e' uno di questi, sono tra le scelte migliori. Per compiti banali ad altissimo volume, valuta il costo rispetto a modelli aperti eseguiti in locale (come GLM o Qwen), che a volume possono risultare piu' economici. La regola resta quella: scegli il modello in base al compito, non per abitudine. Per approfondire, la documentazione ufficiale di Anthropic e' il riferimento da tenere aperto mentre sviluppi; parti da un piccolo script, aggiungi una funzione alla volta e misura sempre token e costi.