Riferimento APIUtilizzo dell'API

Panoramica dell'API

Copy page



Comprendi gli endpoint disponibili dell'API di Claude, gli header di autenticazione, gli SDK client, la paginazione, i limiti di velocità e le opzioni di accesso alle piattaforme cloud.

L'API di Claude è un'API RESTful disponibile all'indirizzo https://api.anthropic.com che fornisce accesso programmatico ai modelli Claude e ai Claude Managed Agents.

Prerequisiti

Per utilizzare l'API di Claude, avrai bisogno di:

• Un account Claude Console
• Una chiave API, o una regola Workload Identity Federation configurata

Per istruzioni di configurazione passo passo, consulta Inizia.

API disponibili

L'API di Claude include le seguenti API:

• Messages API: Invia messaggi a Claude per interazioni conversazionali (POST /v1/messages)
• Message Batches API: Elabora grandi volumi di richieste Messages in modo asincrono con una riduzione dei costi del 50% (POST /v1/messages/batches)
• Token Counting API: Conta i token in un messaggio prima dell'invio per gestire costi e limiti di velocità (POST /v1/messages/count_tokens)
• Models API: Elenca i modelli Claude disponibili e i loro dettagli (GET /v1/models)
• Files API: Carica e gestisci file da utilizzare in più chiamate API (POST /v1/files, GET /v1/files)
• Skills API: Crea e gestisci skill personalizzate per agenti (POST /v1/skills, GET /v1/skills)

Le seguenti API sono in beta:

• Agents API: Definisci configurazioni di agenti riutilizzabili e versionate per i Claude Managed Agents (POST /v1/agents, GET /v1/agents)
• Sessions API: Esegui sessioni di agenti con stato in sandbox cloud gestite (POST /v1/sessions, GET /v1/sessions/{id}/events/stream)
• Environments API: Configura template di sandbox per le sessioni di agenti (POST /v1/environments, GET /v1/environments)

Per il riferimento API completo con tutti gli endpoint, i parametri e gli schemi di risposta, esplora le pagine di riferimento API elencate nella navigazione. Per accedere alle funzionalità beta, consulta Beta headers.

Autenticazione

Per i dettagli su ciascun metodo di autenticazione e su quando utilizzarlo, consulta Autenticazione. Le richieste all'API di Claude includono questi header:

Se stai utilizzando gli SDK client, l'SDK invia automaticamente gli header di autenticazione, versione e content-type; passi tu stesso anthropic-workspace-id quando la tua chiave lo richiede. Per i dettagli sul versioning dell'API, consulta Versioni dell'API.

Quando accedi a Claude tramite una piattaforma cloud, l'autenticazione è integrata con il sistema IAM del provider cloud. Consulta la documentazione specifica della piattaforma per i tipi di credenziali supportati, gli header richiesti e le opzioni di autenticazione.

Ottenere le chiavi API

L'API è resa disponibile tramite la Console web. Puoi utilizzare il playground per provare l'API nel browser e poi generare chiavi API nelle Impostazioni account (consulta Ottieni la tua chiave API di Claude). Scegli il tipo di ciascuna chiave (consulta Tipi di chiave) e la sua scadenza quando la crei. Usa i workspace per separare gli ambienti e controllare la spesa per caso d'uso.

SDK client

Anthropic fornisce SDK ufficiali che semplificano l'integrazione dell'API gestendo l'autenticazione, la formattazione delle richieste, la gestione degli errori e altro ancora.

Vantaggi:

• Gestione automatica degli header (autenticazione, anthropic-version, content-type)
• Gestione type-safe di richieste e risposte
• Logica di retry e gestione degli errori integrate
• Supporto per lo streaming
• Timeout delle richieste e gestione delle connessioni

Per un elenco degli SDK client, consulta SDK client.

API di Claude vs piattaforme cloud

Claude è disponibile tramite l'API diretta di Claude e tramite piattaforme cloud. Scegli in base alla tua infrastruttura, alla disponibilità delle funzionalità, ai requisiti di conformità e alle preferenze di prezzo.

