Usare le API di Claude (Anthropic) in Python: guida pratica

Se usi ChatGPT o Claude dal browser ma vuoi integrare l'intelligenza artificiale nei tuoi programmi, prima o poi dovrai passare alle API. Questa guida ti accompagna passo per passo nell'uso delle API di Claude, i modelli di Anthropic, con Python: dalla prima chiamata fino a funzioni avanzate come lo streaming, l'uso di strumenti (tool) e la cache dei prompt per risparmiare. Al termine saprai esattamente come far parlare il tuo codice con Claude.

A chi serve e cosa ti serve prima di iniziare

Questa guida e' pensata per chi sa scrivere un minimo di Python (funzioni, variabili, installare pacchetti con pip) e vuole costruire applicazioni con l'IA: chatbot, assistenti, strumenti di analisi testi, automazioni. Non servono conoscenze di machine learning. Ti serviranno:

• Python 3.9 o superiore installato (verifica con python --version).
• Un account sulla piattaforma di Anthropic e una chiave API (si crea dalla console dopo la registrazione).
• Un minimo di credito o un piano attivo: le API sono a consumo, si paga in base ai token usati.

Quale modello scegliere: Sonnet, Opus o Haiku

Anthropic offre una famiglia di modelli con un chiaro compromesso tra intelligenza, velocita' e costo. Ecco come orientarsi:

Modello	ID API	Quando usarlo
Claude Sonnet 5	claude-sonnet-5	La prima scelta per la maggior parte dei casi: ottimo rapporto qualita'/prezzo, veloce, adatto a produzione ad alto volume.
Claude Opus 5	claude-opus-5	I compiti piu' difficili: ragionamento complesso, coding avanzato, agenti a lungo orizzonte. Costa di piu'.
Claude Haiku 4.5	claude-haiku-4-5	Compiti semplici e ad alta frequenza dove conta la velocita' e il basso costo (classificazione, estrazione).

Consiglio pratico: parti da claude-sonnet-5. E' la scelta migliore come punto di partenza perche' offre qualita' vicina a Opus a un costo sensibilmente inferiore. Passa a Opus solo se noti che il compito e' troppo difficile, e a Haiku solo per compiti banali dove ti serve massima velocita'. Rispetto ad alternative come le API di OpenAI (GPT), Google Gemini o modelli locali via Ollama, il punto di forza di Claude e' la coerenza sui compiti lunghi e la finestra di contesto molto ampia; per contro, come tutti i servizi commerciali, invii i dati a un fornitore esterno e paghi a consumo.

Passo 1: installazione e prima chiamata

Installa la libreria ufficiale:

pip install anthropic

Imposta la chiave API come variabile d'ambiente, cosi' non la scrivi mai nel codice (buona pratica di sicurezza). Su Linux o macOS:

export ANTHROPIC_API_KEY="la-tua-chiave-qui"

Ora la prima chiamata. Crea un file test.py:

import anthropic

client = anthropic.Anthropic()  # legge ANTHROPIC_API_KEY dall'ambiente

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Spiega in 3 righe cos'e' un token in un modello linguistico."}
    ],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

Eseguilo con python test.py. Il risultato atteso e' una breve spiegazione stampata a schermo. Nota due cose: max_tokens limita la lunghezza della risposta, e response.content e' una lista di blocchi - controlla sempre block.type prima di leggere block.text.

Passo 2: il prompt di sistema e la conversazione

Il system prompt definisce il comportamento dell'assistente. La conversazione, invece, si costruisce alternando messaggi utente e assistente: l'API e' senza memoria, quindi ogni volta devi inviare l'intera cronologia.

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system="Sei un tutor di italiano paziente. Rispondi sempre con esempi concreti.",
    messages=[
        {"role": "user", "content": "Qual e' la differenza tra 'a' e 'ha'?"},
    ],
)

Per una conversazione a piu' turni, accumula i messaggi in una lista e aggiungi ogni risposta prima di inviare il turno successivo.

Passo 3: lo streaming per risposte in tempo reale

Per applicazioni interattive (chatbot) conviene lo streaming: il testo arriva parola per parola, come nel sito web. E' anche piu' robusto per risposte lunghe, perche' evita timeout.

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

Il risultato atteso e' il testo che appare progressivamente a schermo invece di comparire tutto insieme alla fine.

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

La funzione piu' potente per costruire agenti e' il "tool use": tu descrivi degli strumenti (funzioni), Claude decide quando chiamarli e con quali parametri, tu li esegui e restituisci il risultato. Ecco lo scheletro di uno strumento meteo:

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"],
    },
}]

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

# Se Claude vuole usare lo strumento, stop_reason sara' "tool_use".
# Esegui la tua funzione, poi rimanda il risultato con un blocco "tool_result".

