Files API

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 API, 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 i modelli Claude attuali. 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_id univoco
• Scarica file creati dalle skill o dallo strumento di esecuzione del codice
• Fai riferimento ai file nelle richieste Messages usando il file_id invece di ricaricare il contenuto
• Gestisci i tuoi file con operazioni di elenco, recupero ed eliminazione

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
}

downloadable è 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.

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:

Blocchi document

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 image

Per le immagini, usa il blocco di contenuto image:

{
  "type": "image",
  "source": {
    "type": "file",
    "file_id": "file_011CPMxVD3fHLUhvTqtsQA5w"
  }
}

Blocchi container upload

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 usando un blocco container_upload.

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:\n\n{text_content}\n\nPlease 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 caricati. L'endpoint è paginato: ogni richiesta restituisce fino a limit file (20 per impostazione predefinita e al massimo 1.000), e il cursore next_page della risposta recupera la pagina successiva quando viene ripassato come parametro page. I file sono ordinati dal più recente. Consulta il riferimento API List Files. Gli SDK restituiscono la prima pagina e forniscono helper di auto-paginazione. L'esempio CLI limita il totale con --max-items:

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[] restituisce sempre una singola pagina (next_page è null), e qualsiasi ID che non corrisponde a un file nel tuo workspace viene omesso silenziosamente da data; confronta gli ID restituiti con gli ID richiesti per rilevare quelli mancanti. ids[] non può essere combinato con page o limit.

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

Rimuovi 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 lo ha creato:

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 file
• Archiviazione totale: 1 TB per 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 loro expires_at
• I file eliminati non possono essere recuperati
• I file diventano inaccessibili tramite l'API poco dopo l'eliminazione, ma possono persistere nelle chiamate Messages API attive e negli usi degli strumenti associati
• I file che gli utenti eliminano verranno eliminati in conformità con la politica di conservazione dei dati di Anthropic. Per l'idoneità ZDR di tutte le funzionalità, consulta API e conservazione dei dati

Scadenza dei file

Per far scadere automaticamente un file, includi un campo form expires_in_seconds 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_at risultante (RFC 3339) appare in ogni risposta relativa al file ed è null per i file caricati senza scadenza. La scadenza viene impostata una sola volta al 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 fallisce prima dell'inferenza
• I suoi metadati (GET /v1/files/{file_id}) restano leggibili per un massimo di 30 giorni, con expires_at nel passato
• Continua ad apparire nelle risposte di elenco durante quella finestra; confronta expires_at con 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 ancora 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:

Per migrare:

1. Rimuovi l'header beta. Elimina anthropic-beta: files-api-2025-04-14 dalle tue richieste. Negli SDK, chiama client.files invece di client.beta.files; mantenere client.beta.files funziona solo sulle versioni degli SDK che non inviano più l'header. Le versioni precedenti lo inviano da client.beta.files anche senza argomento betas.
2. Aggiorna la paginazione. Sostituisci i cicli after_id/before_id con il cursore page/next_page, oppure usa gli helper di auto-paginazione degli SDK mostrati in Gestire i file.
3. Leggi expires_at. Il campo appare solo senza l'header; null significa che il file non ha scadenza (consulta Scadenza dei file).

Namespace beta degli SDK

A partire da Python SDK 1.2.0, TypeScript SDK 0.122.0, Go SDK 1.68.0, Java SDK 2.59.0, Ruby SDK 1.67.0 e C# SDK 12.44.0, client.beta.files non invia più files-api-2025-04-14 e restituisce le stesse forme di client.files, con nomi di tipo con prefisso Beta. Accetta un argomento betas per le funzionalità Files ancora in beta, come il filtro scope_id sotto un header beta Managed Agents. Le versioni precedenti degli SDK sono tipizzate sulle forme beta; se dipendi da quei tipi, resta su una versione precedente finché non migri.

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_id specificato 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, usare un file immagine in un blocco document)
• Non scaricabile (400): I file che carichi hanno "downloadable": false e 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, usare 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 vietati (<, >, :, ", |, ?, *, \, / o 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

Compatibility