API Files

L’API Files vous permet de téléverser et de gérer des fichiers à utiliser avec l’API Claude sans avoir à téléverser à nouveau le contenu à chaque requête. Cela est particulièrement utile lorsque vous utilisez l’outil d’exécution de code pour fournir des entrées (par exemple, des jeux de données et des documents), puis télécharger des sorties (par exemple, des graphiques). Vous pouvez explorer directement la référence de l’APIAperçu disponible avec des liens vers la référence de l’API, appuyez sur Tab jusqu’à ce que le focus entre dans la carte, et sur Échap pour revenir., en complément de ce guide.

Prise en charge des types de fichiers

La référence à un file_id dans une requête Messages est prise en charge sur tous les modèles qui prennent en charge le type de fichier concerné. Les images sont prises en charge sur tous les modèles Claude actuels. Pour les PDF et les autres types de fichiers avec l’outil d’exécution de code, consultez les pages liées pour connaître les modèles pris en charge.

Fonctionnement de l’API Files

L’API Files propose une approche « créer une fois, utiliser plusieurs fois » pour travailler avec des fichiers :

• Téléversez des fichiers vers le stockage sécurisé d’Anthropic et recevez un file_id unique
• Téléchargez des fichiers créés par les skills ou l’outil d’exécution de code
• Référencez des fichiers dans les requêtes MessagesAperçu disponible avec des liens vers la référence de l’API, appuyez sur Tab jusqu’à ce que le focus entre dans la carte, et sur Échap pour revenir. en utilisant le file_id au lieu de téléverser à nouveau le contenu
• Gérez vos fichiers avec les opérations de liste, de récupération et de suppression

Comment utiliser l’API Files

Téléverser un fichier

Téléversez un fichier à référencer dans de futurs appels d’API :

uploaded = client.files.upload(
    file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
)
file_id = uploaded.id
print(file_id)

La réponse au téléversement d’un fichier comprend :

{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file",
  "filename": "document.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1024000,
  "created_at": "2025-01-01T00:00:00Z",
  "downloadable": false,
  "expires_at": null
}

downloadableAperçu disponible avec des liens vers la référence de l’API, appuyez sur Tab jusqu’à ce que le focus entre dans la carte, et sur Échap pour revenir. vaut false pour les fichiers que vous téléversez. Seuls les fichiers créés par les skills ou l’outil d’exécution de code peuvent être téléchargés. Consultez Télécharger un fichier.

La référence de l’API décrit chaque champ de l’objet fichier.

Utiliser un fichier dans les messages

Une fois téléversé, référencez le fichier en transmettant l’id de la réponse de téléversement en tant que file_id :

response = client.messages.create(
    model="claude-opus-5-5",
    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,
                    },
                },
            ],
        }
    ],
)
print(response)

Types de fichiers et blocs de contenu

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

Blocs document

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

{
  "type": "document",
  "source": {
    "type": "file",
    "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
  },
  "title": "Document Title", // Optional
  "context": "Context about the document", // Optional
  "citations": { "enabled": true } // Optional, enables citations
}

Blocs image

Pour les images, utilisez le bloc de contenu image :

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

Blocs container upload

Pour envoyer un fichier à l’outil d’exécution de code, utilisez le bloc de contenu container_upload :

{
  "type": "container_upload",
  "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
}

Travailler avec d’autres formats de fichiers

Pour les types de fichiers que le bloc document ne prend pas en charge (par exemple, .docx et .xlsx), convertissez les fichiers en texte brut et incluez le contenu directement dans votre message. Les fichiers qui sont déjà en texte brut, tels que les fichiers .csv et .md, peuvent être lus de cette manière ou téléversés via l’API Files avec un type de contenu text/plain explicite. Pour analyser des jeux de données plutôt que de les lire comme du texte, téléversez-les pour l’outil d’exécution de code à l’aide d’un bloc container_upload (consultez Téléverser et analyser vos propres fichiers).

Les exemples suivants lisent un fichier texte et envoient son contenu sous forme de texte brut :

client = anthropic.Anthropic()

# Lire le fichier texte
with open("document.txt") as f:
    text_content = f.read()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": f"Here's the document content:\n\n{text_content}\n\nPlease summarize this document.",
                }
            ],
        }
    ],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

Gérer les fichiers

Lister les fichiers

Récupérez la liste de vos fichiers téléversés. Le point de terminaison est paginé : chaque requête renvoie jusqu’à limitAperçu disponible avec des liens vers la référence de l’API, appuyez sur Tab jusqu’à ce que le focus entre dans la carte, et sur Échap pour revenir. fichiers (20 par défaut, et au maximum 1 000), et le curseur next_pageAperçu disponible avec des liens vers la référence de l’API, appuyez sur Tab jusqu’à ce que le focus entre dans la carte, et sur Échap pour revenir. de la réponse permet de récupérer la page suivante lorsqu’il est renvoyé comme paramètre pageAperçu disponible avec des liens vers la référence de l’API, appuyez sur Tab jusqu’à ce que le focus entre dans la carte, et sur Échap pour revenir.. Les fichiers sont triés du plus récent au plus ancien. Consultez la référence de l’API « Lister les fichiers »Aperçu disponible avec des liens vers la référence de l’API, appuyez sur Tab jusqu’à ce que le focus entre dans la carte, et sur Échap pour revenir.. Le SDK renvoie la première page et fournit des utilitaires de pagination automatique.

