Integrare l'API di Claude nella tua applicazione

L'integrazione dell'API Claude è semplice il primo giorno: l'installazione di un SDK e una chiamata autenticata. Ma la preparazione per la produzione dipende dagli elementi che circondano quella chiamata: streaming, nuovi tentativi, budget di token e osservabilità. Questa guida copre l'intero percorso, con codice funzionante che puoi adattare direttamente.

Autenticazione e prima richiesta

Installa l'SDK ufficiale (pip install anthropic oppure npm install @anthropic-ai/sdk), imposta la chiave in una variabile d'ambiente, mai nel codice sorgente, ed esegui una chiamata alla Messages API per verificare il funzionamento della pipeline. L'API è versionata tramite un header anthropic-version che gli SDK impostano automaticamente.

Le chiavi funzionano allo stesso modo, sia che provengano dalla Anthropic Console sia da un gateway compatibile con Anthropic come AI Prime Tech (un servizio indipendente, non affiliato ad Anthropic): l'unica differenza è il base_url con cui viene creato il client.

Scegliere i modelli in base all'attività

Le integrazioni che fissano un unico modello nel codice spendono troppo o offrono prestazioni insufficienti. Instrada le richieste in base all'attività: Haiku 4.5 per classificazione, estrazione e instradamento; Sonnet 4.6 per la maggior parte delle funzionalità di prodotto e la programmazione; Opus 4.8 quando la profondità del ragionamento è il valore del prodotto; Fable 5 quando serve la finestra di contesto da 1M. Il confronto completo è disponibile in <a href="/it/learn/claude-api-models-compared/">Modelli Claude a confronto</a>.

Rendi il modello un valore di configurazione, non una costante: i nomi dei modelli cambiano ogni pochi mesi e vorrai eseguire test A/B sulle nuove versioni senza effettuare un deploy.

Streaming, timeout e tentativi successivi

Usa lo streaming per tutto ciò che una persona visualizza: gli eventi inviati dal server trasmettono i token man mano che vengono generati, riducendo la latenza percepita da molti secondi a meno di un secondo. Anche le chiamate senza streaming con valori elevati di max_tokens hanno maggiori probabilità di incorrere nei timeout di lettura del proxy: una categoria di bug che emerge solo in produzione.

Riprova le richieste con risposte 429 e 5xx usando un backoff esponenziale con jitter, rispetta gli header retry-after quando presenti e limita il numero totale di tentativi. Considera gli errori 400 come permanenti: il payload stesso è errato (spesso l'input è troppo grande; vedi <a href="/it/learn/claude-api-errors-troubleshooting/">Errori della Claude API</a>) e riprovare consuma soltanto la quota.

Checklist per la produzione

Prima del lancio: applica limiti ai token sia in ingresso sia in uscita; registra il costo di ogni richiesta (i dati di utilizzo vengono restituiti in ogni risposta); abilita la cache dei prompt per i prompt di sistema ripetuti; prevedi un modello o un endpoint di riserva per gli incidenti; ed esegui una revisione dei rischi di prompt injection se l'input dell'utente raggiunge il prompt.

La maggior parte delle difficoltà di integrazione non deriva dall'API stessa, ma dalla crescita illimitata del contesto e dalla mancanza di osservabilità. Registra i token in ingresso e in uscita fin dal primo giorno e le sorprese sui costi scompariranno.

import os, anthropic

client = anthropic.Anthropic(
    api_key=os.environ["ANTHROPIC_API_KEY"],
    base_url=os.environ.get("ANTHROPIC_BASE_URL", "https://aiprimetech.io"),
)

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Summarize our launch plan in 3 bullets."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Domande frequenti

AI Prime Tech è un gateway API indipendente. Non è affiliato ad Anthropic, non è approvato da Anthropic e non è un suo rivenditore. Claude e i nomi dei modelli correlati sono marchi dei rispettivi proprietari.