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:

curl -X POST https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -F "file=@/path/to/document.pdf"

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 FileMIME TypeTipo di Blocco di ContenutoCaso d’Uso
PDFapplication/pdfdocumentAnalisi del testo, elaborazione di documenti
Testo semplicetext/plaindocumentAnalisi del testo, elaborazione
Immaginiimage/jpeg, image/png, image/gif, image/webpimageAnalisi di immagini, compiti visivi
Dataset, altriVaricontainer_uploadAnalisi dei dati, creazione di visualizzazioni

Blocchi di documento

Per PDF e file di testo, utilizza il blocco di contenuto document:

{
  "type": "document",
  "source": {
    "type": "file",
    "file_id": "file_abc123"
  },
  "title": "Titolo del Documento", // Opzionale
  "context": "Contesto sul documento", // Opzionale  
  "citations": {"enabled": true} // Opzionale, abilita le citazioni
}

Blocchi di immagine

Per le immagini, utilizza il blocco di contenuto image:

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

Gestione dei file

Elenco dei file

Recupera un elenco dei tuoi file caricati:

curl https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

Ottenere i metadati del file

Recupera informazioni su un file specifico:

curl https://api.anthropic.com/v1/files/file_abc123 \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

Eliminare un file

Rimuovi un file dal tuo workspace:

curl -X DELETE https://api.anthropic.com/v1/files/file_abc123 \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

Download di un file

Scarica i file che sono stati creati dallo strumento di esecuzione del codice:

curl -X GET "https://api.anthropic.com/v1/files/file_abc123/content" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  --output downloaded_file.txt

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)
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "File not found: file_abc123"
  }
}

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