Le API di Anthropic permettono di integrare i modelli Claude in qualsiasi applicazione Python: assistenti, automazioni, analisi di documenti, agenti. In questa guida partiamo da zero e arriviamo a funzioni avanzate — streaming, uso di strumenti (function calling), analisi di immagini e prompt caching per tagliare i costi. Al termine avrai uno scheletro di codice funzionante e riutilizzabile.

A chi serve e cosa ti occorre

Questa guida e' pensata per chi sa programmare almeno un po' in Python e vuole usare Claude oltre la semplice chat sul sito. Ti servono: Python 3.8 o superiore installato, un account su console.anthropic.com con una chiave API attiva e un minimo di credito (le API sono a consumo, si paga in base ai token elaborati), e un terminale. Niente GPU: il calcolo avviene sui server di Anthropic, il tuo computer fa solo da client.

Quale modello scegliere

Anthropic offre tre famiglie, da bilanciare tra costo, velocita' e capacita':

  • claude-opus-4-7: il modello piu' potente, per ragionamento complesso, codice difficile e compiti agentici lunghi. E' il piu' costoso e il piu' lento.
  • claude-sonnet-4-6: l'equilibrio ideale tra qualita' e prezzo, ottimo per la maggior parte delle applicazioni in produzione. E' la scelta consigliata come punto di partenza.
  • claude-haiku-4-5: il piu' rapido ed economico, perfetto per classificazione, estrazione dati e compiti ad alto volume dove la velocita' conta.

Consiglio pratico: inizia con claude-sonnet-4-6; passa a Opus solo se la qualita' non basta, e ad Haiku se il volume di richieste rende il costo il fattore critico.

Passo 1: installazione e chiave API

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

pip install anthropic

# Linux/macOS
export ANTHROPIC_API_KEY="la-tua-chiave"

# Windows (PowerShell)
setx ANTHROPIC_API_KEY "la-tua-chiave"

Passo 2: la prima chiamata

Il cuore delle API e' l'endpoint Messages. Ecco la richiesta minima:

from anthropic import Anthropic

client = Anthropic()  # legge ANTHROPIC_API_KEY dall'ambiente

resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Spiega in tre frasi cos'e' la fotosintesi."}
    ],
)

print(resp.content[0].text)

La risposta arriva in resp.content, una lista di blocchi: per il testo si legge resp.content[0].text. Il parametro max_tokens e' obbligatorio e limita la lunghezza massima della risposta.

Passo 3: system prompt e conversazione a piu' turni

Il system prompt definisce ruolo e regole dell'assistente; la cronologia si mantiene accodando i messaggi nella lista, alternando i ruoli user e assistant:

messaggi = [
    {"role": "user", "content": "Ciao, mi chiamo Marco."},
    {"role": "assistant", "content": "Ciao Marco, come posso aiutarti?"},
    {"role": "user", "content": "Come mi chiamo?"},
]

resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=512,
    system="Sei un assistente conciso che risponde sempre in italiano.",
    messages=messaggi,
)
print(resp.content[0].text)  # -> "Ti chiami Marco."
Lo scheletro di codice e' riutilizzabile in qualsiasi progetto Python. (Foto: Pexels)

Passo 4: streaming, per risposte in tempo reale

Per mostrare il testo man mano che viene generato — come fa l'interfaccia di Claude — si usa lo streaming:

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

Lo streaming migliora molto la percezione di velocita' nelle interfacce utente e va quasi sempre preferito per le applicazioni interattive.

Passo 5: gli strumenti (function calling)

La funzione piu' potente e' la possibilita' di dare a Claude degli «strumenti»: funzioni del tuo codice che il modello puo' decidere di invocare. Tu descrivi lo strumento, Claude restituisce i parametri, tu esegui la funzione e gli ritorni il risultato.

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

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

if resp.stop_reason == "tool_use":
    blocco = next(b for b in resp.content if b.type == "tool_use")
    print("Claude vuole chiamare:", blocco.name, blocco.input)
    # qui esegui la tua funzione reale e rimandi il risultato con
    # un messaggio role="user" contenente un blocco "tool_result"

Questo schema e' la base di ogni agente: Claude ragiona, sceglie lo strumento giusto, riceve il risultato e prosegue. Il ciclo si ripete finche' il compito non e' concluso.

Passo 6: analizzare immagini

Claude e' multimodale: puoi inviargli un'immagine insieme alla domanda. Ecco l'esempio con un'immagine codificata in base64:

import base64

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

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

Passo 7: prompt caching, per pagare meno

Se invii spesso lo stesso contesto lungo — un manuale, il codice di un progetto, istruzioni dettagliate — il prompt caching permette di memorizzare quella parte sui server di Anthropic e riutilizzarla nelle richieste successive a costo molto ridotto. Basta marcare il blocco da memorizzare con cache_control:

