API dei File
L’API dei File ti consente di caricare e gestire file da utilizzare con l’API di Anthropic senza dover ricaricare i contenuti 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 dei File per evitare di dover continuamente ricaricare documenti e immagini utilizzati frequentemente in più chiamate API.
L’API dei File è attualmente in versione beta. Ti preghiamo di contattarci tramite il nostro modulo di feedback per condividere la tua esperienza con l’API dei File.
Modelli supportati
Il riferimento a un file_id
in una richiesta Messages è supportato in tutti i modelli che supportano il tipo di file specifico. 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 e in tutti i modelli Claude 3.7+.
L’API dei File attualmente non è supportata su Amazon Bedrock o Google Vertex AI.
Come funziona l’API dei File
L’API dei File fornisce un approccio semplice di creazione unica e utilizzo multiplo per lavorare con i file:
- Carica file nel nostro storage sicuro e ricevi un
file_id
univoco - Scarica file che sono stati creati dallo strumento di esecuzione del codice
- Fai riferimento ai 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 dei File
Per utilizzare l’API dei File, dovrai includere l’intestazione della funzionalità beta: anthropic-beta: files-api-2025-04-14
.
Caricamento di un file
Carica un file da utilizzare in future chiamate API:
Tipi di file e blocchi di contenuto
L’API dei File supporta diversi tipi di file che corrispondono a diversi tipi di blocchi di contenuto:
Tipo di File | MIME Type | 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 | Vari | container_upload | Analisi dei dati, creazione di visualizzazioni |
Blocchi di documento
Per PDF e file di testo, utilizza il blocco di contenuto document
:
Blocchi di immagine
Per le immagini, utilizza il blocco di contenuto image
:
Gestione dei file
Elenco dei file
Recupera un elenco dei tuoi file caricati:
Ottenere i metadati del file
Recupera informazioni su un file specifico:
Eliminare un file
Rimuovi un file dal tuo workspace:
Download di un file
Scarica i file che sono stati creati dallo strumento di esecuzione del codice:
Puoi scaricare solo i file che sono stati creati dallo strumento di esecuzione del codice. I file che hai caricato non possono essere scaricati.
Archiviazione dei file e limiti
Limiti di archiviazione
- Dimensione massima del file: 32 MB per file
- Archiviazione totale: 100 GB per organizzazione
Ciclo di vita del file
- I file sono limitati al workspace della chiave API. Altre chiavi API possono utilizzare i file creati da qualsiasi altra chiave API associata allo stesso workspace
- I file persistono fino a quando 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 dei File 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 di documento)
- 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
- Nome file non valido (400): Il nome del file non soddisfa i requisiti di lunghezza (1-255 caratteri) o contiene caratteri vietati (
<
,>
,:
,"
,|
,?
,*
,\
,/
, o caratteri unicode 0-31)
Utilizzo e fatturazione
Le operazioni dell’API dei 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 addebitato come token di input. Puoi scaricare solo i file creati dallo strumento di esecuzione del codice.
Limiti di frequenza
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ù elevati per il tuo caso d’uso