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