Claude, il modello di Anthropic, e' tra gli assistenti piu' apprezzati per scrittura, analisi e programmazione. Usarlo via interfaccia web e' comodo, ma il vero potere si sblocca con le API: integrare Claude nei tuoi script, in un'app o in un flusso di automazione. Questa guida ti porta da zero alla prima chiamata funzionante in Python, fino a streaming, output strutturato e analisi di immagini. Se hai gia' seguito le nostre guide alle API di OpenAI, Gemini e DeepSeek, qui ritroverai una logica simile ma con le specificita' di Anthropic.

A chi serve e cosa ti occorre

Questa guida e' pensata per chi sa scrivere qualche riga di Python e vuole automatizzare compiti di testo: riassumere documenti, classificare email, estrarre dati, generare bozze, costruire un piccolo assistente. I prerequisiti reali sono pochi:

  • Python 3.8 o superiore installato (verifica con python --version).
  • Un account su console.anthropic.com e una chiave API.
  • Un minimo di credito: l'uso delle API e' a pagamento, conteggiato sui token (i "pezzi" di testo) in ingresso e in uscita. Per imparare bastano pochi euro.

Passo 1: creare la chiave API

Accedi a console.anthropic.com, vai nella sezione API Keys e genera una nuova chiave. Copiala subito e conservala in un posto sicuro: non sara' piu' visibile per intero. Non scrivere mai la chiave dentro il codice che condividi o pubblichi: usala come variabile d'ambiente. Su Linux e macOS:

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

Su Windows (PowerShell):

setx ANTHROPIC_API_KEY "la-tua-chiave-qui"

Passo 2: installare l'SDK

Anthropic mette a disposizione una libreria ufficiale per Python. Installala con pip, preferibilmente dentro un ambiente virtuale per non sporcare il sistema:

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

Passo 3: la prima chiamata

Il cuore delle API di Anthropic e' la Messages API. Si invia una lista di messaggi (con ruolo "user" o "assistant") e si riceve la risposta del modello. Ecco lo script minimo:

import anthropic

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

risposta = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Spiega in 3 frasi cos'e' un'API, per un principiante."}
    ],
)

print(risposta.content[0].text)

Due parametri sono obbligatori e meritano attenzione. model indica quale Claude usare: la famiglia comprende Opus (il piu' potente, per i compiti difficili), Sonnet (l'equilibrato, ottimo rapporto qualita'/prezzo) e Haiku (il piu' rapido ed economico). max_tokens fissa la lunghezza massima della risposta: serve sempre, ed evita output troppo lunghi e costosi.

Passo 4: il system prompt, per dare un ruolo a Claude

A differenza di OpenAI, in Anthropic il "messaggio di sistema" non va nella lista dei messaggi ma in un parametro dedicato, system. E' qui che definisci personalita', tono e regole dell'assistente:

risposta = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=800,
    system="Sei un assistente editoriale italiano. Rispondi sempre in italiano, "
           "con tono chiaro e professionale. Non inventare fatti.",
    messages=[
        {"role": "user", "content": "Scrivi un titolo e un sommario per un articolo sulle auto elettriche."}
    ],
)
print(risposta.content[0].text)
Il system prompt definisce ruolo e regole dell-assistente. Immagine: Pexels.

Passo 5: conversazioni a piu' turni

Claude non ha memoria tra una chiamata e l'altra: per mantenere il filo di un dialogo devi rispedire l'intera conversazione ogni volta, accodando i nuovi messaggi. Lo schema e' questo:

storia = []

def chiedi(testo):
    storia.append({"role": "user", "content": testo})
    r = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=600,
        messages=storia,
    )
    testo_risposta = r.content[0].text
    storia.append({"role": "assistant", "content": testo_risposta})
    return testo_risposta

print(chiedi("Consigliami una citta' europea per un weekend a giugno."))
print(chiedi("E qualcosa da mangiare tipico di quel posto?"))

Nella seconda domanda Claude "ricorda" la citta' suggerita solo perche' gliela stai rimandando dentro storia. Attenzione: piu' lunga e' la conversazione, piu' token consumi a ogni chiamata.

Passo 6: lo streaming, per risposte in tempo reale

Per applicazioni interattive (come una chat) conviene ricevere il testo man mano che viene generato, invece di aspettare la risposta completa. Si usa il metodo stream:

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

Passo 7: ottenere un output JSON pulito

Spesso non vuoi un testo discorsivo ma dati strutturati da riusare nel programma. Il modo piu' semplice e' chiederlo esplicitamente nel prompt e, come trucco, "precaricare" l'inizio della risposta dell'assistente con una parentesi graffa, cosi' Claude prosegue con il JSON:

r = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=400,
    system="Rispondi SOLO con JSON valido, senza testo aggiuntivo.",
    messages=[
        {"role": "user", "content": "Estrai nome, citta' e professione da: 'Sono Luca, faccio il cuoco a Napoli'."},
        {"role": "assistant", "content": "{"}
    ],
)
print("{" + r.content[0].text)

Questa tecnica, chiamata prefill, e' una delle peculiarita' di Claude e riduce molto il rischio che il modello aggiunga frasi di contorno prima o dopo il JSON.

Passo 8: analizzare un'immagine

Claude e' multimodale: puo' leggere le immagini. Si passa l'immagine codificata in base64 dentro il contenuto del messaggio, insieme alla domanda testuale:

import base64

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

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

Errori comuni e come risolverli

  • "authentication_error" / 401: la chiave non e' impostata o e' sbagliata. Verifica la variabile d'ambiente con echo $ANTHROPIC_API_KEY e riavvia il terminale.
  • "rate_limit_error" / 429: troppe richieste in poco tempo. Inserisci una pausa tra le chiamate o gestisci il retry con attesa progressiva.
  • "invalid_request_error": spesso manca max_tokens o il nome del modello e' scritto male. Ricontrolla i parametri obbligatori.
  • Credito esaurito: se le chiamate falliscono all'improvviso, controlla il saldo nella console.

Costi, alternative e quando non usare le API

Il prezzo dipende dal modello e dal numero di token: Haiku costa una frazione di Opus, quindi conviene usare il modello piu' leggero che svolge bene il compito e riservare Opus ai problemi davvero complessi. Per i numeri aggiornati consulta sempre la pagina prezzi ufficiale, che cambia nel tempo.

Rispetto alle API di OpenAI, quelle di Claude brillano nei compiti di scrittura lunga, ragionamento e analisi di documenti, e offrono finestre di contesto molto ampie. Quando invece ti serve solo una chat occasionale, senza integrazione in un programma, l'interfaccia web e' piu' che sufficiente: le API hanno senso quando vuoi automatizzare, ripetere o inserire Claude in un prodotto. Da qui puoi proseguire verso argomenti piu' avanzati come il tool use, che permette a Claude di chiamare funzioni e strumenti esterni.