DEV Community

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

Posted on Originally published at apidog.com

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

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 de téléverser un fichier une seule fois sur https://api.anthropic.com/v1/files, d'obtenir un file_id, puis de référencer cet ID dans n'importe quelle requête Messages au lieu de renvoyer le contenu à chaque appel. Depuis le 20 août 2026, elle est généralement disponible sur la Claude Platform : plus 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 sur les agents de production, aux côtés du GA pour l'utilisation d'ordinateurs, l'outil de navigateur et l'API Skills.

Essayez Apidog dès aujourd'hui

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

Ce que fait l'API Files

L'API Files est une couche de stockage « crée-une-fois, utilise-plusieurs-fois » pour l'API Claude. Elle répond à un coût précis : si votre application interroge le même PDF de 40 pages lors de centaines de requêtes, 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éverser un fichier dans le stockage d'Anthropic et recevoir un file_id unique
  • Référencer 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 réduite :

Opération Point d'entrée
Téléverser 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 des requêtes.

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 change quatre choses importantes pour la planification en production :

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

  1. Pas d'en-tête bêta. Les requêtes fonctionnent avec les en-têtes standard de l'API Claude.
  2. Limites de débit 5x plus élevées. Les opérations sur les fichiers autorisent désormais environ 500 requêtes par minute, avec des limites supérieures disponibles auprès du service commercial.
  3. 1 To de stockage par organisation, avec une limite de 500 Mo par fichier.
  4. 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éverser 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-[REDACTED CREDENTIAL] \
  -H "anthropic-version: 2023-06-01" \
  -F "file=@/path/to/report.pdf"
Enter fullscreen mode Exit fullscreen mode

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
}
Enter fullscreen mode Exit fullscreen mode

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 expiration au moment du téléversement (détails ci-dessous).

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

Référencer des fichiers dans les messages

Une fois le fichier téléversé, il s'intègre à une requête Messages via l'un des trois types de bloc de contenu, selon le 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 varie 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-[REDACTED CREDENTIAL] \
  -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"}}
      ]
    }]
  }'
Enter fullscreen mode Exit fullscreen mode

Le bloc document accepte également les champs optionnels title, context et citations, qui vous permettent 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écharger les 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-[REDACTED CREDENTIAL] \
  -H "anthropic-version: 2023-06-01" \
  --output chart.png
Enter fullscreen mode Exit fullscreen mode

Tenter de télécharger un fichier que vous avez téléversé renvoie une erreur 400. Vérifiez le drapeau downloadable dans les métadonnées avant d'implémenter une logique de nouvelle tentative : cela évite un ticket de support. Cette boucle « 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'à l'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). La valeur est définie une seule fois et ne peut pas être modifiée 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, sans possibilité d'annulation. Le contenu expiré est libéré de votre quota de stockage, mais peut être conservé brièvement pour un examen de sécurité : l'expiration est donc un outil de cycle de vie, pas un contrôle de suppression garanti.

Le modèle de sécurité : les fichiers ont pour périmètre l'espace de travail

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

Les règles pratiques :

  • N'acceptez jamais de valeurs file_id provenant d'utilisateurs finaux. Un ID fourni par un 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éversement, 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 à la 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
Enter fullscreen mode Exit fullscreen mode

Le jeton provient d'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.
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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éversez 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 scripte 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.

Pour aller plus loin, voici comment générer une documentation API publique avec Apidog :

Top comments (0)