documento_lungo = open("manuale.txt").read()

resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[
        {"type": "text", "text": "Sei un assistente che risponde solo in base al manuale fornito."},
        {"type": "text", "text": documento_lungo,
         "cache_control": {"type": "ephemeral"}},
    ],
    messages=[{"role": "user", "content": "Riassumi il capitolo 3."}],
)
print(resp.usage)  # mostra i token letti dalla cache

Alla prima richiesta paghi la scrittura della cache; dalle successive (entro pochi minuti) la lettura dei token memorizzati costa una frazione del prezzo normale. Su contesti grandi e ripetuti il risparmio puo' superare il 90%. Controlla sempre il campo resp.usage per verificare quanti token vengono letti dalla cache.

Capire i costi: come si pagano i token

Le API non hanno un canone fisso: si paga in base ai token elaborati, dove un token equivale grossomodo a tre quarti di una parola in italiano. La fatturazione distingue tra token in ingresso (quelli che invii: prompt, cronologia, documenti) e token in uscita (la risposta generata), con i secondi piu' costosi dei primi. Tre regole pratiche per tenere sotto controllo la spesa: scegli il modello piu' piccolo che svolge bene il compito (Haiku costa molto meno di Opus); limita max_tokens a quanto ti serve davvero; e usa il prompt caching descritto piu' avanti quando ripeti lo stesso contesto. Per stimare i consumi prima di andare in produzione, leggi sempre il campo resp.usage, che riporta il numero esatto di token in ingresso e in uscita di ogni chiamata.

Un errore tipico di chi inizia e' rispedire l'intera cronologia della conversazione a ogni messaggio: in una chat lunga, i token in ingresso crescono a ogni turno e con loro il costo. Per applicazioni con conversazioni estese conviene riassumere periodicamente i messaggi piu' vecchi, oppure usare il caching sulla parte stabile del contesto.

Buone pratiche di sicurezza

Tre accorgimenti fondamentali prima di mettere in produzione. Primo: non scrivere mai la chiave API nel codice sorgente ne' caricarla su repository pubblici; usa variabili d'ambiente o un gestore di segreti. Secondo: non passare ciecamente al modello input non controllati degli utenti se questi possono attivare strumenti che eseguono azioni reali — valida sempre cosa l'agente sta per fare. Terzo: imposta limiti di spesa nella console di Anthropic, cosi' un bug o un abuso non si traducono in una bolletta inaspettata.

Errori comuni e come risolverli

  • 401 authentication_error: la chiave API e' mancante o errata. Verifica che la variabile d'ambiente ANTHROPIC_API_KEY sia impostata nel terminale da cui lanci lo script.
  • 429 rate_limit_error: hai superato il limite di richieste o di token al minuto. Rallenta, introduci attese progressive (backoff) e, se serve, chiedi un aumento dei limiti dalla console.
  • 529 overloaded_error: i server sono temporaneamente sovraccarichi. Riprova dopo qualche secondo con backoff esponenziale.
  • Risposta troncata: se resp.stop_reason e' max_tokens, la risposta e' stata tagliata. Aumenta max_tokens.

Varianti, alternative e prossimi passi

Per progetti seri conviene gestire le chiamate in modo asincrono con AsyncAnthropic, aggiungere log e ritentativi automatici, e separare i prompt dal codice. Se non vuoi gestire l'infrastruttura, valuta i framework per agenti che si appoggiano a Claude. E ricorda che lo stesso modello e' raggiungibile anche tramite Amazon Bedrock e Google Vertex AI, utile se la tua azienda e' gia' su quei cloud. Quando NON usare le API dirette? Se ti serve solo chattare occasionalmente, l'app di Claude basta e avanza: le API hanno senso quando vuoi automatizzare, integrare o servire molti utenti.

Per approfondire, la documentazione ufficiale di Anthropic resta il riferimento piu' aggiornato su parametri, limiti e prezzi. Da questo scheletro — messaggi, streaming, strumenti, immagini e cache — puoi gia' costruire la quasi totalita' delle applicazioni reali basate su Claude.

Come esercizio finale, prova a mettere insieme i pezzi in un piccolo progetto completo: un assistente da terminale che mantiene la cronologia, usa lo streaming per mostrare le risposte in tempo reale e dispone di uno strumento «cerca sul web» che invochi con una tua funzione. Bastano poche decine di righe, ma tocchi tutti i concetti chiave visti qui. Quando funziona, sostituisci lo strumento finto con una vera ricerca o con l'accesso a un tuo database: a quel punto avrai costruito, di fatto, il tuo primo agente. Da li' in poi la differenza tra un esperimento e un prodotto sta nei dettagli — gestione degli errori, log, limiti di spesa, test — piu' che nelle capacita' del modello, che restano le stesse.