API di Claude (Anthropic) in Python: la guida pratica

Questa guida ti porta dalla creazione dell'account alla prima vera applicazione che parla con i modelli Claude di Anthropic via API, in Python. È pensata per chi sa scrivere un po' di codice ma non ha mai toccato le API di un modello linguistico, e arriva fino a temi avanzati come lo streaming e l'uso degli strumenti (tool use). È anche il momento giusto per impararlo: dal 15 giugno 2026 Anthropic ha separato l'uso programmatico di Claude dai limiti dell'abbonamento, spostandolo su un credito a consumo tariffato ai prezzi delle API. Capire come funzionano le chiamate — e quanto costano — non è più un dettaglio.

A chi serve, cosa otterrai e prerequisiti

Serve a sviluppatori, analisti e curiosi che vogliono integrare Claude in script, backend o automazioni: riassumere documenti, classificare testi, estrarre dati, costruire un piccolo assistente. Alla fine avrai uno script funzionante, saprai gestire system prompt, streaming e strumenti, e avrai chiaro come tenere sotto controllo i costi. Prerequisiti reali:

• Python 3.9 o superiore installato (verifica con python3 --version).
• Un account Anthropic con credito attivo, da creare su console.anthropic.com.
• Dimestichezza con il terminale e con i concetti base di Python (variabili, funzioni, dizionari).

Quale modello scegliere (e quanto costa)

Anthropic offre tre famiglie, dalla più potente alla più economica. La scelta è un compromesso tra qualità, velocità e costo:

Modello	Quando usarlo	Identificatore
Claude Opus 4.8	Compiti complessi: ragionamento, codice difficile, analisi lunghe	claude-opus-4-8
Claude Sonnet 4.6	Il cavallo di battaglia: ottimo equilibrio qualità-prezzo	claude-sonnet-4-6
Claude Haiku 4.5	Volumi alti, risposte rapide, costi minimi	claude-haiku-4-5

Regola pratica: parti da Sonnet 4.6 per quasi tutto, sali a Opus solo se la qualità non basta, scendi a Haiku per i compiti semplici e ripetitivi. I prezzi sono per milione di token (input e output separati) e cambiano nel tempo: controlla sempre il listino ufficiale. Ricorda che dopo il 15 giugno 2026 gli identificatori vecchi come claude-sonnet-4-20250514 non funzionano più: usa gli alias aggiornati della tabella.

Passo 1: crea la chiave API

Accedi a console.anthropic.com, vai nella sezione API Keys e genera una nuova chiave. Copiala subito: non potrai rivederla. Assegnale un nome che ricordi a cosa serve (es. «test-locale»). Non scrivere mai la chiave dentro il codice che condividi o carichi su GitHub: la tratteremo come variabile d'ambiente.

Passo 2: installa la libreria e imposta la chiave

Crea una cartella di progetto, poi un ambiente virtuale e installa il pacchetto ufficiale:

python3 -m venv venv
source venv/bin/activate    # su Windows: venv\Scripts\activate
pip install anthropic

Imposta la chiave come variabile d'ambiente, così la libreria la legge da sola:

export ANTHROPIC_API_KEY="sk-ant-la-tua-chiave"   # Windows: set ANTHROPIC_API_KEY=...

Passo 3: la prima chiamata

Crea un file prima.py con questo contenuto:

import anthropic

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

msg = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=500,
    messages=[
        {"role": "user", "content": "Spiega in 4 punti cos'e' un token in un LLM."}
    ],
)
print(msg.content[0].text)

Eseguilo con python prima.py. Il risultato atteso è una risposta in quattro punti. Nota tre cose: max_tokens limita la lunghezza della risposta (e quindi il costo in uscita); messages è la cronologia della conversazione; la risposta sta in msg.content[0].text.

Passo 4: dai una personalità con il system prompt

Il system prompt definisce ruolo e regole del modello, separati dalla conversazione. È il modo corretto per impostare il comportamento:

msg = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=600,
    system="Sei un assistente che risponde sempre in italiano, conciso, con esempi concreti. Se non sai una cosa, dillo.",
    messages=[
        {"role": "user", "content": "Consigliami una struttura per un articolo su 3 errori comuni nei prompt."}
    ],
)
print(msg.content[0].text)

Passo 5: streaming, per le risposte lunghe

Per mostrare il testo man mano che viene generato — come nella chat — usa lo streaming:

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

È utile per le interfacce interattive: l'utente vede subito che «qualcosa sta succedendo» invece di aspettare l'intera risposta.

Passo 6: tool use, far chiamare le tue funzioni al modello

La funzione più potente è il tool use: descrivi al modello degli strumenti (funzioni) e lui decide quando usarli, restituendoti i parametri con cui chiamarli. È il mattone di base degli agenti. Esempio con un «meteo» finto:

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

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

for blocco in msg.content:
    if blocco.type == "tool_use":
        print("Il modello vuole chiamare:", blocco.name, blocco.input)
        # qui esegui davvero la tua funzione con blocco.input["citta"]

Il modello non esegue nulla da solo: ti dice quale funzione vuole e con quali argomenti. Sta a te eseguirla e rimandargli il risultato (con un messaggio di ruolo user contenente un blocco tool_result) per ottenere la risposta finale. È così che si collegano i modelli al mondo reale: database, API, calcoli.

Errori comuni e come risolverli

• 401 authentication_error: chiave mancante o sbagliata. Verifica che ANTHROPIC_API_KEY sia impostata nello stesso terminale da cui lanci lo script.
• 404 not_found_error sul modello: stai usando un identificatore ritirato (es. claude-sonnet-4-20250514). Passa agli alias aggiornati.
• 429 rate_limit_error: troppe richieste o credito esaurito. Aggiungi attese con backoff esponenziale e controlla il budget nella console.
• Risposta troncata: hai impostato max_tokens troppo basso. Alzalo, ma ricorda che incide sul costo.

Come tenere i costi sotto controllo e come proseguire

Tre abitudini fanno la differenza: imposta un tetto di spesa nella console; scegli il modello giusto per ogni compito (non usare Opus per classificare email); e riusa il contesto in cache quando rimandi sempre lo stesso testo lungo. Dopo questi passi, le direzioni naturali sono: costruire un loop completo di tool use (un piccolo agente), collegare Claude ai tuoi dati con un sistema RAG, oppure usare la Claude Agent SDK per orchestrare attività complesse. La documentazione di riferimento è la Claude Developer Platform; per i concetti generali resta utile il sito di Anthropic. Se lavori molto con i modelli, vale la pena confrontare lo stesso codice con le API di OpenAI o di Google: la struttura è simile e saper passare dall'uno all'altro ti rende indipendente da un singolo fornitore.