API Claude Files : téléversez une fois, référencez partout (guide de disponibilité générale)

L'API Files de Claude vous permet d'uploader un fichier une seule fois sur https://api.anthropic.com/v1/files, d'obtenir un file_id, et de référencer cet ID dans n'importe quelle requête Messages au lieu de renvoyer le contenu à chaque fois. Au 20 août 2026, elle est généralement disponible sur la Claude Platform : pas d'en-tête bêta, 1 To de stockage par organisation et des limites de débit cinq fois supérieures à celles de la version bêta. Anthropic a annoncé ce changement dans son article post sur les agents de production, aux côtés du GA pour l'utilisation d'ordinateurs, de l'outil de navigateur et de l'API Skills.

Ce guide couvre tout le cycle de vie : téléchargement, référence des fichiers dans les messages, téléchargement des résultats générés, expiration, le modèle de sécurité de l'espace de travail et les limites que vous rencontrerez en production. Puisque chaque étape ici est un appel HTTP, votre agent de codage peut transformer l'intégralité du flux en un scénario de test Apidog CLI au lieu d'une pile de commandes curl ponctuelles.

Ce que fait l'API Files

L'API Files est une couche de stockage de type crée-une-fois, utilise-plusieurs-fois pour l'API Claude. Elle résout un coût spécifique : si votre application pose des questions sur le même PDF de 40 pages lors de centaines de requêtes, le fait de re-téléverser ce PDF dans chaque requête gaspille de la bande passante et complique le code de votre client. Avec l'API Files, vous pouvez :

Cycle de vie de l'API Claude Files : upload, référence par file_id, téléchargement, suppression

Télécharger un fichier dans le stockage d'Anthropic et recevoir un file_id unique
Faire référence à cet ID dans les requêtes Messages via un bloc de contenu
Télécharger les fichiers générés par les skills ou l'outil d'exécution de code (graphiques, feuilles de calcul, présentations)
Gérer tout avec les opérations list, retrieve-metadata et delete

La surface des points de terminaison est petite :

Opération	Point d'entrée
Télécharger un fichier	`POST /v1/files`
Lister les fichiers	`GET /v1/files`
Obtenir les métadonnées du fichier	`GET /v1/files/{file_id}`
Télécharger le contenu du fichier	`GET /v1/files/{file_id}/content`
Supprimer un fichier	`DELETE /v1/files/{file_id}`

Tout cela fonctionne avec les en-têtes standard x-api-key et anthropic-version: 2023-06-01. Si vous débutez avec l'API Messages elle-même, notre guide de l'API Claude Opus 5 couvre les bases de l'authentification et de la forme de la requête.

Ce qui a changé au GA

L'API Files a passé des mois en version bêta derrière un en-tête. La version GA du 20 août 2026 a changé quatre choses importantes pour la planification en production :

Ce qui a changé lorsque l'API Claude Files est passée au GA

Pas d'en-tête bêta. Les requêtes fonctionnent avec les en-têtes standards de l'API Claude.
Limites de débit 5x plus élevées. Les opérations sur les fichiers permettent désormais environ 500 requêtes par minute, avec des limites plus élevées disponibles auprès du service commercial.
1 To de stockage par organisation, avec une limite de 500 Mo par fichier.
Couverture de plateforme plus étendue. L'API Files fonctionne directement sur l'API Claude, sur la Claude Platform sur AWS en version bêta, et sur Microsoft Foundry lors de l'utilisation d'un déploiement Hosted on Anthropic. Elle n'est pas disponible sur Amazon Bedrock ou Google Cloud Vertex AI, et elle n'est pas éligible aux accords de non-rétention des données. Planifiez en conséquence si vous avez une politique de rétention stricte.

Télécharger un fichier

Les uploads sont des requêtes de formulaire multipart, pas du JSON :

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

La réponse vous donne tout ce dont vous avez besoin pour référencer le fichier plus tard :

{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file",
  "filename": "report.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1024000,
  "created_at": "2026-08-24T00:00:00Z",
  "downloadable": false,
  "expires_at": null
}

Deux champs méritent votre attention. downloadable est false pour tout ce que vous téléversez ; seuls les fichiers générés par Claude via des skills ou l'exécution de code peuvent être récupérés. Et expires_at est null à moins que vous ne définissiez une date d'expiration au moment du téléversement (davantage de détails ci-dessous).

Dans le test Apidog CLI ci-dessous, l'étape de téléversement enregistre id comme variable, de sorte que chaque requête en aval fasse référence à {{claude_file_id}} au lieu d'une chaîne codée en dur.

Référence des fichiers dans les messages

Une fois le fichier téléchargé, il s'intègre à une requête Messages via l'un des trois types de bloc de contenu, en fonction du fichier :

