L’API Files ti consente di caricare e gestire file da utilizzare con l’API Anthropic senza dover ricaricare il contenuto 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 Files per evitare di dover continuamente ricaricare documenti e immagini utilizzati frequentemente attraverso più chiamate API.

L’API Files è attualmente in beta. Ti preghiamo di contattarci attraverso il nostro modulo di feedback per condividere la tua esperienza con l’API Files.

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

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

Come funziona l’API Files

L’API Files fornisce un approccio semplice crea-una-volta, usa-molte-volte per lavorare con i file:

  • Carica file nel nostro storage sicuro e ricevi un file_id unico
  • Scarica file che vengono creati dallo strumento di esecuzione del codice
  • Riferisci 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 Files

Per utilizzare l’API Files, dovrai includere l’header della funzionalità beta: anthropic-beta: files-api-2025-04-14.

Caricamento di un file

Carica un file da riferire 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"

Utilizzo di un file nei messaggi

Una volta caricato, riferisci il file utilizzando il suo file_id:

curl -X POST https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Per favore riassumi questo documento per me."          
          },
          {
            "type": "document",
            "source": {
              "type": "file",
              "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
            }
          }
        ]
      }
    ]
  }'

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 FileTipo MIMETipo 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, altriVariacontainer_uploadAnalizzare dati, creare visualizzazioni

Lavorare con altri formati di file

Per i tipi di file che non sono supportati come blocchi document (.csv, .txt, .md, .docx, .xlsx), converti i file in testo semplice e includi il contenuto direttamente nel tuo messaggio:

# Esempio: Leggere un file di testo e inviarlo come testo semplice
# Nota: Per file con caratteri speciali, considera la codifica base64
TEXT_CONTENT=$(cat document.txt | jq -Rs .)

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d @- <<EOF
{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Ecco il contenuto del documento:\n\n${TEXT_CONTENT}\n\nPer favore riassumi questo documento."
        }
      ]
    }
  ]
}
EOF

Per i file .docx contenenti immagini, convertili prima in formato PDF, poi utilizza il supporto PDF per sfruttare l’analisi delle immagini integrata. Questo consente di utilizzare citazioni dal documento PDF.

Blocchi documento

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

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

Blocchi 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:

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 metadati del file

Recupera informazioni su un file specifico:

curl https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w \
  -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_011CNha8iCJcU1wXNR6q4V8w \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

Scaricare un file

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

curl -X GET "https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w/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 file che sono stati creati dallo strumento di esecuzione del codice. I file che hai caricato non possono essere scaricati.


Archiviazione e limiti dei file

Limiti di archiviazione

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

Ciclo di vita dei 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 finché 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 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 esempio, utilizzare 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 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 proibiti (<, >, :, ", |, ?, *, \, /, o caratteri unicode 0-31)
  • 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
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "File non trovato: file_011CNha8iCJcU1wXNR6q4V8w"
  }
}

Utilizzo e fatturazione

Le operazioni dell’API 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 prezzato come token di input. Puoi scaricare solo file creati 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ù alti per il tuo caso d’uso