Sapere usare le API di Claude, i modelli di Anthropic, apre la porta a un mondo di applicazioni: chatbot personalizzati, strumenti di riassunto, estrazione dati, assistenti che chiamano funzioni del tuo software. Questa guida ti accompagna dalla prima chiamata a Python fino allo streaming, alla gestione delle conversazioni e all'uso degli strumenti, con codice funzionante e i prezzi aggiornati per scegliere il modello giusto.

A chi serve e cosa otterrai

La guida è pensata per chi sa già programmare un minimo in Python e vuole integrare un modello linguistico nelle proprie applicazioni. Al termine saprai autenticarti, inviare messaggi, ricevere risposte in tempo reale, mantenere il contesto di una conversazione, forzare risposte in formato JSON e far usare a Claude degli strumenti (function calling). Non serve conoscere il machine learning: bastano le basi di Python.

Prerequisiti reali

  • Un account Anthropic e una chiave API, generata dalla console per sviluppatori su console.anthropic.com.
  • Python 3.8 o superiore.
  • Crediti sul tuo account: l'uso delle API è a consumo, si paga per token elaborati.

Quale modello scegliere e quanto costa

Anthropic offre più modelli, con un compromesso tra intelligenza, velocità e costo. Ecco i principali e i prezzi per milione di token (input/output):

ModelloIDInput ($/M)Output ($/M)Quando usarlo
Claude Opus 5claude-opus-55,0025,00Ragionamento complesso, agenti, coding difficile
Claude Sonnet 5claude-sonnet-53,0015,00Equilibrio qualità/costo per la produzione
Claude Haiku 4.5claude-haiku-4-51,005,00Compiti semplici e ad alta velocità

Come regola pratica: parti da Sonnet 5 per la maggior parte dei casi, sali a Opus 5 quando la qualità del ragionamento è cruciale, scendi a Haiku 4.5 per classificazioni o compiti semplici ad alto volume dove conta la velocità. La documentazione ufficiale è su docs.anthropic.com.

Con poche righe di Python si integra Claude in un'applicazione: dal riassunto all'estrazione dati agli agenti.

Passo 1: installazione e chiave API

Installa la libreria ufficiale e imposta la chiave come variabile d'ambiente (non scriverla mai direttamente nel codice):

pip install anthropic

# macOS/Linux:
export ANTHROPIC_API_KEY="la-tua-chiave"
# Windows (PowerShell):
setx ANTHROPIC_API_KEY "la-tua-chiave"

Passo 2: la prima chiamata

La libreria legge automaticamente la chiave dalla variabile d'ambiente. Ecco una richiesta minima:

import anthropic

client = anthropic.Anthropic()

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

# La risposta è una lista di blocchi: controlla il tipo prima di leggere il testo
for block in response.content:
    if block.type == "text":
        print(block.text)

Il parametro max_tokens è il limite massimo di token in uscita: tienilo abbastanza alto da non troncare la risposta (per risposte lunghe, valori come 4000-16000).

Passo 3: il system prompt

Il «system prompt» definisce il ruolo e il comportamento del modello. Si passa con il parametro system, separato dai messaggi dell'utente:

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system="Sei un assistente che risponde sempre in italiano, in modo conciso e con esempi pratici.",
    messages=[{"role": "user", "content": "Come leggo un file JSON in Python?"}],
)

Passo 4: risposte in tempo reale (streaming)

Per un'interfaccia di chat, mostrare la risposta parola per parola migliora l'esperienza. Con lo streaming il testo arriva a pezzi man mano che viene generato:

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

Passo 5: conversazioni a più turni

Le API sono «senza stato»: il modello non ricorda i messaggi precedenti a meno che tu non glieli reinvii ogni volta. Per una conversazione, accumula i turni nella lista messages:

messaggi = []

def chiedi(testo_utente):
    messaggi.append({"role": "user", "content": testo_utente})
    r = client.messages.create(
        model="claude-sonnet-5", max_tokens=1024, messages=messaggi
    )
    risposta = next(b.text for b in r.content if b.type == "text")
    messaggi.append({"role": "assistant", "content": risposta})
    return risposta

print(chiedi("Mi chiamo Marco."))
print(chiedi("Come mi chiamo?"))  # il modello ricorda: "Marco"

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

La funzione più potente: puoi descrivere delle «funzioni» (strumenti) e lasciare che il modello decida quando chiamarle, per esempio per consultare un database o un'API meteo. Il modello non esegue il codice: ti restituisce quale strumento vuole usare e con quali argomenti; sei tu a eseguirlo e a rimandare il risultato.

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

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

for block in r.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 come tool_result

Passo 7: risposte in JSON strutturato

Per pipeline che devono elaborare l'output, conviene ottenere JSON valido e prevedibile. Il modo più robusto è vincolare il formato con output_config, indicando lo schema atteso:

r = client.messages.create(
    model="claude-sonnet-5", max_tokens=1024,
    messages=[{"role": "user", "content": "Estrai nome ed email da: Marco Rossi, marco@example.com"}],
    output_config={"format": {"type": "json_schema", "schema": {
        "type": "object",
        "properties": {"nome": {"type": "string"}, "email": {"type": "string"}},
        "required": ["nome", "email"],
        "additionalProperties": False,
    }}},
)
import json
dati = json.loads(next(b.text for b in r.content if b.type == "text"))
print(dati["nome"], dati["email"])

Ridurre i costi: il prompt caching

Se riinvii spesso lo stesso contesto (per esempio un lungo documento o istruzioni fisse), il «prompt caching» permette di riutilizzarlo a costo ridotto. Basta marcare il blocco stabile con cache_control: le richieste successive con lo stesso prefisso pagano una frazione del prezzo per la parte in cache. È il modo più semplice per abbattere i costi in applicazioni con contesto ripetuto.

Errori comuni e soluzioni

  • 401 authentication_error → chiave API mancante o errata. Verifica la variabile d'ambiente ANTHROPIC_API_KEY e riapri il terminale.
  • 404 not_found_error → ID del modello sbagliato. Usa esattamente le stringhe della tabella (per esempio claude-sonnet-5), senza suffissi inventati.
  • 429 rate_limit_error → troppe richieste. La libreria riprova automaticamente con attesa crescente; per volumi alti, controlla i limiti del tuo piano.
  • Risposta troncata → max_tokens troppo basso: aumentalo, e per risposte lunghe usa lo streaming.

Quando NON usare le API cloud

Le API sono ideali per potenza, semplicità e nessuna gestione di hardware. Ma non sono sempre la scelta giusta: se hai vincoli stringenti di privacy che vietano di inviare dati a servizi esterni, o vuoi costo marginale zero su grandi volumi, valuta un modello open source eseguito in locale (con strumenti come Ollama o LM Studio). Il compromesso è tra comodità e qualità delle API da un lato, e controllo e riservatezza del locale dall'altro.

Prossimi passi: dagli agenti alla ricerca sui tuoi dati

Con queste basi puoi costruire applicazioni reali: un assistente che risponde su documenti aziendali (combinando le API con una ricerca sui tuoi dati), un agente che concatena più strumenti, o un servizio di classificazione automatica. Il passo successivo è approfondire il «tool use» per costruire agenti, e i parametri di ragionamento avanzato dei modelli più recenti. La documentazione ufficiale contiene esempi per ogni funzione.

Guida basata sulla documentazione ufficiale di Anthropic e sull'SDK Python, verificata allo stato attuale di modelli e prezzi. AI Notizie applica revisione editoriale umana.