Type de fichier	MIME type	Bloc de contenu
PDF, texte brut	`application/pdf`, `text/plain`	`document`
Images	`image/jpeg`, `image/png`, `image/gif`, `image/webp`	`image`
Jeux de données et tout le reste	varies	`container_upload` (outil d'exécution de code)

Une requête de résumé de PDF ressemble à ceci :

curl -X POST https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 1024,
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Résumez ce document."},
        {"type": "document", "source": {"type": "file", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"}}
      ]
    }]
  }'

Le bloc document accepte également les champs optionnels title, context et citations, ce qui vous permet d'activer la sortie de citations par rapport au fichier téléversé. Pour les images, remplacez le type de bloc par image avec la même forme source. Pour les feuilles de calcul et les CSV que vous souhaitez analyser plutôt que lire, ou tout autre format que le bloc document ne prend pas en charge, utilisez container_upload pour remettre le fichier à l' outil d'exécution de code.

Une note sur le format : .docx et .xlsx ne sont pas pris en charge directement par le bloc document. Convertissez les fichiers Word en PDF pour conserver l'analyse d'images et les citations, ou extrayez le texte brut et envoyez-le en ligne.

Téléchargement des fichiers générés

Le point de terminaison de téléchargement existe pour la sortie, pas pour l'entrée. Lorsque Claude construit un graphique avec l'exécution de code ou produit une feuille de calcul via un skill, la réponse inclut un file_id à l'intérieur du bloc bash_code_execution_tool_result. Cet ID est téléchargeable :

curl "https://api.anthropic.com/v1/files/$FILE_ID/content" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  --output chart.png

Tenter de télécharger un fichier que vous avez téléchargé renvoie une erreur 400. Vérifiez le drapeau downloadable dans les métadonnées avant d'implémenter une logique de nouvelle tentative autour de cela ; cela évite un ticket de support. Cette boucle de "upload-in, generate-out" est l'épine dorsale du flux de travail de l'API Skills nouvellement GA, où les skills produisent des documents Office que vous récupérez via ce même point de terminaison. Notre guide sur Claude Skills explique ce que sont les skills et comment ils s'exécutent.

Expiration et cycle de vie des fichiers

Les fichiers persistent jusqu'à ce que vous les supprimiez ou jusqu'à une expiration que vous avez définie lors du téléversement :

Passez expires_in_seconds comme champ de formulaire lors du téléversement. Plage valide : 3600 (1 heure) à 7 776 000 (90 jours). Il est défini une seule fois et ne peut pas être modifié ultérieurement.
Après l'expiration de expires_at, les téléchargements de contenu renvoient un 404 et toute requête Messages faisant référence au fichier échoue avant l'inférence.
Les métadonnées restent lisibles jusqu'à 30 jours après l'expiration, et les fichiers expirés apparaissent toujours dans les réponses de liste pendant cette fenêtre. Comparez expires_at à l'heure actuelle lors du filtrage.
Supprimer un fichier le retire immédiatement et ne peut être annulé. Le contenu expiré est libéré de votre quota de stockage, mais peut être conservé brièvement pour un examen de sécurité, donc l'expiration est un outil de cycle de vie, pas un contrôle de suppression garanti.

Le modèle de sécurité : les fichiers sont périmètre d'espace de travail

C'est le point le plus pertinent de toute l'API. Les fichiers téléchargés sont accessibles à l'ensemble de votre espace de travail, et non limité à un utilisateur final, une conversation ou une session. Toute clé API dans le même espace de travail peut lire n'importe quel fichier y a été téléchargé, et toutes les clés partagent l'Espace de Travail par défaut de votre organisation, sauf si vous les assigniez ailleurs.

Les règles pratiques :

Ne jamais accepter de valeurs file_id provenant d'utilisateurs finaux. Un ID fourni par l'utilisateur permettrait à un utilisateur de votre application de lire le contenu des uploads d'un autre utilisateur. Traitez les IDs de fichiers comme des références côté serveur et maintenez le mappage utilisateur-fichier dans votre propre base de données.
Vous construisez multi-tenant ? Un espace de travail par locataire. L'espace de travail est la limite d'isolation. Chaque organisation reçoit jusqu'à 100 espaces de travail, et les équipes de compte d'Anthropic peuvent augmenter ce nombre.

Si vous suivez déjà les clés API par locataire pour l'attribution des coûts (sujet que nous abordons dans comment réduire votre facture d'API Claude), le même agencement d'espaces de travail vous offre une isolation de fichiers gratuite.

Limites et facturation

Les chiffres à connaître :

Limite	Valeur
Taille maximale du fichier	500 Mo
Stockage de l'organisation	1 To
Limitation de débit de l'API Files	environ 500 requêtes/minute
Longueur du nom de fichier	1 à 255 caractères
Plage d'expiration	1 heure à 90 jours

