API Files
L’API Files ti consente di caricare e gestire file da utilizzare con l’API Anthropic senza dover ricaricare il contenuto ad ogni richiesta. Questo è particolarmente utile quando si utilizza lo strumento di esecuzione del codice per fornire input (ad esempio dataset e documenti) e poi scaricare output (ad esempio grafici). Puoi anche utilizzare l’API Files per evitare di dover continuamente ricaricare documenti e immagini utilizzati frequentemente attraverso più chiamate API.
L’API Files è attualmente in beta. Ti preghiamo di contattarci attraverso il nostro modulo di feedback per condividere la tua esperienza con l’API Files.
Modelli supportati
Il riferimento a un file_id
in una richiesta Messages è supportato in tutti i modelli che supportano il tipo di file specificato. Ad esempio, le immagini sono supportate in tutti i modelli Claude 3+, i PDF in tutti i modelli Claude 3.5+, e vari altri tipi di file per lo strumento di esecuzione del codice in Claude 3.5 Haiku più tutti i modelli Claude 3.7+.
L’API Files attualmente non è supportata su Amazon Bedrock o Google Vertex AI.
Come funziona l’API Files
L’API Files fornisce un approccio semplice crea-una-volta, usa-molte-volte per lavorare con i file:
- Carica file nel nostro storage sicuro e ricevi un
file_id
unico - Scarica file che vengono creati dallo strumento di esecuzione del codice
- Riferisci file nelle richieste Messages utilizzando il
file_id
invece di ricaricare il contenuto - Gestisci i tuoi file con operazioni di elenco, recupero ed eliminazione
Come utilizzare l’API Files
Per utilizzare l’API Files, dovrai includere l’header della funzionalità beta: anthropic-beta: files-api-2025-04-14
.
Caricamento di un file
Carica un file da riferire in future chiamate API:
Utilizzo di un file nei messaggi
Una volta caricato, riferisci il file utilizzando il suo file_id
:
Tipi di file e blocchi di contenuto
L’API Files supporta diversi tipi di file che corrispondono a diversi tipi di blocchi di contenuto:
Tipo di File | Tipo MIME | Tipo di Blocco di Contenuto | Caso d’Uso |
---|---|---|---|
application/pdf | document | Analisi del testo, elaborazione di documenti | |
Testo semplice | text/plain | document | Analisi del testo, elaborazione |
Immagini | image/jpeg , image/png , image/gif , image/webp | image | Analisi di immagini, compiti visivi |
Dataset, altri | Varia | container_upload | Analizzare dati, creare visualizzazioni |
Lavorare con altri formati di file
Per i tipi di file che non sono supportati come blocchi document
(.csv, .txt, .md, .docx, .xlsx), converti i file in testo semplice e includi il contenuto direttamente nel tuo messaggio:
Per i file .docx contenenti immagini, convertili prima in formato PDF, poi utilizza il supporto PDF per sfruttare l’analisi delle immagini integrata. Questo consente di utilizzare citazioni dal documento PDF.
Blocchi documento
Per PDF e file di testo, utilizza il blocco di contenuto document
:
Blocchi immagine
Per le immagini, utilizza il blocco di contenuto image
:
Gestione dei file
Elencare i file
Recupera un elenco dei tuoi file caricati:
Ottenere metadati del file
Recupera informazioni su un file specifico:
Eliminare un file
Rimuovi un file dal tuo workspace:
Scaricare un file
Scarica file che sono stati creati dallo strumento di esecuzione del codice:
Puoi scaricare solo file che sono stati creati dallo strumento di esecuzione del codice. I file che hai caricato non possono essere scaricati.
Archiviazione e limiti dei file
Limiti di archiviazione
- Dimensione massima del file: 500 MB per file
- Archiviazione totale: 100 GB per organizzazione
Ciclo di vita dei file
- I file sono limitati al workspace della chiave API. Altre chiavi API possono utilizzare file creati da qualsiasi altra chiave API associata allo stesso workspace
- I file persistono finché non li elimini
- I file eliminati non possono essere recuperati
- I file sono inaccessibili tramite l’API poco dopo l’eliminazione, ma potrebbero persistere nelle chiamate API
Messages
attive e negli usi degli strumenti associati
Gestione degli errori
Gli errori comuni quando si utilizza l’API Files includono:
- File non trovato (404): Il
file_id
specificato non esiste o non hai accesso ad esso - Tipo di file non valido (400): Il tipo di file non corrisponde al tipo di blocco di contenuto (ad esempio, utilizzare un file immagine in un blocco documento)
- Supera la dimensione della finestra di contesto (400): Il file è più grande della dimensione della finestra di contesto (ad esempio utilizzare un file di testo semplice da 500 MB in una richiesta
/v1/messages
) - Nome file non valido (400): Il nome del file non soddisfa i requisiti di lunghezza (1-255 caratteri) o contiene caratteri proibiti (
<
,>
,:
,"
,|
,?
,*
,\
,/
, o caratteri unicode 0-31) - File troppo grande (413): Il file supera il limite di 500 MB
- Limite di archiviazione superato (403): La tua organizzazione ha raggiunto il limite di archiviazione di 100 GB
Utilizzo e fatturazione
Le operazioni dell’API File sono gratuite:
- Caricamento di file
- Download di file
- Elenco dei file
- Ottenimento dei metadati dei file
- Eliminazione di file
Il contenuto dei file utilizzato nelle richieste Messages
viene prezzato come token di input. Puoi scaricare solo file creati dallo strumento di esecuzione del codice.
Limiti di velocità
Durante il periodo beta:
- Le chiamate API relative ai file sono limitate a circa 100 richieste al minuto
- Contattaci se hai bisogno di limiti più alti per il tuo caso d’uso