client = anthropic.Anthropic()
files = client.files.list()
print(files)

Pour vérifier un ensemble connu de fichiers en une seule requête plutôt que de paginer, transmettez jusqu’à 100 identifiants de fichiers en tant que paramètres de requête ids[]. Une requête ids[] renvoie toujours une seule page (next_page vaut null), et tout identifiant qui ne correspond pas à un fichier de votre espace de travail est silencieusement omis de data ; comparez les identifiants renvoyés aux identifiants demandés pour détecter les absences. ids[] ne peut pas être combiné avec page ou limit.

Obtenir les métadonnées d’un fichier

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

file = client.files.retrieve_metadata(file_id)
print(file)

Supprimer un fichier

Supprimez un fichier de votre espace de travail :

client.files.delete(file_id)

Télécharger un fichier

Téléchargez les fichiers créés par les skills ou l’outil d’exécution de code. Les fichiers que vous téléversez ne peuvent pas être téléchargés. Le file_id d’un fichier généré apparaît dans le bloc de contenu bash_code_execution_tool_result de la réponse Messages qui l’a créé :

file_content = client.files.download(file_id)

file_content.write_to_file("downloaded_file.txt")

Sur l’API Claude, les fichiers image, vidéo et audio pris en charge que Claude produit avec l’outil d’exécution de code, y compris les fichiers créés par les skills, comportent des Content Credentials C2PA signés lorsque vous les téléchargez. Consultez Content Credentials sur les fichiers générés pour savoir ce que contient l’identifiant et comment le vérifier.

Stockage des fichiers et limites

Limites de stockage

• Taille maximale des fichiers : 500 Mo par fichier
• Stockage total : 1 To par organisation

Cycle de vie des fichiers

• Les fichiers sont limités à l’espace de travail dans lequel ils ont été téléversés. Toute requête dans le même espace de travail peut y faire référence ; n’acceptez jamais d’identifiants de fichiers provenant de sources non fiables (consultez l’avertissement sur l’accès à l’espace de travail).
• Les fichiers ne peuvent pas être modifiés ni renommés après le téléversement. Pour modifier le contenu d’un fichier, téléversez un nouveau fichier et supprimez l’ancien.
• Les fichiers sont conservés jusqu’à ce que vous les supprimiez avec le point de terminaison DELETE /v1/files/{file_id} ou qu’ils atteignent leur expires_at.
• Les fichiers supprimés ne peuvent pas être récupérés.
• Les fichiers deviennent inaccessibles via l’API peu après leur suppression, mais ils peuvent subsister dans les appels actifs à l’API Messages et les utilisations d’outils associées.
• Les fichiers supprimés par les utilisateurs seront supprimés conformément à la politique de conservation des données d’Anthropic.

Expiration des fichiers

Pour qu’un fichier expire automatiquement, incluez un champ de formulaire expires_in_secondsAperçu disponible avec des liens vers la référence de l’API, appuyez sur Tab jusqu’à ce que le focus entre dans la carte, et sur Échap pour revenir. lors de son téléversement. La valeur est un nombre entier de secondes compris entre 3 600 (1 heure) et 7 776 000 (90 jours). L’horodatage expires_atAperçu disponible avec des liens vers la référence de l’API, appuyez sur Tab jusqu’à ce que le focus entre dans la carte, et sur Échap pour revenir. qui en résulte (RFC 3339) apparaît dans chaque réponse de fichier et vaut null pour les fichiers téléversés sans expiration. L’expiration est définie une seule fois lors du téléversement et ne peut pas être modifiée.

Lorsqu’un fichier atteint son expires_at :

• Le téléchargement de son contenu (GET /v1/files/{file_id}/content) renvoie une erreur 404.
• Une requête Messages qui référence le fichier échoue avant l’inférence.
• Ses métadonnées (GET /v1/files/{file_id}) restent lisibles pendant 30 jours au maximum, avec un expires_at situé dans le passé.
• Il continue d’apparaître dans les réponses de listage pendant cette période ; comparez expires_at à l’heure actuelle pour filtrer les fichiers expirés.

La suppression d’un fichier expiré avec DELETE /v1/files/{file_id} supprime immédiatement ses métadonnées au lieu d’attendre l’écoulement de la période de 30 jours.

Journalisation d’audit

