API Files
L’API Files vous permet de télécharger et de gérer des fichiers à utiliser avec l’API Anthropic sans avoir à re-télécharger 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 également utiliser l’API Files pour éviter d’avoir à continuellement re-télécharger des documents et images fréquemment utilisés à travers plusieurs appels d’API.
L’API Files est actuellement en version bêta. Veuillez nous contacter via notre formulaire de commentaires pour partager votre expérience avec l’API Files.
Modèles pris en charge
Référencer un file_id
dans une requête Messages est pris en charge dans tous les modèles qui supportent 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 3.5 Haiku plus tous les modèles Claude 3.7+.
L’API Files n’est actuellement pas prise en charge sur Amazon Bedrock ou Google Vertex AI.
Comment fonctionne l’API Files
L’API Files fournit une approche simple de création unique et d’utilisation multiple pour travailler avec des fichiers :
- Télécharger des fichiers vers notre stockage sécurisé et recevoir un
file_id
unique - Télécharger des fichiers qui sont créés à partir de 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écharger le contenu - Gérer vos fichiers avec les opérations de liste, récupération et suppression
Comment utiliser l’API Files
Pour utiliser l’API Files, vous devrez inclure l’en-tête de fonctionnalité bêta : anthropic-beta: files-api-2025-04-14
.
Télécharger un fichier
Téléchargez un fichier pour qu’il soit référencé dans de futurs appels d’API :
Utiliser un fichier dans les messages
Une fois téléchargé, référencez le fichier en utilisant son file_id
:
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 :
Type de Fichier | Type MIME | Type de Bloc de Contenu | Cas d’Usage |
---|---|---|---|
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 | Varie | container_upload | Analyser des données, créer des visualisations |
Travailler avec d’autres formats de fichiers
Pour les types de fichiers qui ne sont pas pris en charge comme 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 PDF pour tirer parti de l’analyse d’images intégrée. Cela permet d’utiliser des citations du document PDF.
Blocs de documents
Pour les PDFs et fichiers texte, utilisez le bloc de contenu document
:
Blocs d’images
Pour les images, utilisez le bloc de contenu image
:
Gérer les fichiers
Lister les fichiers
Récupérez une liste de vos fichiers téléchargé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 l’outil d’exécution de code :
Vous ne pouvez télécharger que les fichiers qui ont été créés par l’outil d’exécution de code. Les fichiers que vous avez téléchargés ne peuvent pas être téléchargés.
Stockage de fichiers et limites
Limites de stockage
- Taille maximale de fichier : 500 MB par fichier
- Stockage total : 100 GB 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 toute 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 la suppression, mais ils peuvent persister dans les appels d’API
Messages
actifs et les utilisations d’outils associées
Gestion des erreurs
Les erreurs courantes lors de l’utilisation de l’API Files incluent :
- Fichier non trouvé (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)
- 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 MB 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 caractères unicode 0-31) - Fichier trop volumineux (413) : Le fichier dépasse la limite de 500 MB
- Limite de stockage dépassée (403) : Votre organisation a atteint la limite de stockage de 100 GB
Utilisation et facturation
Les opérations de l’API Files sont gratuites :
- Télécharger des fichiers
- Télécharger des fichiers
- Lister les fichiers
- Obtenir les métadonnées des fichiers
- Supprimer des fichiers
Le contenu des fichiers utilisé dans les requêtes Messages
est facturé comme des jetons d’entrée. Vous ne pouvez télécharger que les fichiers créés par l’outil d’exécution de code.
Limites de taux
Pendant la période bêta :
- Les appels d’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