Files API

La Files API ti consente di caricare e gestire file da utilizzare con l'API di Claude senza ricaricare il contenuto a 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 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 specificato. Le immagini sono supportate su tutti i modelli Claude attuali. Per i PDF e 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
• Referenzia 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 la Files API



Caricare un file

Carica un file da referenziare 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
}

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.



Utilizzare un file nei messaggi

Una volta caricato, referenzia il file passando l'id dalla risposta di caricamento come file_id:

response = client.messages.create(
    model="claude-opus-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 dataset invece di leggerli come testo, caricali per lo strumento di esecuzione del codice utilizzando 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",
    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 tuoi file caricati. L'endpoint è paginato: ogni richiesta restituisce fino a limit file (20 per impostazione predefinita), e i parametri before_id e after_id recuperano la pagina adiacente. 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.beta.files.list()
print(files)



Ottenere i metadati di un file

Recupera 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")



Archiviazione dei file e limiti



Limiti di archiviazione

• Dimensione massima del file: 500 MB per file
• Archiviazione totale: 500 GB per organizzazione



Ciclo di vita dei file

• I file sono limitati al workspace della chiave API che li ha caricati. Qualsiasi chiave API nello stesso workspace può referenziarli; 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 modificare 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}
• I file eliminati non possono essere recuperati
• I file diventano inaccessibili tramite l'API poco dopo l'eliminazione, ma potrebbero persistere nelle chiamate API Messages attive e negli usi degli strumenti associati
• I file che gli utenti eliminano saranno eliminati in conformità con la policy di conservazione dei dati di Anthropic. Per l'idoneità ZDR su tutte le funzionalità, consulta API e conservazione dei dati



Gestione degli errori

Gli errori comuni quando si utilizza la Files API 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 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 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 non consentiti (<, >, :, ", |, ?, *, \, /, 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 500 GB

{
  "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 utilizzato nelle richieste Messages viene addebitato come token di input.



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ù elevati per il tuo caso d'uso



Passaggi successivi