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 dover ricaricare continuamente documenti e immagini di uso frequente in più chiamate API. Puoi esplorare il riferimento API direttamente, oltre a questa guida.

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 semplice approccio carica una volta, usa molte volte per lavorare con i file:

• Carica file nel nostro archivio sicuro 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 ed eliminazione

Come utilizzare l'API Files

Caricamento di un file

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

La risposta dal caricamento di un file includerà:

{
  "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:

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

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:

# Esempio: Lettura di un file di testo e invio come testo semplice
# Nota: Per i 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-opus-4-6",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Here's the document content:\n\n${TEXT_CONTENT}\n\nPlease summarize this document."
        }
      ]
    }
  ]
}
EOF

Blocchi di documento

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

{
  "type": "document",
  "source": {
    "type": "file",
    "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
  },
  "title": "Document Title", // Facoltativo
  "context": "Context about the document", // Facoltativo
  "citations": {"enabled": true} // Facoltativo, abilita le citazioni
}

Blocchi di immagine

Per le immagini, utilizza il blocco di contenuto image:

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

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_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"

Scaricamento di un file

Scarica file creati da skill o 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

Archiviazione dei file e limiti

Limiti di archiviazione

• Dimensione massima del file: 500 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 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 nostra politica di 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)
• 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 not found: file_011CNha8iCJcU1wXNR6q4V8w"
  }
}

Utilizzo e fatturazione

Le operazioni dell'API Files sono gratuite:

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

Il contenuto dei 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ù alti per il tuo caso d'uso