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.

​

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

​

Télécharger un fichier

Téléchargez un fichier pour qu’il soit référencé dans de futurs appels d’API :

curl -X POST https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -F "file=@/path/to/document.pdf"

​

Utiliser un fichier dans les messages

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

curl -X POST https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Veuillez résumer ce document pour moi."          
          },
          {
            "type": "document",
            "source": {
              "type": "file",
              "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
            }
          }
        ]
      }
    ]
  }'

​

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 comme blocs document (.csv, .txt, .md, .docx, .xlsx), convertissez les fichiers en texte brut, et incluez le contenu directement dans votre message :

# Exemple : Lire un fichier texte et l'envoyer comme texte brut
# Note : Pour les fichiers avec des caractères spéciaux, considérez l'encodage base64
TEXT_CONTENT=$(cat document.txt | jq -Rs .)

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d @- <<EOF
{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Voici le contenu du document :\n\n${TEXT_CONTENT}\n\nVeuillez résumer ce document."
        }
      ]
    }
  ]
}
EOF

​

Blocs de documents

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

{
  "type": "document",
  "source": {
    "type": "file",
    "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
  },
  "title": "Titre du Document", // Optionnel
  "context": "Contexte sur le document", // Optionnel  
  "citations": {"enabled": true} // Optionnel, active les citations
}

​

Blocs d’images

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échargés :

curl https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

​

Obtenir les métadonnées d’un fichier

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

curl https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

​

Supprimer un fichier

Supprimez un fichier de votre espace de travail :

curl -X DELETE https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

​

Télécharger un fichier

Téléchargez des fichiers qui ont été créés par l’outil d’exécution de code :

curl -X GET "https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w/content" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  --output downloaded_file.txt

​

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

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Fichier non trouvé : file_011CNha8iCJcU1wXNR6q4V8w"
  }
}

​

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