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

Se hai gia' usato ChatGPT o Claude dal browser e vuoi fare il passo successivo - integrare l'intelligenza artificiale nei tuoi programmi, automatizzare un flusso di lavoro o costruire un piccolo assistente - le API di Anthropic sono uno dei modi piu' solidi per farlo. Questa guida ti porta dalla chiave d'accesso al primo programma funzionante, fino a funzioni avanzate come lo streaming, il ragionamento adattivo, i "tool" e l'output in JSON. Il linguaggio scelto e' Python, il piu' usato per questo genere di compiti.

A chi serve e cosa ti occorre

Questa guida e' pensata per chi sa scrivere qualche riga di Python ma non ha mai usato un'API di IA. Al termine saprai fare chiamate a Claude dal tuo codice, gestire risposte in tempo reale e far usare al modello degli strumenti esterni. Ti servono: Python 3.9 o superiore installato, un terminale, un account su console.anthropic.com e una carta per attivare il credito (le API sono a consumo, ma bastano pochi euro per tutte le prove di questa guida).

1) Ottieni la chiave API

Accedi alla Console di Anthropic, vai nella sezione delle chiavi (API Keys) e creane una nuova. Copiala e conservala: verra' mostrata una sola volta. Non inserirla mai direttamente nel codice ne' pubblicarla su GitHub. Il modo corretto e' salvarla in una variabile d'ambiente:

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

Su Windows (PowerShell) usa invece setx ANTHROPIC_API_KEY "la-tua-chiave-qui" e riapri il terminale.

2) Installa l'SDK ufficiale

pip install anthropic

La prima chiamata a Claude

Ecco il programma minimo. Il client legge automaticamente la chiave dalla variabile d'ambiente, quindi non serve passarla a mano:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Spiega in tre frasi cos'e' un'API."}
    ],
)

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

Il risultato atteso e' una risposta di poche frasi stampata a schermo. Nota due dettagli importanti: max_tokens e' il limite massimo di lunghezza della risposta (in "token", frammenti di parola), e response.content e' una lista di blocchi - per questo controlliamo block.type == "text" prima di leggere il testo.

Scegliere il modello giusto

Anthropic offre piu' modelli, con un compromesso tra intelligenza, velocita' e costo. Ecco i principali e i loro prezzi per milione di token (input/output):

Modello	ID da usare	Prezzo (input/output)	Quando usarlo
Claude Opus 4.8	claude-opus-4-8	5 / 25 $	Compiti complessi, ragionamento, codice
Claude Sonnet 5	claude-sonnet-5	3 / 15 $ (introduttivi 2 / 10 $ fino al 31 agosto)	Uso quotidiano ad alto volume
Claude Haiku 4.5	claude-haiku-4-5	1 / 5 $	Compiti semplici, massima velocita'

Prima scelta consigliata: Opus 4.8 quando conta la qualita', Sonnet 5 quando conta il rapporto qualita'-prezzo su molte richieste, Haiku 4.5 per classificazioni o risposte brevissime.

Un prompt di sistema per dare istruzioni

Il campo system serve a definire il comportamento del modello, separato dal messaggio dell'utente:

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=800,
    system="Sei un assistente che risponde sempre in italiano, con tono conciso e professionale.",
    messages=[{"role": "user", "content": "Riassumi i vantaggi del cloud in 5 punti."}],
)

Streaming: la risposta parola per parola

Per le risposte lunghe conviene lo streaming, che mostra il testo mentre viene generato ed evita timeout. L'SDK offre un helper comodo:

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=2000,
    messages=[{"role": "user", "content": "Scrivi un breve racconto sul mare."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Il risultato atteso e' il testo che compare progressivamente a schermo, come in una chat.

Ragionamento adattivo (thinking)

I modelli recenti possono "ragionare" prima di rispondere. Con il thinking adattivo e' il modello a decidere quanto pensare. Attenzione: sui modelli attuali (Opus 4.8, Sonnet 5) il vecchio parametro budget_tokens non va piu' usato - va sostituito con il tipo adaptive e, se serve, il livello di sforzo:

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4000,
    thinking={"type": "adaptive", "display": "summarized"},
    output_config={"effort": "high"},   # low | medium | high | xhigh | max
    messages=[{"role": "user", "content": "Un treno parte alle 9:15 e arriva alle 12:40, con 20 minuti di sosta. Quanto dura il viaggio effettivo?"}],
)
for block in response.content:
    if block.type == "thinking":
        print("[ragionamento]", block.thinking)
    elif block.type == "text":
        print("[risposta]", block.text)

Il campo display: "summarized" restituisce un riassunto leggibile del ragionamento; senza di esso i blocchi di pensiero arrivano vuoti. Alza effort per problemi difficili, abbassalo per risparmiare token su compiti semplici.

Tool use: far usare a Claude i tuoi strumenti

La funzione piu' potente e' il "tool use": descrivi una funzione, e il modello decide quando chiamarla passandoti i parametri. Sei tu a eseguirla e a restituire il risultato. Esempio con una finta funzione 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"],
    },
}]

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

