Come integrare l'API di Claude nella tua app
Per integrare l'API di Claude, crea una chiave API nella Claude Console di Anthropic, conservala come segreto lato server (di solito ANTHROPIC_API_KEY) e chiama la Messages API da una route del tuo server usando uno degli SDK ufficiali di Anthropic. Ogni richiesta indica un model, imposta max_tokens (la risposta più lunga che accetti) e invia la conversazione come messages, con le tue istruzioni in un system prompt separato. Imposta un limite di spesa, usa lo streaming per le risposte lunghe e gestisci gli errori di limite di frequenza (429) e di sovraccarico (529) con nuovi tentativi.
Questa guida copre la configurazione, un flusso di richiesta sicuro, i prompt per un builder AI e gli errori da mettere in conto. I dettagli su Anthropic sono tratti dalla sua documentazione aggiornata a settembre 2026. Per capire in generale come funzionano token e prezzi, vedi come usare le API LLM.
Cosa puoi costruire
- Assistenti chat e widget di aiuto (come creare un'app chatbot AI)
- Riassunti, riscritture e risposte bozza
- Estrazione di campi da documenti, email e moduli
- Risposte a domande sui tuoi contenuti
- Agenti che richiamano le funzioni della tua app tramite tool use
Per altre idee, vedi come aggiungere funzioni AI alla tua app.
La Messages API in breve
Secondo il riferimento API di Anthropic, una richiesta è una POST a https://api.anthropic.com/v1/messages con:
| Parte | Cosa è |
|---|---|
intestazione x-api-key | La tua chiave API |
intestazione anthropic-version | La versione dell'API, per esempio 2023-06-01 |
model (obbligatorio) | Quale modello Claude usare |
max_tokens (obbligatorio) | Il massimo di token che la risposta può contenere; il modello può fermarsi prima |
messages (obbligatorio) | La conversazione: turni user e assistant alternati |
system (facoltativo) | Istruzioni che valgono per tutta la conversazione |
stream (facoltativo) | Impostalo a true per ricevere la risposta mentre viene scritta, tramite server-sent events |
L'API è senza stato: per continuare una conversazione, invia di nuovo i turni precedenti a ogni richiesta. Per questo le chat lunghe costano di più a messaggio.
Anthropic pubblica SDK ufficiali per Python, TypeScript, C#, Go, Java, PHP e Ruby. Impostano le intestazioni, analizzano le risposte e supportano lo streaming. Usane uno invece di HTTP diretto, a meno che tu non abbia un motivo per non farlo.
Scegliere un modello
Anthropic offre diversi modelli Claude che bilanciano capacità, velocità e prezzo, e la gamma cambia nel tempo. Scegli il modello più piccolo che svolge bene il tuo compito, testalo su esempi reali e mantieni l'ID del modello nella configurazione, così puoi cambiarlo senza modificare il codice. Consulta le pagine di Anthropic su modelli e prezzi per le opzioni e le tariffe attuali.
Configurare il tuo account
- Accedi alla Claude Console su platform.claude.com e aggiungi un metodo di pagamento.
- Crea una chiave API. Usa una chiave per ogni ambiente (test e produzione), così puoi revocarne una senza interrompere l'altra.
- Imposta un limite di spesa. La pagina degli errori di Anthropic precisa che, quando l'utilizzo raggiunge un limite di spesa che hai impostato, l'API restituisce un errore 400; la tua app dovrebbe mostrare un messaggio chiaro in quel caso.
- Verifica i limiti di frequenza del tuo account nella Console; sono misurati per organizzazione.
Il flusso della richiesta
- L'utente agisce nella tua app: invia un messaggio, clicca su "Riassumi".
- Il browser chiama la tua route del server, mai direttamente Anthropic.
- Il tuo server verifica che l'utente abbia effettuato l'accesso e possa usare la funzione, e applica un limite per utente.
- Costruisce la richiesta: un system prompt con le tue regole, l'input dell'utente e i dati che il compito richiede dal tuo database.
- Chiama la Messages API con la chiave presa dall'ambiente e un
max_tokenssensato. - Trasmette la risposta al browser e registra l'uso dei token dalla risposta.
Opzioni e compromessi
| Decisione | Scelta semplice | Quando andare oltre |
|---|---|---|
| Streaming | Attendi la risposta completa | Usa lo streaming per la chat e per tutto ciò che è lungo; Anthropic consiglia streaming o batch per le richieste di lunga durata |
| Formato di output | Testo semplice | Output JSON strutturato quando il tuo codice deve leggere dei campi |
| I tuoi dati | Includi il record pertinente | Retrieval sui tuoi contenuti quando sono troppi (cos'è RAG) |
| Azioni | Il modello scrive solo testo | Tool use, in cui il modello chiede al tuo codice di eseguire una funzione che hai definito |
| Lavoro in blocco, non urgente | Ciclo sugli elementi | La Message Batches API, che invii e di cui interroghi i risultati |
Prompt da dare al tuo builder AI
Una prima funzione:
Aggiungi un pannello "Chiedi informazioni su questo documento". Chiama una route del server POST /api/ask che verifica che l'utente sia loggato e sia proprietario del documento, poi chiama la Messages API di Claude con l'SDK ufficiale di Anthropic e il segreto ANTHROPIC_API_KEY. Leggi l'ID del modello dal segreto CLAUDE_MODEL. System prompt: "Rispondi solo in base al documento fornito. Se la risposta non c'è, dillo." Invia il testo del documento e la domanda, imposta max_tokens a 800, trasmetti la risposta alla pagina e non esporre mai la chiave al browser.
Limiti ed errori:
Limita ogni utente a 20 domande l'ora, registrate nel database. Registra i token di input e di output di ogni risposta con l'ID utente e l'ID della richiesta. Con gli errori 429 o 529, riprova con backoff esponenziale fino a 3 volte, rispettando l'intestazione retry-after, poi mostra "L'assistente è occupato, riprova tra poco." Se l'API segnala un errore di limite di spesa, mostra "Le funzioni AI sono in pausa" e avvisa l'amministratore.
Errori da prevedere
Dalla documentazione degli errori di Anthropic, quelli che la tua app incontrerà davvero:
| Codice | Tipo | Cosa fare |
|---|---|---|
| 400 | invalid_request_error | Correggi la richiesta; viene restituito anche quando raggiungi un limite di spesa che hai impostato |
| 401 | authentication_error | Verifica che la chiave sia presente, corretta e non revocata |
| 413 | request_too_large | Invia meno dati; la Messages API accetta fino a 32 MB per richiesta |
| 429 | rate_limit_error | Rallenta e riprova, rispettando retry-after |
| 500 | api_error | Riprova con backoff; contatta il supporto con l'ID della richiesta se persiste |
| 529 | overloaded_error | Traffico temporaneamente alto da parte di tutti gli utenti; rallenta e riprova |
La documentazione di Anthropic afferma che gli SDK ufficiali ritentano automaticamente gli errori transitori (errori di connessione, limiti di frequenza e errori 5xx) due volte per impostazione predefinita, con backoff esponenziale, e che questo è configurabile. Ogni risposta contiene un'intestazione request-id; registrala così il supporto può ricostruire i problemi.
Errori comuni
- Chiamare l'API dal browser. La tua chiave diventa pubblica. Passa sempre dal tuo server. Vedi come proteggere le chiavi API.
- Dimenticare che
max_tokensè un limite massimo, non un obiettivo. Impostalo in base a ciò che serve alla funzione; troppo basso tronca le risposte, troppo alto rischia risposte lunghe e costose. - Mettere le regole nel messaggio dell'utente. Le istruzioni stabili vanno nel prompt
system; i permessi vanno nel tuo codice. - Inviare per sempre tutta la chat. Riduci o riassumi i turni vecchi man mano che le conversazioni crescono.
- Nessun limite di spesa né tetto per utente.
- Scrivere fisso l'ID del modello. I modelli vengono aggiornati e ritirati.
- Ignorare il motivo di stop. Se la risposta si è fermata perché ha raggiunto
max_tokens, avvisa l'utente o alza il limite.
Checklist
- Chiave API creata nella Claude Console e salvata come segreto lato server
- Chiavi separate per test e produzione
- Limite di spesa impostato; messaggio chiaro quando viene raggiunto
- Tutte le richieste passano dal tuo server con controlli dei permessi
- Il system prompt contiene le regole; l'ID del modello è configurabile
-
max_tokensimpostato per funzione; risposte lunghe in streaming - Limite di frequenza per utente nella tua app
- Errori 429 e 529 gestiti con backoff; ID delle richieste registrati
- Stato di errore chiaro che non interrompe la pagina
- Testato con input vuoti, molto lunghi e ostili
Usare l'API di Claude in Mythex
Nelle app che costruisci su Mythex, le funzioni Claude usano la tua chiave Anthropic e vengono addebitate sul tuo account Anthropic, non sui crediti di build di Mythex. È separato dall'agente Mythex che scrive il tuo codice. Aggiungi ANTHROPIC_API_KEY come segreto del progetto tramite /secrets, le impostazioni del progetto o la scheda dei segreti in chat, poi descrivi la funzione con prompt simili a quelli sopra. Pubblica di nuovo dopo aver cambiato i segreti su un'app online. Per un prompt di partenza, vedi Aggiungere funzioni AI con le tue chiavi API. Se stai scegliendo tra fornitori, come integrare l'API di OpenAI copre gli stessi punti per OpenAI.
Domande
Come ottengo una chiave API di Claude?
Accedi alla Claude Console su platform.claude.com, configura la fatturazione e crea una chiave API. Conservala come segreto lato server, di norma con il nome ANTHROPIC_API_KEY, e non inserirla mai nel codice del browser.
Cosa serve per fare una richiesta all'API di Claude?
A settembre 2026, il riferimento della Messages API di Anthropic indica tre campi obbligatori nel corpo della richiesta: model, max_tokens e messages. Le chiamate HTTP dirette richiedono anche le intestazioni x-api-key e anthropic-version; gli SDK ufficiali le impostano per te.
Cos'è un errore 529 dell'API di Claude?
La pagina degli errori di Anthropic descrive il 529 come overloaded_error: l'API è temporaneamente sovraccarica per l'alto traffico di tutti gli utenti. Riprova con backoff esponenziale. Gli SDK ufficiali ritentano automaticamente alcuni errori transitori.
Posso usare Claude con codice scritto per l'SDK di OpenAI?
Anthropic documenta un livello di compatibilità con l'SDK di OpenAI per usare Claude attraverso l'interfaccia dell'SDK OpenAI. Per il codice nuovo, i suoi SDK nativi danno accesso alle funzionalità specifiche di Claude, quindi sono di solito il punto di partenza migliore.