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 le contenu à chaque requête. Ceci 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) puis télécharger des sorties (par exemple, des graphiques). Vous pouvez explorer directement la référence de l'API, en complément de ce guide.



Modèles pris en charge

Le référencement d'un file_id dans une requête Messages est pris en charge sur tous les modèles qui prennent en charge le type de fichier donné. 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 la prise en charge des modèles.

La Files API est disponible sur l'API Claude, Claude Platform sur AWS et Microsoft Foundry. Sur Microsoft Foundry, la Files API nécessite un déploiement Hosted on Anthropic. Elle n'est actuellement pas disponible sur Amazon Bedrock ou Google Cloud.



Comment fonctionne la Files API

La Files API offre 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 Messages en utilisant le file_id au lieu de re-téléverser le contenu
• Gérez vos fichiers avec les opérations de liste, de récupération et de suppression



Comment utiliser la Files API



Téléverser un fichier

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

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

La réponse du téléversement d'un fichier inclut :

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

downloadable est 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.



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.beta.messages.create(
    model="claude-opus-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,
                    },
                },
            ],
        }
    ],
    betas=["files-api-2025-04-14"],
)
print(response)



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 :



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 soit être lus de cette manière, soit être téléversés via la Files API avec un type de contenu text/plain explicite. Pour analyser des jeux de données au lieu de les lire comme du texte, téléversez-les pour l'outil d'exécution de code en utilisant un bloc container_upload.

Les exemples suivants lisent un fichier texte et envoient son contenu en 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",
    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 une liste de vos fichiers téléversés. Le point de terminaison est paginé : chaque requête renvoie jusqu'à limit fichiers (20 par défaut), et les paramètres before_id et after_id récupèrent la page adjacente. Consultez la référence de l'API List Files. Les SDK renvoient la première page et fournissent des assistants de pagination automatique. L'exemple CLI limite le total avec --max-items :

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



Obtenir les métadonnées d'un fichier

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

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



Supprimer un fichier

Supprimez un fichier de votre espace de travail :

client.beta.files.delete(file_id)



Télécharger un fichier

Téléchargez les fichiers qui ont été 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.beta.files.download(file_id)

file_content.write_to_file("downloaded_file.txt")



Stockage des 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 qui les a téléversés. Toute clé API du même espace de travail peut les référencer
• Les fichiers ne peuvent pas être modifiés ou 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 persistent jusqu'à ce que vous les supprimiez avec le point de terminaison DELETE /v1/files/{file_id}
• 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 persister dans les appels actifs à l'API Messages 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. Pour l'éligibilité ZDR sur l'ensemble des 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 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é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 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 500 Go

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



Utilisation et facturation

Les opérations de la Files API sont gratuites :

• Téléverser des fichiers
• Télécharger des fichiers
• Lister les fichiers
• Obtenir les métadonnées d'un fichier
• Supprimer des fichiers

Le contenu des fichiers utilisé dans les requêtes Messages est facturé en tant que tokens d'entrée.



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'usage



Prochaines étapes