La facturation est conviviale : le téléchargement, le téléchargement, la liste et la suppression des fichiers sont gratuits. Vous payez uniquement lorsque le contenu d'un fichier entre dans une requête Messages, où il est facturé comme des jetons d'entrée ordinaires. Un PDF de 100 pages référencé dans dix requêtes coûte dix fois les mêmes jetons d'entrée ; l'API Files vous fait gagner de la bande passante et de la complexité client, pas des dépenses en jetons. Pour économiser sur le côté jetons, associez les références de fichiers au mise en cache de prompts.

Surveillez ces erreurs : 413 lorsqu'un fichier dépasse 500 Mo, 400 lorsque votre organisation atteint le plafond de 1 To, 400 lorsqu'un type de fichier ne correspond pas à son bloc de contenu (une image dans un bloc document, par exemple), et 404 pour les IDs en dehors de votre espace de travail.

Laissez Claude Code tester l'API Files avec Apidog CLI

L'API Files est un flux multi-étapes et avec état, elle mérite un test de régression, pas un historique de shell. Claude Code, ou tout agent de codage, peut construire et exécuter ce test via Apidog CLI. Configurez-le une fois :

npm install -g apidog-cli@latest
apidog login --with-token <VOTRE_JETON>
npx -y skills add https://apidog.com   # choisissez votre agent lorsqu'on vous le demande

Le jeton provient de Apidog sous Paramètres du compte, Jetons d'accès à l'API. Ensuite, donnez l'une de ces invites à l'agent :

Utilise Apidog CLI sur le projet <id>. Ajoute les points de terminaison de l'API Files (upload, list, métadonnées, download, delete) et POST /v1/messages, avec x-api-key provenant de {{ANTHROPIC_API_KEY}} et l'en-tête anthropic-version. Construis un scénario de test :
upload avec expires_in_seconds=3600 et assure que expires_at est défini, sauve l'id comme claude_file_id, fais-en référence dans un appel Messages et assure un 200, supprime-le, puis assure que l'appel de métadonnées retourne 404. Exécute-le et résume tout échec.

Les commandes qu'il exécute, vérifiées par rapport à Apidog CLI 2.2.7 :

apidog cli-schema get endpoint-create
apidog endpoint create --project <id> --file files-upload.json
apidog test-scenario create --project <id> --name "Files API lifecycle" --priority 1
apidog test-scenario import-steps <scenarioId> --project <id> --source endpoint \
  --ids <uploadId>,<messagesId>,<deleteId>,<metadataId> --sync manual
apidog cli-schema validate test-scenario-update --file lifecycle.json
apidog test-scenario update <scenarioId> --project <id> --file lifecycle.json
apidog run -t <scenarioId> --project <id> -e <envId> \
  --env-var "ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY" -r cli,json

L'agent répète endpoint create pour chaque point de terminaison, puis écrit l'extraction de variable et les assertions dans le scénario avant qu'il ne s'exécute. Changer les fichiers de test plus tard signifie modifier une seule étape d'upload, pas chaque requête. Demandez également un mock de la réponse de téléchargement (apidog mock create), et l'équipe frontend obtient la forme JSON avant que votre proxy backend n'existe. La même ligne apidog run avec -r junit se déploie en CI ; notre guide Apidog CLI dans Claude Code couvre la configuration de l'agent de bout en bout.

FAQ

Ai-je toujours besoin d'un en-tête bêta ? Non. Depuis le GA du 20 août 2026, l'API Files fonctionne sur l'API Claude avec les en-têtes standard x-api-key et anthropic-version. Si votre SDK ou proxy utilise toujours l'ancien en-tête bêta des fichiers, supprimez-le lors de la mise à niveau.

Puis-je mettre à jour le contenu d'un fichier ? Non. Les fichiers sont immuables après le téléversement. Téléversez un nouveau fichier, dirigez vos références vers le nouvel ID et supprimez l'ancien.

L'API Files fonctionne-t-elle sur Bedrock ou Vertex AI ? Non. Elle est sur l'API Claude, la Claude Platform sur AWS (bêta) et Microsoft Foundry avec un déploiement Hosted on Anthropic. Sur Bedrock et Vertex, vous avez toujours besoin de contenu base64 en ligne.

L'API Files est-elle la même chose que ce qu'utilise l'API Skills pour les sorties ? Oui. Les Skills et l'outil d'exécution de code écrivent leurs documents générés dans le même stockage de fichiers, et vous les téléchargez via GET /v1/files/{file_id}/content. Le côté API Skills de ce flux de travail s'associe bien aux tests automatisés.

Conclusion

La généralisation de l'API Files élimine la dernière excuse pour le remplissage en base64 du même document dans chaque requête. Téléchargez une fois, référez par ID, définissez une date d'expiration et maintenez les fichiers de locataires dans des espaces de travail séparés. La surface de l'API se compose de cinq points de terminaison, et chacun d'eux est testable en quelques minutes : faites en sorte que votre agent de codage scripts le flux avec Apidog CLI, chaînez le file_id à travers une variable et vérifiez le cycle de vie complet en CI avant que vos utilisateurs ne trouvent les cas limites pour vous.