API di Claude

• Accesso diretto ai modelli e alle funzionalità più recenti
• Fatturazione e supporto Anthropic
• Ideale per: Nuove integrazioni, accesso completo alle funzionalità, relazione diretta con Anthropic

API delle piattaforme cloud

Accedi a Claude tramite AWS, Google Cloud o Microsoft Azure:

• Integrato con la fatturazione e l'IAM del provider cloud
• La disponibilità delle funzionalità varia in base alla piattaforma: Le piattaforme gestite da Anthropic includono Claude Platform on AWS e Microsoft Foundry; le piattaforme gestite da partner includono Amazon Bedrock e Google Cloud. Consulta la pagina di ciascuna piattaforma per la disponibilità e i tempi delle funzionalità.
• Ideale per: Impegni cloud esistenti, requisiti di conformità specifici, fatturazione cloud consolidata

Formato di richiesta e risposta

Limiti di dimensione delle richieste

Se superi questi limiti, riceverai un errore 413 request_too_large.

Header di risposta

L'API di Claude include i seguenti header nelle sue risposte:

Per gli header dei limiti di velocità, consulta Header di risposta in Limiti di velocità. Per esempi che leggono un header di risposta per nome con ciascun SDK, consulta Identifica il workspace dietro una risposta API.

Paginazione

Gli endpoint di elenco restituiscono i risultati in pagine. La maggior parte degli endpoint di elenco più recenti utilizza lo schema di cursore page e next_page descritto in questa sezione. Alcuni utilizzano uno schema diverso; consulta la nota alla fine di questa sezione. Usa il parametro di query limit per controllare la dimensione della pagina e il parametro di query page per recuperare una pagina adiacente. Ogni risposta include un array data insieme ai campi del cursore per navigare tra le pagine.

Per tornare indietro di una pagina, passa prev_page come parametro page. prev_page è null quando sei sulla prima pagina. Non tutti gli endpoint di elenco supportano prev_page. Solo GET /v1/sessions restituisce prev_page; sugli endpoint di elenco che non supportano la paginazione all'indietro, il campo è assente dalla risposta anziché null. Per una guida dettagliata alle richieste, consulta Elencare le sessioni.

Ogni SDK fornisce un iteratore con paginazione automatica che segue next_page per te. In Python e TypeScript, lo ottieni iterando direttamente il risultato dell'elenco. Gli altri SDK forniscono l'iteratore tramite un metodo separato. La paginazione automatica degli SDK è solo in avanti; per tornare indietro di una pagina, leggi prev_page dalla risposta e passalo nuovamente come parametro page tu stesso. Consulta SDK client per i dettagli specifici del linguaggio.

Limiti di velocità e disponibilità

Limiti di velocità

L'API applica limiti di velocità e limiti di spesa per prevenire abusi e gestire la capacità. I limiti sono organizzati in livelli di utilizzo; la tua organizzazione viene assegnata automaticamente a un livello e può passare a un livello superiore nel tempo. Ogni livello ha:

• Limiti di spesa: Costo mensile massimo per l'utilizzo dell'API
• Limiti di velocità: Numero massimo di richieste al minuto (RPM) e token al minuto (TPM)

Puoi visualizzare i tuoi limiti di velocità nella pagina Limiti di velocità e i tuoi limiti di spesa nella pagina Fatturazione nella Console. Per limiti di velocità più elevati o un tetto di spesa mensile più alto, usa Richiedi aumento del limite di velocità nella pagina Limiti di velocità.

Per informazioni dettagliate su limiti, livelli e l'algoritmo token bucket utilizzato per la limitazione della velocità, consulta Limiti di velocità.

Disponibilità

L'API di Claude è disponibile in molti paesi e regioni in tutto il mondo. Controlla la pagina delle regioni supportate per confermare la disponibilità nella tua posizione.

Prossimi passi