Si votre organisation a activé la Compliance API, son Activity Feed (flux d’activité) enregistre les opérations de l’API Files effectuées avec une clé API Claude ou depuis la Claude Console : chaque téléversement (POST /v1/files), téléchargement de contenu (GET /v1/files/{file_id}/content) et suppression (DELETE /v1/files/{file_id}) apparaît sous la forme d’une activité platform_file_uploaded, platform_file_content_downloaded ou platform_file_deleted. Le listage des fichiers et la récupération des métadonnées de fichiers ne sont pas enregistrés. Les opérations qui ont lieu pendant que la Compliance API est désactivée ne sont pas enregistrées et ne peuvent pas être récupérées ultérieurement ; configurez donc la Compliance API avant de vous appuyer sur cette piste d’audit. Sur Claude Platform on AWS, auditez plutôt les opérations sur les fichiers à l’aide des événements de données AWS CloudTrail.

Migrer depuis files-api-2025-04-14

L’API Files n’est plus en bêta et ne nécessite aucun en-tête bêta. La migration depuis files-api-2025-04-14 est facultative : les requêtes qui l’envoient continuent de fonctionner et de renvoyer les formes de réponse bêta, de sorte qu’une intégration existante continue de fonctionner jusqu’à ce que vous la modifiiez. La suppression de l’en-tête fait basculer ces requêtes vers les formes documentées sur cette page :

Pour migrer :

1. Supprimez l’en-tête bêta. Retirez anthropic-beta: files-api-2025-04-14 de vos requêtes. Avec le SDK, appelez client.files au lieu de client.beta.files ; conserver client.beta.files ne fonctionne qu’avec les versions du SDK qui n’envoient plus l’en-tête. Les versions antérieures l’envoient depuis client.beta.files même si vous ne transmettez aucun nom de bêta.
2. Mettez à jour la pagination. Remplacez les boucles after_id/before_id par le curseur page/next_page, ou utilisez les utilitaires de pagination automatique des SDK présentés dans Gérer les fichiers.
3. Lisez expires_at. Le champ n’apparaît que sans l’en-tête ; null signifie que le fichier n’a pas d’expiration (voir Expiration des fichiers).

Espace de noms bêta des SDK

À partir des versions Python SDK 1.2.0, TypeScript SDK 0.122.0, Go SDK 1.68.0, Java SDK 2.59.0, PHP SDK 0.45.0, Ruby SDK 1.67.0 et C# SDK 12.44.0, client.beta.files n’envoie plus files-api-2025-04-14 et renvoie les mêmes formats que client.files, avec des noms de types préfixés par Beta (en PHP, des classes dans l’espace de noms Anthropic\Beta). Il accepte des noms de bêta via betas pour les fonctionnalités Files qui sont en bêta, comme le filtrage par scope_id sous un en-tête bêta Managed Agents. Les versions antérieures du SDK sont typées selon les formats bêta ; si vous dépendez de ces types, restez sur une version antérieure jusqu’à votre migration.

Les requêtes qui portent anthropic-beta: managed-agents-2026-04-01 sans files-api-2025-04-14 reçoivent les formes de cette page avec une facilité de compatibilité sur GET /v1/files : before_id et after_id sont toujours acceptés (non combinables avec page ou ids[]), et la réponse de liste inclut has_more, first_id et last_id en plus de next_page. Les versions bêta ultérieures de Managed Agents reçoivent la forme simple.

Gestion des erreurs

Les erreurs courantes lors de l’utilisation de l’API Files comprennent :

• Fichier introuvable (404) : Le file_id spécifié n’existe pas ou vous n’y avez pas accès.
• Type de fichier non valide (400) : Le type de fichier ne correspond pas au type de bloc de contenu (par exemple, utilisation d’un fichier image dans un bloc document).
• Non téléchargeable (400) : Les fichiers que vous téléversez ont "downloadable": false et ne peuvent pas être téléchargés. Seuls les fichiers créés par les skills ou l’outil d’exécution de code peuvent être téléchargés.
• Dépassement de la taille de la fenêtre de contexte (400) : Le fichier est plus volumineux que la taille de la « context window » (fenêtre de contexte) (par exemple, utilisation d’un fichier texte brut de 500 Mo dans une requête /v1/messages).
• Nom de fichier non valide (400) : Le nom du 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).
• Fichier trop volumineux (413) : Le fichier dépasse la limite de 500 Mo.
• Limite de stockage dépassée (400) : Votre organisation a atteint la limite de stockage de 1 To.

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "File `file_011CNha8iCJcU1wXNR6q4V8w` not found."
  },
  "request_id": "req_011CQFYcrRp7mCHLDsAYT8Qt"
}

Utilisation et facturation

Les opérations de l’API Files sont gratuites :

• Téléversement de fichiers
• Téléchargement de fichiers
• Listage des 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.

Limites de débit

Les appels API liés aux fichiers sont limités à environ 500 requêtes par minute. Pour demander une « rate limit » (limite de débit) plus élevée, contactez l’équipe commerciale.

Prochaines étapes

Disponibilité