API Files

L'API Files vous permet de téléverser et de gérer des fichiers à utiliser avec l'API Claude sans avoir à retéléverser 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 également utiliser l'API Files pour éviter d'avoir à retéléverser continuellement des documents et des images fréquemment utilisés lors de multiples appels d'API. 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 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 la prise en charge par modèle.

L'API Files est disponible sur l'API Claude, Claude Platform sur AWS et Microsoft Foundry. Elle n'est actuellement pas disponible sur Amazon Bedrock ni sur Vertex AI.



Fonctionnement de l'API Files

L'API Files offre une approche simple de type « 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 à partir de compétences ou de 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 retéléverser le contenu
• Gérez vos fichiers avec des opérations de listage, 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.beta.files.upload(
    file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
)

La réponse au téléversement d'un fichier inclura :

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



Utiliser un fichier dans des messages

Une fois téléversé, référencez le fichier en utilisant son file_id :

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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

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



Travailler avec d'autres formats de fichiers

Pour les types de fichiers qui ne sont pas pris en charge en tant que blocs document (.csv, .txt, .md, .docx, .xlsx), convertissez les fichiers en texte brut et incluez le contenu directement dans votre message :

import pandas as pd
# ...
# Exemple : lecture d'un fichier CSV
df = pd.read_csv("data.csv")
csv_content = df.to_string()

# Envoyer en tant que texte brut dans le message
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": f"Here's the CSV data:\n\n{csv_content}\n\nPlease analyze this data.",
                }
            ],
        }
    ],
)

print(response.content[0].text)



Blocs de 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 d'image

Pour les images, utilisez le bloc de contenu image :

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



Gérer les fichiers



Lister les fichiers

Récupérez une liste de vos fichiers téléversés :

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



Obtenir les métadonnées d'un fichier

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

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



Supprimer un fichier

Supprimez un fichier de votre espace de travail :

result = client.beta.files.delete(file_id)



Télécharger un fichier

Téléchargez des fichiers qui ont été créés par des compétences ou par l'outil d'exécution de code :

file_content = client.beta.files.download(file_id)

# Save to file
file_content.write_to_file("downloaded_file.txt")



Stockage de 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. 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 deviennent inaccessibles via l'API peu de temps après leur suppression, mais ils peuvent persister dans les appels d'API Messages actifs 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.



Conservation des données

Les fichiers téléversés via l'API Files sont conservés jusqu'à leur suppression explicite à l'aide du point de terminaison DELETE /v1/files/{file_id}. Les fichiers sont stockés pour être réutilisés dans plusieurs requêtes d'API.

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 l'API Files incluent :

• 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, utiliser un fichier image dans un bloc de document)
• Dépassement de 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 non valide (400) : Le nom de fichier ne respecte pas les exigences de longueur (1 à 255 caractères) ou contient des caractères interdits (<, >, :, ", |, ?, *, \, /, ou des caractères Unicode 0 à 31)
• Fichier trop volumineux (413) : Le fichier dépasse la limite de 500 Mo
• Limite de stockage dépassée (403) : Votre organisation a atteint la limite de stockage de 500 Go

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "File not found: file_011CNha8iCJcU1wXNR6q4V8w"
  }
}



Utilisation et facturation

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

• Téléversement de fichiers
• Téléchargement de fichiers
• Listage de 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 jetons d'entrée. Vous pouvez uniquement télécharger des fichiers créés par des compétences ou par l'outil d'exécution de code.



Limites de débit

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