Files API

La Files API vous permet de téléverser et de gérer des fichiers à utiliser avec l'API Claude sans avoir à re-téléverser du contenu à chaque requête. Cela est particulièrement utile lors de l'utilisation de l'outil d'exécution de code pour fournir des entrées (par exemple, des jeux de données et des documents) et télécharger des sorties (par exemple, des graphiques). Vous pouvez également utiliser la Files API pour éviter de devoir continuellement re-téléverser des documents et des images fréquemment utilisés lors de plusieurs appels API. Vous pouvez explorer la référence API directement, en plus de ce guide.

La Files API est en version bêta. Contactez-nous via le formulaire de retour pour partager votre expérience avec la Files API.

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

Modèles pris en charge

Le référencement d'un file_id dans une requête Messages est pris en charge dans tous les modèles qui prennent en charge le type de fichier donné. Par exemple, les images sont prises en charge dans tous les modèles Claude 3+, les PDFs dans tous les modèles Claude 3.5+, et divers autres types de fichiers pour l'outil d'exécution de code dans Claude Haiku 4.5 ainsi que tous les modèles Claude 3.7+.

La Files API n'est actuellement pas prise en charge sur Amazon Bedrock ou Google Vertex AI.

Fonctionnement de la Files API

La Files API fournit une approche simple de type « créer une fois, utiliser plusieurs fois » pour travailler avec des fichiers :

Téléverser des fichiers vers le stockage sécurisé d'Anthropic et recevoir un file_id unique
Télécharger des fichiers créés par des compétences ou l'outil d'exécution de code
Référencer des fichiers dans les requêtes Messages en utilisant le file_id au lieu de re-téléverser du contenu
Gérer vos fichiers avec des opérations de liste, de récupération et de suppression

Comment utiliser la Files API

Pour utiliser la Files API, vous devrez inclure l'en-tête de fonctionnalité bêta : anthropic-beta: files-api-2025-04-14.

Téléverser un fichier

Téléversez un fichier pour le référencer dans de futurs appels API :

La réponse au téléversement d'un fichier inclura :

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
}

Utiliser un fichier dans des messages

Une fois téléversé, référencez le fichier en utilisant son file_id :

Types de fichiers et blocs de contenu

La Files API prend en charge différents types de fichiers qui correspondent à différents types de blocs de contenu :

Type de fichier	Type MIME	Type de bloc de contenu	Cas d'utilisation
PDF	`application/pdf`	`document`	Analyse de texte, traitement de documents
Texte brut	`text/plain`	`document`	Analyse de texte, traitement
Images	`image/jpeg`, `image/png`, `image/gif`, `image/webp`	`image`	Analyse d'images, tâches visuelles
Jeux de données, autres

Travailler avec d'autres formats de fichiers

Pour les types de fichiers qui ne sont pas pris en charge en tant que blocs document (.csv, .txt, .md, .docx, .xlsx), convertissez les fichiers en texte brut et incluez le contenu directement dans votre message :

Pour les fichiers .docx contenant des images, convertissez-les d'abord au format PDF, puis utilisez la prise en charge des PDF pour profiter de l'analyse d'images intégrée. Cela permet d'utiliser des citations à partir du document PDF.

Blocs de documents

Pour les PDFs et les fichiers texte, utilisez le bloc de contenu document :

{
  "type": "document",
  "source": {
    "type": "file",
    "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
  },
  "title": "Titre du document", // Optionnel
  "context": "Contexte sur le document", // Optionnel
  "citations": { "enabled": true } // Optionnel, active les citations
}

Blocs d'images

Pour les images, utilisez le bloc de contenu image :

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

Gérer les fichiers

Lister les fichiers

Récupérez une liste de vos fichiers téléversés :

Obtenir les métadonnées d'un fichier

Récupérez des informations sur un fichier spécifique :

Supprimer un fichier

Supprimez un fichier de votre espace de travail :

Télécharger un fichier

Téléchargez des fichiers qui ont été créés par des compétences ou l'outil d'exécution de code :

Vous pouvez uniquement télécharger des fichiers qui ont été créés par des compétences ou l'outil d'exécution de code. Les fichiers que vous avez téléversés ne peuvent pas être téléchargés.

Stockage de fichiers et limites

Limites de stockage

Taille maximale de fichier : 500 Mo par fichier
Stockage total : 500 Go par organisation

Cycle de vie des fichiers

Les fichiers sont limités à l'espace de travail de la clé API. D'autres clés API peuvent utiliser des fichiers créés par n'importe quelle autre clé API associée au même espace de travail
Les fichiers persistent jusqu'à ce que vous les supprimiez
Les fichiers supprimés ne peuvent pas être récupérés
Les fichiers sont inaccessibles via l'API peu après leur suppression, mais ils peuvent persister dans les appels API Messages actifs et les utilisations d'outils associées
Les fichiers que les utilisateurs suppriment seront supprimés conformément à la politique de conservation des données d'Anthropic.

Conservation des données

Les fichiers téléversés via la Files API sont conservés jusqu'à leur suppression explicite à l'aide du point de terminaison DELETE /v1/files/{file_id}. Les fichiers sont stockés pour être réutilisés dans plusieurs requêtes API.

Pour l'éligibilité ZDR sur toutes les fonctionnalités, consultez API et conservation des données.

Gestion des erreurs

Les erreurs courantes lors de l'utilisation de la Files API incluent :

Fichier introuvable (404) : Le file_id spécifié n'existe pas ou vous n'y avez pas accès
Type de fichier invalide (400) : Le type de fichier ne correspond pas au type de bloc de contenu (par exemple, utiliser un fichier image dans un bloc de document)
Dépasse la taille de la fenêtre de contexte (400) : Le fichier est plus grand que la taille de la fenêtre de contexte (par exemple, utiliser un fichier texte brut de 500 Mo dans une requête /v1/messages)
Nom de fichier invalide (400) : Le nom de fichier ne respecte pas les exigences de longueur (1-255 caractères) ou contient des caractères interdits (<, >, :, ", |, ?, *, \, /, ou les caractères unicode 0-31)
Le fichier dépasse la limite de 500 Mo

Output

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

Utilisation et facturation

Les opérations de la Files API sont gratuites :

Téléversement de fichiers
Téléchargement de fichiers
Listage de fichiers
Obtention des métadonnées de fichiers
Suppression de fichiers

Le contenu des fichiers utilisé dans les requêtes Messages est facturé en tant que tokens d'entrée. Vous pouvez uniquement télécharger des fichiers créés par des compétences ou l'outil d'exécution de code.

Limites de débit

Pendant la période bêta :

Les appels API liés aux fichiers sont limités à environ 100 requêtes par minute
Contactez-nous si vous avez besoin de limites plus élevées pour votre cas d'utilisation

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"

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 @- <<EOF
{
  "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"
          }
        }
      ]
    }
  ]
}
EOF

# Exemple : Lire un fichier texte et l'envoyer en tant que texte brut
# Remarque : Pour les fichiers avec des caractères spéciaux, envisagez l'encodage base64
# ...
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": "Voici le contenu du document :\n\n${TEXT_CONTENT}\n\nVeuillez résumer ce document."
        }
      ]
    }
  ]
}
EOF

curl -X GET "https://api.anthropic.com/v1/files/$FILE_ID/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