Source: https://aiprimetech.io/it/learn/anthropic-python-sdk/ [Home](/it/) / [Impara](/it/learn/) / SDK Python di Anthropic: installare, impostare base_url, usare lo streaming e gestire gli errori # SDK Python di Anthropic: installazione, configurazione di base_url, streaming e gestione degli errori La anthropic è il pacchetto client Python ufficiale di Anthropic per l'API di Claude. Gestisce autenticazione, tentativi successivi, streaming ed errori tipizzati e funziona senza modifiche con qualsiasi endpoint compatibile con Anthropic: imposta base_url (oppure ANTHROPIC_BASE_URL) e il resto del codice rimane invariato. ## Installazione terminaleCopia ``` pip install anthropic ``` Le versioni 1.x funzionano su httpx2 e richiedono Python 3.10 o successivo. Se passi un tuo client HTTP, usa DefaultHttpxClient dell'SDK per mantenere i timeout e i limiti di connessione predefiniti. ## Creare un client app.pyCopia ``` import anthropic client = anthropic.Anthropic( api_key="your_key", # default: ANTHROPIC_API_KEY base_url="https://aiprimetech.io", # default: ANTHROPIC_BASE_URL, else https://api.anthropic.com ) ``` base_url è l'URL radice dell'host. L'SDK aggiunge /v1/messages automaticamente, quindi https://aiprimetech.io/v1 produrrebbe /v1/v1/messages e un 404 page not found. Con entrambe le variabili impostate nell'ambiente, anthropic.Anthropic() non richiede alcun argomento: terminaleCopia ``` export ANTHROPIC_API_KEY=your_key export ANTHROPIC_BASE_URL=https://aiprimetech.io ``` ## Inviare un messaggio app.pyCopia ``` message = client.messages.create( model="claude-sonnet-5", max_tokens=1024, messages=[{"role": "user", "content": "Summarise TCP slow start in two sentences."}], ) for block in message.content: if block.type == "text": print(block.text) print(message.usage.input_tokens, message.usage.output_tokens) print(message._request_id) # log this with any failure report ``` content è un elenco di blocchi (testo, ragionamento, uso di strumenti), quindi controlla block.type invece di leggere content[0].text alla cieca. ## Ricevere risposte in streaming stream.pyCopia ``` with client.messages.stream( model="claude-sonnet-5", max_tokens=16000, messages=[{"role": "user", "content": "Write a short story about a lighthouse."}], ) as stream: for text in stream.text_stream: print(text, end="", flush=True) final = stream.get_final_message() ``` Usa lo streaming per qualsiasi richiesta con input lungo, output lungo o un valore elevato di max_tokens: una singola richiesta senza streaming deve terminare entro il timeout; una richiesta in streaming no. messages.create(..., stream=True) fornisce l'iteratore degli eventi grezzi se non hai bisogno della funzione di supporto. ## Client asincrono async_app.pyCopia ``` import asyncio, anthropic client = anthropic.AsyncAnthropic(base_url="https://aiprimetech.io") limit = asyncio.Semaphore(3) # stay within your key's concurrency async def ask(question: str) -> str: async with limit: msg = await client.messages.create( model="claude-haiku-4-5", max_tokens=512, messages=[{"role": "user", "content": question}], ) return next(b.text for b in msg.content if b.type == "text") async def main(): answers = await asyncio.gather(*(ask(q) for q in ["What is DNS?", "What is BGP?"])) print(answers) asyncio.run(main()) ``` Il semaforo è importante. Inviare centinaia di richieste contemporaneamente con asyncio.gather è la causa più comune degli errori Concurrency limit exceeded che riscontriamo nei client Python. ## Timeout e nuovi tentativi Valori predefiniti: un timeout di 10 minuti per richiesta e 2 tentativi automatici con backoff esponenziale. L'SDK ritenta in caso di errori di connessione e risposte 408, 409, 429 e 5xx. Poiché ritenta anche in caso di timeout, il tempo totale nel caso peggiore è pari al timeout moltiplicato per il numero di tentativi. app.pyCopia ``` client = anthropic.Anthropic(base_url="https://aiprimetech.io", timeout=60.0, max_retries=4) # override for one call only client.with_options(timeout=300.0).messages.create( model="claude-opus-5-5", max_tokens=4000, messages=[{"role": "user", "content": "Review this design doc..."}], ) ``` ## Gestione degli errori | Stato | Eccezione | Riprovare? | 400 | anthropic.BadRequestError | No: correggi la richiesta | 401 | anthropic.AuthenticationError | No: chiave errata o mancante | 403 | anthropic.PermissionDeniedError | No | 404 | anthropic.NotFoundError | No: ID del modello o URL | 429 | anthropic.RateLimitError | Sì, dopo una pausa | 5xx, incluso 529 per sovraccarico | anthropic.InternalServerError | Sì | Errore di rete | anthropic.APIConnectionError | Sì | Timeout | anthropic.APITimeoutError | Sì, oppure usa lo streaming errors.pyCopia ``` try: message = client.messages.create(model="claude-sonnet-5", max_tokens=1024, messages=[{"role": "user", "content": "Hi"}]) except anthropic.NotFoundError as e: print("Bad model ID or URL:", e.message) except anthropic.RateLimitError as e: print("Rate limited, retry after", e.response.headers.get("retry-after")) except anthropic.APIStatusError as e: print(e.status_code, e.type, e.message) except anthropic.APIConnectionError: print("Network problem") ``` Intercetta prima le classi specifiche e APIStatusError per ultima; una singola except generica nasconde la differenza tra gli errori per cui vale la pena ritentare e quelli che richiedono una modifica al codice. e.type fornisce la stringa del tipo di errore dell'API, ad esempio rate_limit_error o overloaded_error. ## ID dei modelli | ID del modello | Usalo per | claude-sonnet-5 | Scelta predefinita per programmazione e attività degli agenti: veloce, potente, di fascia media. | claude-opus-5-5 | Ragionamenti più complessi, refactoring estesi, esecuzioni prolungate degli agenti. | claude-fable-5-1 | Il più capace e il più costoso; riservalo alle attività più difficili. | claude-haiku-4-5 | Economico e rapido: titoli, riepiloghi, classificazione, piccoli passaggi. client.models.list() restituisce i modelli disponibili su un endpoint, così puoi verificare un ID prima di usarlo. Usa gli ID esattamente come sono scritti, senza suffissi di data. ## Risoluzione dei problemi su un gateway | Che cosa vedi | Causa | Soluzione | NotFoundError con 404 page not found | /v1 in base_url | Usa l'URL radice dell'host | AuthenticationError | Chiave non impostata nel processo o incollata con spazi | Stampa len(os.environ["ANTHROPIC_API_KEY"]) | RateLimitError: Concurrency limit exceeded for user | Troppe richieste in corso | Un asyncio.Semaphore come sopra | APITimeoutError nelle attività lunghe | Richiesta senza streaming che supera il timeout | Usa lo streaming o aumenta timeout | InternalServerError: No available accounts | Capacità temporaneamente limitata del servizio a monte | Lascia che l'SDK ritenti; aumenta max_retries | Insufficient account balance | Saldo esaurito | [Ricarica](/it/topup/) Per approfondire gli errori lato modello, consulta la [guida agli errori dell'API di Claude](/it/learn/claude-api-errors-troubleshooting/). ## Domande frequenti Come si installa l'SDK Python di Anthropic? pip install anthropic. La versione 1.x richiede Python 3.10 o successivo. Come si imposta un URL di base personalizzato nell'SDK Python di Anthropic? Passa base_url ad anthropic.Anthropic() oppure imposta ANTHROPIC_BASE_URL. Usa l'URL radice dell'host; l'SDK aggiunge /v1/messages. Quali sono il timeout e il numero di tentativi predefiniti? 10 minuti per richiesta e 2 tentativi con backoff esponenziale, per errori di connessione e risposte 408, 409, 429 e 5xx. Come si usa lo streaming con l'SDK Python? Usa with client.messages.stream(...) as stream: e itera su stream.text_stream; stream.get_final_message() restituisce il messaggio completo. Inizia a usare Claude in pochi minuti Ottieni una chiave API: non servono un account Anthropic né una lista d'attesa.[Ottieni la tua chiave API](/register) 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. ## Altre guide all'API di Claude [Come ottenere una chiave API di Claude](/it/learn/how-to-get-a-claude-api-key/)[I prezzi dell'API Claude, spiegati](/it/learn/claude-api-pricing-explained/)[Il modo più economico per usare l'API Claude](/it/learn/cheapest-way-to-use-claude-api/)[Cursor illimitato con l'API Claude](/learn/use-claude-api-with-cursor/)[Accesso illimitato a Claude Code](/it/learn/use-claude-api-with-claude-code/)[Gateway API Claude e accesso diretto ad Anthropic a confronto](/it/learn/claude-api-vs-anthropic-direct/)[Usare Claude tramite un'API compatibile con OpenAI](/it/learn/openai-compatible-claude-api/)[I modelli Claude spiegati: un confronto tra Claude Opus, Sonnet, Haiku e Fable — tutti i modelli API Claude, i nomi dei modelli Anthropic e i prezzi (2026)](/it/learn/claude-api-models-compared/)[Pagare l'API Claude con criptovalute](/it/learn/claude-api-with-crypto-payment/)[Accesso all'API Claude senza lista d'attesa](/it/learn/claude-api-without-waitlist/)[Come ridurre l'utilizzo dei token di Claude](/it/learn/how-to-reduce-claude-token-usage/)[Cline illimitato con l'API Claude](/it/learn/use-claude-api-with-cline/)[Roo Code illimitato con l'API Claude](/it/learn/use-claude-api-with-roo-code/)[Claude illimitato negli IDE JetBrains](/it/learn/use-claude-api-with-jetbrains/)[Aider senza limiti con l'API di Claude](/it/learn/use-claude-api-with-aider/)[Claude illimitato in VS Code](/it/learn/use-claude-api-with-vscode/)[Configurazione di OpenCode per Claude: impostazione di opencode.json, modelli ed errori comuni](/it/learn/use-claude-api-with-opencode/)[Eseguire un agente Hermes senza limiti su Claude](/it/learn/run-hermes-agent-with-claude-api/)[Eseguire OpenClaw senza limiti con Claude](/it/learn/run-openclaw-with-claude-api/)[Cosa significa un'API compatibile con Anthropic](/it/learn/anthropic-compatible-api/)[Chiave API di Claude Code — ANTHROPIC_API_KEY: come ottenerla, configurarla e quando usare invece claude setup-token](/it/learn/claude-code-api-key-setup/)[Costi dell'API di Claude Code — Prezzi e come ridurli](/it/learn/claude-code-api-costs/)[Gli errori dell'API Claude spiegati: errore del server 500, sovraccarico 529, limite di frequenza 429, richiesta non valida 400 — e la soluzione per ciascuno](/it/learn/claude-api-errors-troubleshooting/)[Come acquistare crediti per l'API di Claude e perché un credito Claude conviene più di qualsiasi offerta per «acquistare un account Claude»](/it/learn/buy-claude-api-credits/)[API Claude gratuita: esiste una chiave API di Claude gratuita e che cosa è davvero gratuito nel 2026?](/it/learn/claude-api-free-trial/)[API Claude e abbonamento Claude Pro/Max a confronto — Quale scegliere](/it/learn/claude-api-vs-subscription/)[Eseguire la CLI di Codex su Claude](/it/learn/use-claude-api-with-codex/)[Collegare Claude a n8n](/it/learn/use-claude-api-with-n8n/)[Instradare LiteLLM verso Claude](/it/learn/use-claude-api-with-litellm/)[Usare Claude in Kilo Code](/it/learn/use-claude-api-with-kilo-code/)[Integrare Claude in GitHub Copilot](/it/learn/use-claude-api-with-github-copilot/)[Collega Zed a Claude tramite il gateway](/it/learn/use-claude-api-with-zed/)[Collega Cherry Studio a Claude](/it/learn/use-claude-api-with-cherry-studio/)[ChatAnthropic in LangChain: importazione, base_url, streaming, strumenti ed errori](/it/learn/use-claude-api-with-langchain/)[Claude con Vercel AI SDK: baseURL di createAnthropic, streaming e soluzioni ai problemi](/it/learn/use-claude-api-with-vercel-ai-sdk/)[Esegui Factory Droid con Claude](/it/learn/use-claude-api-with-factory-droid/)[L'API di Claude Code spiegata](/it/learn/claude-code-api/)[Integrare l'API di Claude nella tua applicazione](/it/learn/claude-api-integration/)[Come ottenere un utilizzo illimitato di Claude e perché non esiste un «Claude Code craccato»](/it/learn/get-unlimited-claude-usage/)