for block in msg.content:
    if block.type == "tool_use":
        print("Il modello vuole chiamare:", block.name, "con", block.input)
        # Qui esegui la tua funzione reale e rimandi il risultato con un messaggio
        # di tipo "tool_result" e lo stesso tool_use_id (block.id).

Il risultato atteso e' che, invece di inventare il meteo, il modello ti chieda di eseguire get_meteo con {"citta": "Milano"}. Il ciclo si chiude rimandando un blocco tool_result. Per chi vuole automatizzare tutto il ciclo, l'SDK offre anche un "tool runner" in beta che gestisce da solo il loop.

Output strutturato: ottenere JSON valido

Se ti serve una risposta in un formato preciso (per salvarla in un database, per esempio), usa l'estrazione strutturata con una classe Pydantic:

from pydantic import BaseModel
import anthropic

class Contatto(BaseModel):
    nome: str
    email: str
    interesse: str

client = anthropic.Anthropic()
resp = client.messages.parse(
    model="claude-opus-4-8", max_tokens=500,
    messages=[{"role": "user", "content": "Estrai: Mario Rossi (mario@rossi.it) e' interessato al piano Business."}],
    output_format=Contatto,
)
print(resp.parsed_output.nome, resp.parsed_output.email)

Il risultato e' un oggetto Contatto gia' validato, senza bisogno di analizzare il testo a mano.

Gestire gli errori

In produzione conviene gestire i casi di errore con le eccezioni tipizzate dell'SDK, invece di controllare il testo del messaggio:

import anthropic
try:
    response = client.messages.create(model="claude-opus-4-8", max_tokens=100,
        messages=[{"role": "user", "content": "Ciao"}])
except anthropic.RateLimitError:
    print("Troppe richieste: riprova tra qualche secondo.")
except anthropic.AuthenticationError:
    print("Chiave API non valida.")
except anthropic.APIStatusError as e:
    print("Errore API:", e.status_code)

L'SDK riprova automaticamente gli errori temporanei (429 e 5xx) con backoff esponenziale, quindi spesso non devi fare nulla di piu'.

Errori comuni e soluzioni

• "authentication_error" (401): la variabile ANTHROPIC_API_KEY non e' impostata o e' sbagliata. Verifica di aver riaperto il terminale dopo averla definita.
• Risposta troncata (stop_reason: "max_tokens"): hai messo un max_tokens troppo basso. Aumentalo, o passa allo streaming per risposte lunghe.
• Errore 400 con budget_tokens o temperature: su Opus 4.8 e Sonnet 5 questi parametri non sono piu' accettati. Usa thinking: {"type": "adaptive"} e guida il comportamento con il prompt.
• ID modello con data (es. claude-opus-4-8-20260101): usa sempre l'alias esatto senza suffissi di data, altrimenti ottieni un 404.

Quando non usare le API (e come proseguire)

Le API sono la scelta giusta quando devi integrare l'IA in un software o automatizzare compiti ripetibili. Se ti serve solo chattare occasionalmente, l'app o il sito di Claude sono piu' semplici e spesso piu' economici. Per volumi molto alti e non urgenti, valuta la Batch API, che dimezza i costi elaborando le richieste in modo asincrono. Da qui puoi proseguire costruendo un vero agente con il tool use, aggiungendo la memoria della conversazione (l'API e' senza stato: devi rimandare lo storico a ogni chiamata) e sperimentando il prompt caching per abbattere i costi quando riusi lo stesso contesto. La documentazione ufficiale di Anthropic e' il riferimento sempre aggiornato per ogni funzione.

I comandi e gli ID modello di questa guida sono aggiornati a luglio 2026; verifica sempre modelli e prezzi sulla documentazione ufficiale, che puo' cambiare nel tempo.