Files API

L'API Files ti consente di caricare e gestire file da utilizzare con l'API Claude senza ricaricare il contenuto ad ogni richiesta. Questo è particolarmente utile quando si utilizza lo strumento di esecuzione del codice per fornire input (ad es. dataset e documenti) e quindi scaricare output (ad es. grafici). Puoi anche utilizzare l'API Files per evitare di ricaricare continuamente documenti e immagini utilizzati di frequente in più chiamate API. Puoi esplorare il riferimento API direttamente, oltre a questa guida.

L'API Files è in beta. Contattaci tramite il modulo di feedback per condividere la tua esperienza con l'API Files.

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

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 Haiku 4.5 più tutti i modelli Claude 3.7+.

L'API Files non è attualmente supportata su Amazon Bedrock o Google Vertex AI.

Come funziona l'API Files

L'API Files fornisce un approccio semplice carica-una-volta-usa-molte-volte per lavorare con i file:

Carica file nell'archiviazione sicura di Anthropic e ricevi un file_id univoco
Scarica file creati da skill o 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 e eliminazione

Come utilizzare l'API Files

Per utilizzare l'API Files, dovrai includere l'intestazione della funzione beta: anthropic-beta: files-api-2025-04-14.

Caricamento di un file

Carica un file da utilizzare nelle future chiamate API:

La risposta dal caricamento di un file includerà:

Output

{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file",
  "filename": "document.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1024000,
  "created_at": "2025-01-01T00:00:00Z",
  "downloadable": false
}

Utilizzo di un file nei messaggi

Una volta caricato, fai riferimento al 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
PDF	`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

Utilizzo di altri formati di file

Per i tipi di file non 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, quindi utilizza il supporto PDF per sfruttare l'analisi delle immagini integrata. Questo consente di utilizzare le citazioni dal documento PDF.

Blocchi di documento

Per PDF e file di testo, utilizza 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 di immagine

Per le immagini, utilizza il blocco di contenuto image:

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

Gestione dei file

Elencare i 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:

Scaricamento di un file

Scarica file creati da skill o dallo strumento di esecuzione del codice:

Puoi scaricare solo i file creati da skill o 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: 500 MB per file
Archiviazione totale: 500 GB per organizzazione

Ciclo di vita del 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 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
I file che gli utenti eliminano verranno eliminati in conformità alla politica di conservazione dei dati di Anthropic.

Conservazione dei dati

I file caricati tramite l'API Files vengono conservati fino a quando non vengono eliminati esplicitamente utilizzando l'endpoint DELETE /v1/files/{file_id}. I file vengono archiviati per il riutilizzo in più richieste API.

Per l'idoneità ZDR in tutte le funzioni, vedi API e conservazione dei dati.

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 es. utilizzo di 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 es. utilizzo di un file di testo semplice di 500 MB in una richiesta /v1/messages)
Nome file non valido (400): Il nome file non soddisfa i requisiti di lunghezza (1-255 caratteri) o contiene caratteri vietati (<, >, :, ", |, ?, *, \, /, o caratteri unicode 0-31)
Il file supera il limite di 500 MB

Output

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "File not found: file_011CNha8iCJcU1wXNR6q4V8w"
  }
}

Utilizzo e fatturazione

Le operazioni dell'API Files sono gratuite:

Caricamento di file
Scaricamento di file
Elenco di file
Ottenimento dei metadati del file
Eliminazione di file

Il contenuto del file utilizzato nelle richieste Messages viene addebitato come token di input. Puoi scaricare solo i file creati da skill o 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ù elevati per il tuo caso d'uso

response = client.beta.messages.create(
    model="claude-opus-4-6",
    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,
                    },
                },
            ],
        }
    ],
    betas=["files-api-2025-04-14"],
)
print(response)

import pandas as pd
# ...
# Example: Reading a CSV file
df = pd.read_csv("data.csv")
csv_content = df.to_string()

# Send as plain text in the message
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": f"Here's the CSV data:\n\n{csv_content}\n\nPlease analyze this data.",
                }
            ],
        }
    ],
)

print(response.content[0].text)