Il ciclo completo prevede: Claude chiede lo strumento, tu esegui la funzione reale (una chiamata a un servizio meteo), restituisci il risultato in un messaggio con role: "user" contenente un blocco tool_result, e Claude formula la risposta finale. La libreria ufficiale offre anche un "tool runner" che automatizza questo ciclo.

Passo 5: risparmiare con la cache dei prompt

Se ripeti spesso lo stesso contesto lungo (istruzioni, documenti, esempi), la cache dei prompt puo' ridurre il costo fino a circa il 90% sulla parte ripetuta. Basta marcare il blocco stabile:

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system=[{
        "type": "text",
        "text": "TESTO_LUNGO_CON_LE_TUE_ISTRUZIONI...",
        "cache_control": {"type": "ephemeral"},
    }],
    messages=[{"role": "user", "content": "Domanda specifica"}],
)
print(response.usage.cache_read_input_tokens)  # token serviti dalla cache

La regola d'oro: metti all'inizio cio' che non cambia (istruzioni, documenti) e alla fine cio' che varia (la domanda). Se cache_read_input_tokens resta a zero su richieste ripetute, qualcosa nel prefisso cambia ogni volta (per esempio una data o un ID) e invalida la cache.

Un esempio completo: chatbot da terminale con memoria

Mettiamo insieme i pezzi in un piccolo assistente conversazionale che ricorda cio' che gli hai detto durante la sessione. E' lo scheletro di qualsiasi applicazione di chat:

import anthropic

client = anthropic.Anthropic()
messaggi = []
print("Assistente Claude - scrivi 'esci' per terminare")

while True:
    testo = input("Tu: ")
    if testo.strip().lower() == "esci":
        break
    messaggi.append({"role": "user", "content": testo})
    risposta = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        system="Sei un assistente conciso e gentile. Rispondi in italiano.",
        messages=messaggi,
    )
    testo_out = "".join(b.text for b in risposta.content if b.type == "text")
    print("Claude:", testo_out)
    messaggi.append({"role": "assistant", "content": testo_out})

La chiave e' la lista messaggi: a ogni giro aggiungiamo prima il messaggio dell'utente, poi la risposta dell'assistente. Cosi' Claude "vede" l'intera conversazione e puo' fare riferimento a cio' che e' stato detto prima. Attenzione: piu' lunga diventa la cronologia, piu' token invii (e paghi) a ogni turno; per conversazioni molto lunghe conviene, a un certo punto, riassumere i messaggi piu' vecchi.

Ottenere risposte in JSON strutturato

Spesso non vuoi testo libero ma dati pronti da usare nel codice: un elenco, un'etichetta, dei campi. Il modo piu' semplice e' chiederlo esplicitamente nel prompt e istruire Claude a rispondere solo con JSON valido:

import json

risposta = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=512,
    system="Rispondi SOLO con JSON valido, senza testo aggiuntivo.",
    messages=[{"role": "user", "content":
        "Estrai nome, citta' ed eta' da: 'Sono Luca, ho 34 anni e vivo a Bologna.'"}],
)
dati = json.loads(next(b.text for b in risposta.content if b.type == "text"))
print(dati["nome"], dati["citta"], dati["eta"])

Per garanzie piu' forti sul formato, l'SDK offre anche funzioni di output strutturato che validano la risposta contro uno schema: utili quando il JSON deve avere sempre la stessa forma esatta.

Errori comuni e come risolverli

• authentication_error (401): la chiave API manca o e' sbagliata. Verifica di aver esportato ANTHROPIC_API_KEY nella stessa shell da cui lanci lo script.
• not_found_error (404): l'ID del modello e' scritto male. Usa esattamente claude-sonnet-5, senza suffissi inventati.
• rate_limit_error (429): troppe richieste. La libreria riprova in automatico con attesa progressiva; per volumi alti valuta un piano superiore.
• Risposta troncata (stop_reason "max_tokens"): hai impostato max_tokens troppo basso. Aumentalo, e per risposte molto lunghe usa lo streaming.

Quando NON usare le API di Claude, e come proseguire

Le API commerciali non sono sempre la scelta giusta. Se lavori con dati molto sensibili che non possono uscire dai tuoi server, o vuoi azzerare i costi variabili, valuta un modello aperto in locale (con Ollama o LM Studio): rinunci a un po' di qualita' e velocita', ma guadagni controllo e privacy. Se invece la qualita' e la finestra di contesto ampia sono prioritarie e i dati non sono critici, le API di Claude restano una delle opzioni piu' solide. Da qui puoi proseguire costruendo un piccolo agente con tool use, aggiungendo la lettura di documenti PDF, oppure integrando Claude in un'applicazione web. La documentazione ufficiale di Anthropic e' il riferimento aggiornato per prezzi, limiti e funzioni piu' avanzate come l'output strutturato in JSON. Nota finale: gli identificatori dei modelli e i prezzi evolvono spesso, quindi verifica sempre i valori correnti prima di andare in produzione.