Files API
Carica i file una sola volta, fai riferimento a essi tramite file_id nelle richieste Messages e scarica gli output creati dalle skill o dallo strumento di esecuzione del codice.
L’utilizzo varia in base al prodotto
file_id in un blocco document, image o container_upload.file_id in un evento user.message.La Files API ti consente di caricare e gestire file da usare con la Claude API senza dover ricaricare il contenuto a ogni richiesta. Questo è particolarmente utile quando usi lo strumento di esecuzione del codice per fornire input (ad esempio, dataset e documenti) e poi scaricare gli output (ad esempio, grafici). Puoi esplorare direttamente il riferimento APIAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro), oltre a questa guida.
Supporto dei tipi di file
Il riferimento a un file_id in una richiesta Messages è supportato su tutti i modelli che supportano il tipo di file in questione. Le immagini sono supportate su tutti gli attuali modelli Claude. Per i PDF e gli altri tipi di file con lo strumento di esecuzione del codice, consulta le pagine collegate per il supporto dei modelli.
Come funziona la Files API
La Files API offre un approccio “crea una volta, usa molte volte” per lavorare con i file:
- Carica file nello storage sicuro di Anthropic e ricevi un
file_idunivoco - Scarica file creati dalle skill o dallo strumento di esecuzione del codice
- Fai riferimento ai file nelle richieste MessagesAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro) usando il
file_idinvece di ricaricare il contenuto - Gestisci i tuoi file con operazioni di elenco, recupero ed eliminazione
I file non sono limitati a un utente finale, a una conversazione o a una sessione. Qualsiasi chiave API con accesso a un workspace può accedere a qualsiasi file caricato in quel workspace. Ogni account di servizio, e ogni utente il cui ruolo nell’organizzazione consente l’accesso all’API, può usare il workspace predefinito oltre a qualsiasi workspace a cui lo aggiungi, quindi tieni i file che devono restare separati nel proprio workspace e accedi a essi solo con chiavi limitate a quel workspace. Non accettare mai valori file_id da utenti finali o da altre fonti non attendibili: un ID file fornito da un utente consentirebbe a un utente della tua applicazione di leggere contenuti caricati da un altro utente. Tratta gli ID file come riferimenti lato server e mantieni nella tua applicazione la mappatura tra i tuoi utenti e i loro file.
Se stai creando un’applicazione multitenant sulla Files API, crea un workspace separato per ciascun tenant. Il workspace è il confine di isolamento per i file, quindi un workspace per ciascun tenant garantisce ai dati di quel tenant un isolamento rigido da ogni altro tenant. Ogni organizzazione può avere fino a 100 workspace; contatta il tuo team di riferimento se ne hai bisogno di più.
Come usare la Files API
Caricare un file
Carica un file a cui fare riferimento nelle future chiamate API:
uploaded = client.files.upload(
file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
)
file_id = uploaded.id
print(file_id)La risposta al caricamento di un file include:
{
"id": "file_011CNha8iCJcU1wXNR6q4V8w",
"type": "file",
"filename": "document.pdf",
"mime_type": "application/pdf",
"size_bytes": 1024000,
"created_at": "2025-01-01T00:00:00Z",
"downloadable": false,
"expires_at": null
}downloadableAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro) è false per i file che carichi. Solo i file creati dalle skill o dallo strumento di esecuzione del codice possono essere scaricati. Consulta Scaricare un file.
Il riferimento API descrive ogni campo dell’oggetto file.
Usare un file nei messaggi
Una volta caricato, fai riferimento al file passando l’id della risposta di caricamento come file_id:
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Please summarize this document for me."},
{
"type": "document",
"source": {
"type": "file",
"file_id": file_id,
},
},
],
}
],
)
print(response)Tipi di file e blocchi di contenuto
La Files API 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, attività visive |
| Dataset, altri (consulta Caricare e analizzare i propri file) | Varia | container_upload | Analisi dei dati, visualizzazione |
Blocchi documento
Per PDF e file di testo, usa il blocco di contenuto document:
{
"type": "document",
"source": {
"type": "file",
"file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
},
"title": "Document Title", // Optional
"context": "Context about the document", // Optional
"citations": { "enabled": true } // Optional, enables citations
}Blocchi immagine
Per le immagini, usa il blocco di contenuto image:
{
"type": "image",
"source": {
"type": "file",
"file_id": "file_011CPMxVD3fHLUhvTqtsQA5w"
}
}Blocchi di caricamento nel container
Per inviare un file allo strumento di esecuzione del codice, usa il blocco di contenuto container_upload:
{
"type": "container_upload",
"file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
}Lavorare con altri formati di file
Per i tipi di file che il blocco document non supporta (ad esempio, .docx e .xlsx), converti i file in testo semplice e includi il contenuto direttamente nel tuo messaggio. I file che sono già in testo semplice, come i file .csv e .md, possono essere letti in questo modo oppure caricati tramite la Files API con un tipo di contenuto text/plain esplicito. Per analizzare i dataset invece di leggerli come testo, caricali per lo strumento di esecuzione del codice utilizzando un blocco container_upload (consulta Caricare e analizzare i propri file).
Gli esempi seguenti leggono un file di testo e ne inviano il contenuto come testo semplice:
client = anthropic.Anthropic()
# Leggi il file di testo
with open("document.txt") as f:
text_content = f.read()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": f"""Here's the document content:
{text_content}
Please summarize this document.""",
}
],
}
],
)
for block in response.content:
if block.type == "text":
print(block.text)Gestire i file
Elencare i file
Recupera un elenco dei file che hai caricato. L’endpoint è paginato: ogni richiesta restituisce fino a limitAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro) file (20 per impostazione predefinita e al massimo 1.000), e il cursore next_pageAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro) della risposta recupera la pagina successiva quando viene ripassato come parametro pageAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro). I file sono ordinati dal più recente. Consulta il riferimento API Elenca i fileAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro). L’SDK restituisce la prima pagina e fornisce helper di paginazione automatica.
client = anthropic.Anthropic()
files = client.files.list()
print(files)Per verificare un insieme noto di file in una singola richiesta invece di paginare, passa fino a 100 ID file come parametri di query ids[]. Una richiesta ids[] differisce da un elenco paginato in tre modi:
- Non puoi combinare
ids[]conpageolimit. - La risposta è sempre una singola pagina (
next_pageènull). - Se un ID non corrisponde a un file nel tuo workspace, l’API omette quell’ID da
datasenza restituire un errore. Per trovare gli ID omessi dall’API, confronta gli ID restituiti con gli ID richiesti.
Ottenere i metadati di un file
Recupera le informazioni su un file specifico:
file = client.files.retrieve_metadata(file_id)
print(file)Eliminare un file
Elimina un file dal tuo workspace:
client.files.delete(file_id)Scaricare un file
Scarica i file creati dalle skill o dallo strumento di esecuzione del codice. I file che carichi non possono essere scaricati. Il file_id di un file generato appare nel blocco di contenuto bash_code_execution_tool_result della risposta Messages che ha creato il file. Usa quel file_id nella richiesta di download:
file_content = client.files.download(file_id)
file_content.write_to_file("downloaded_file.txt")Sulla Claude API, i file di immagine, video e audio supportati che Claude produce con lo strumento di esecuzione del codice, inclusi i file creati dalle skill, includono Content Credentials C2PA firmate quando li scarichi. Consulta Content Credentials sui file generati per sapere cosa contiene la credenziale e come verificarla.
Archiviazione dei file e limiti
Limiti di archiviazione
- Dimensione massima del file: 500 MB per ciascun file
- Spazio di archiviazione totale: 1 TB per ciascuna organizzazione
Ciclo di vita dei file
- I file sono limitati al workspace in cui sono stati caricati. Qualsiasi richiesta nello stesso workspace può farvi riferimento; non accettare mai ID file da fonti non attendibili (consulta l’avviso sull’accesso al workspace).
- I file non possono essere modificati o rinominati dopo il caricamento. Per cambiare il contenuto di un file, carica un nuovo file ed elimina quello vecchio.
- I file persistono finché non li elimini con l’endpoint
DELETE /v1/files/{file_id}o finché non raggiungono il loroexpires_at. - I file eliminati non possono essere recuperati.
- I file diventano inaccessibili tramite l’API poco dopo l’eliminazione, ma possono persistere nelle chiamate attive alla Messages API e negli usi degli strumenti associati.
- I file eliminati dagli utenti verranno eliminati in conformità con la politica di conservazione dei dati di Anthropic.
Scadenza dei file
Per fare in modo che un file scada automaticamente, includi un campo del modulo expires_in_secondsAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro) quando lo carichi. Il valore è un numero intero di secondi compreso tra 3.600 (1 ora) e 7.776.000 (90 giorni). Il timestamp expires_atAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro) risultante (RFC 3339) compare in ogni risposta relativa ai file ed è null per i file caricati senza scadenza. La scadenza viene impostata una sola volta al momento del caricamento e non può essere modificata.
Quando un file raggiunge il suo expires_at:
- Il download del suo contenuto (
GET /v1/files/{file_id}/content) restituisce un errore 404. - Una richiesta Messages che fa riferimento al file non riesce prima dell’inferenza.
- I suoi metadati (
GET /v1/files/{file_id}) restano leggibili per un massimo di 30 giorni, conexpires_atnel passato. - Continua a comparire nelle risposte di elenco durante tale periodo; confronta
expires_atcon l’ora corrente per filtrare i file scaduti.
Eliminare un file scaduto con DELETE /v1/files/{file_id} rimuove immediatamente i suoi metadati invece di attendere che trascorra la finestra di 30 giorni.
Registrazione di audit
Se la tua organizzazione ha la Compliance API abilitata, il suo Activity Feed registra le operazioni della Files API effettuate con una chiave API Claude o dalla Claude Console: ogni caricamento (POST /v1/files), download di contenuto (GET /v1/files/{file_id}/content) ed eliminazione (DELETE /v1/files/{file_id}) appare come attività platform_file_uploaded, platform_file_content_downloaded o platform_file_deleted. L’elenco dei file e il recupero dei metadati dei file non vengono registrati. Le operazioni che avvengono mentre la Compliance API è disattivata non vengono registrate e non possono essere recuperate in seguito, quindi configura la Compliance API prima di fare affidamento su questa traccia di audit. Su Claude Platform on AWS, esegui invece l’audit delle operazioni sui file con gli eventi dati di AWS CloudTrail.
Migrare da files-api-2025-04-14
La Files API è uscita dalla beta e non richiede alcun header beta. La migrazione da files-api-2025-04-14 è facoltativa: le richieste che lo inviano continuano a funzionare e continuano a restituire le forme di risposta beta, quindi un’integrazione esistente continua a funzionare finché non la modifichi. Rimuovere l’header fa passare quelle richieste alle forme documentate in questa pagina:
Con files-api-2025-04-14 | Senza l’header | |
|---|---|---|
| Risposta di elenco | { data, has_more, first_id, last_id } | { data, next_page }; ripassa next_page come parametro di query page |
| Cursori di elenco | before_id, after_id | page, oppure fino a 100 ids[] (before_id e after_id restituiscono un errore 400) |
expires_at sugli oggetti file | Non restituito | Sempre presente; null quando il file non ha scadenza |
Content-Type sulla parte del file caricato | Obbligatorio | Facoltativo; il tipo viene rilevato quando omesso |
Per migrare:
- Rimuovi l’header beta. Elimina
anthropic-beta: files-api-2025-04-14dalle tue richieste. Con l’SDK, chiamaclient.filesinvece diclient.beta.files; mantenereclient.beta.filesfunziona solo con le versioni dell’SDK che non inviano più l’header. Le versioni precedenti lo inviano daclient.beta.filesanche quando non passi alcun nome beta. - Aggiorna la paginazione. Sostituisci i cicli
after_id/before_idcon il cursorepage/next_page, oppure usa gli helper di auto-paginazione degli SDK mostrati in Gestire i file. - Leggi
expires_at. Il campo appare solo senza l’header;nullsignifica che il file non ha scadenza (consulta Scadenza dei file).
Namespace beta degli SDK
L’SDK offre la Files API in due namespace. Questa pagina usa il namespace stabile, mentre le funzionalità dei file che sono in beta usano il namespace beta.
A partire dalla versione del tuo SDK indicata nella tabella seguente, il namespace beta differisce da quello delle versioni precedenti in due modi:
- Non invia più
files-api-2025-04-14. - Restituisce le stesse strutture del namespace stabile, ma con nomi di tipo con prefisso
Beta.
La tabella riporta anche i nomi dei namespace di ciascun SDK e dove il namespace beta accetta i valori anthropic-beta:
| SDK | Namespace stabile | Namespace beta | Namespace beta modificato in | I valori anthropic-beta vanno in |
|---|---|---|---|---|
| Python | client.files | client.beta.files | 1.2.0 | betas |
| TypeScript | client.files | client.beta.files | 0.122.0 | betas |
| C# | client.Files | client.Beta.Files | 12.44.0 | Betas |
| Go | client.Files | client.Beta.Files | 1.68.0 | Betas |
| Java | client.files() | client.beta().files() | 2.59.0 | .addBeta() |
| PHP | $client->files | $client->beta->files (classi in Anthropic\Beta) | 0.45.0 | betas |
| Ruby | client.files | client.beta.files | 1.67.0 | betas |
Per una funzionalità dei file che è in beta, usa il namespace beta e passa il valore anthropic-beta della funzionalità come mostrato nella tabella. Ad esempio, con un header beta di Managed Agents, scope_id limita un elenco di file ai file di una sessione. Per usare scope_id, consulta Elenco e download dei file di sessione.
Nelle versioni precedenti a quella del tuo SDK indicata nella tabella, i tipi del namespace beta corrispondono alle strutture restituite da files-api-2025-04-14. Se dipendi da tali tipi, resta su una di tali versioni finché non esegui la migrazione da essi.
Le richieste che contengono anthropic-beta: managed-agents-2026-04-01 senza files-api-2025-04-14 ricevono le forme di questa pagina con una concessione di compatibilità su GET /v1/files: before_id e after_id sono ancora accettati (non combinabili con page o ids[]), e la risposta di elenco include has_more, first_id e last_id insieme a next_page. Le versioni beta successive di Managed Agents ricevono la forma semplice.
Gestione degli errori
Gli errori comuni nell’uso della Files API includono:
- File non trovato (404): Il
file_idspecificato non esiste o non hai accesso a esso. - Tipo di file non valido (400): Il tipo di file non corrisponde al tipo di blocco di contenuto (ad esempio, utilizzo di un file immagine in un blocco documento).
- Non scaricabile (400): I file che carichi hanno
"downloadable": falsee non possono essere scaricati. Solo i file creati dalle skill o dallo strumento di esecuzione del codice possono essere scaricati. - Supera la dimensione della finestra di contesto (400): Il file è più grande della dimensione della “context window” (finestra di contesto) (ad esempio, utilizzo di 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 non consentiti (
<,>,:,",|,?,*,\,/o i caratteri Unicode 0–31). - File troppo grande (413): Il file supera il limite di 500 MB.
- Limite di archiviazione superato (400): La tua organizzazione ha raggiunto il limite di archiviazione di 1 TB.
{
"type": "error",
"error": {
"type": "not_found_error",
"message": "File `file_011CNha8iCJcU1wXNR6q4V8w` not found."
},
"request_id": "req_011CQFYcrRp7mCHLDsAYT8Qt"
}Utilizzo e fatturazione
Le operazioni della Files API sono gratuite:
- Caricamento di file
- Download di file
- Elenco dei file
- Recupero dei metadati dei file
- Eliminazione di file
Il contenuto dei file usato nelle richieste Messages viene tariffato come token di input.
Limiti di velocità
Le chiamate API relative ai file sono soggette a un “rate limit” (limite di velocità) di circa 500 richieste al minuto. Per richiedere un limite più alto, contatta il team commerciale.
Passaggi successivi
Elabora i PDF con Claude. Estrai testo, analizza grafici e comprendi il contenuto visivo dei tuoi documenti.
Esegui codice Python e Bash in un container sandbox per analizzare dati, generare file e iterare sulle soluzioni.
Elabora e analizza input visivi e genera testo e codice a partire dalle immagini.
Disponibilità
Claude API
- API
- Messages API
- Managed Agents
- Modelli
- Tutti i modelli
Claude Platform on AWS
- API
- Messages API
- Managed Agents
- Modelli
- Tutti i modelli
Claude Models on Google Cloud (Anthropic managed)
- API
- Messages API
- Managed Agents
- Modelli
- Tutti i modelli
Microsoft Foundry (hosted on Anthropic)
- API
- Messages API
- Modelli
- Tutti i modelli
Gestione dei dati
Panoramica sulla gestione dei datiEndpoint applicabili
/v1/files
File conservati finché non vengono eliminati esplicitamente o raggiungono la scadenza configurata. Scopri di più
Questa pagina ti è stata utile?