Uploader des fichiers avec la Files API

Du copier-coller au document natif

Vous avez probablement déjà collé quinze pages de rapport dans un prompt en espérant que la mise en page survive. Elle ne survit jamais : les colonnes des tableaux se mélangent et le modèle finit par raisonner sur une bouillie de texte. La Files API de xAI répond précisément à ce problème. Vous transmettez le document d’origine, xAI l’analyse côté serveur, et Grok travaille sur un contenu dont la structure, les tableaux et le découpage en sections sont préservés.

Le mécanisme tient dans un seul endpoint, POST /v1/files. Vous envoyez votre fichier en multipart/form-data avec un paramètre purpose fixé à "assistants", et l’API vous rend un identifiant unique appelé file_id. Cet identifiant devient ensuite la clé de tout ce que vous ferez : interroger le document, consulter ses métadonnées, le supprimer ou l’intégrer à une collection.

Votre premier upload

Prenez un rapport annuel au format PDF, posé sur votre disque. La requête d’upload n’est pas du JSON mais du multipart/form-data, ce qui explique la syntaxe en -F plutôt qu’en -d :

curl -X POST https://api.x.ai/v1/files \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -F "[email protected]" \
  -F "purpose=assistants"

La réponse arrive en quelques instants et contient l’identifiant du fichier ainsi que ses caractéristiques :

{
  "id": "file_abc123xyz",
  "object": "file",
  "bytes": 2458901,
  "created_at": 1710000000,
  "filename": "rapport-annuel.pdf",
  "purpose": "assistants"
}

Ce file_id — ici file_abc123xyz — est votre référence permanente vers le document. Notez-le dès la réponse reçue : un identifiant perdu signifie un fichier orphelin, qui consomme du quota sans être exploitable.

Paramètres et authentification

Deux paramètres seulement, tous deux obligatoires :

• file : le contenu binaire du fichier, envoyé en multipart. La taille maximale est de 48 MB
• purpose : toujours "assistants", seule valeur acceptée à ce jour. Elle indique que le fichier servira dans le cadre des interactions avec le modèle

Le plafond de 48 MB se rencontre plus vite qu’on ne l’imagine : un export de logs d’une journée ou une documentation produit complète le dépassent régulièrement. Dans ce cas, découpez votre source en plusieurs fichiers cohérents plutôt que de tronquer arbitrairement — vous les retrouverez tous dans une même collection plus tard.

Côté authentification, chaque requête vers la Files API porte votre clé API standard dans le header Authorization: Bearer. Retenez dès maintenant que cette clé n’est pas la Management API Key : celle-ci, réservée aux collections, viendra plus tard dans le parcours et se confond fréquemment avec la première lors des premiers essais.

Faire parler le fichier

Le fichier uploadé ne sert à rien tant que vous ne le référencez pas dans une requête. C’est le rôle du bloc input_file de l’API Responses, que vous accompagnez d’une consigne en texte libre :

{
  "model": "grok-4.5",
  "input": [
    {
      "type": "input_file",
      "file_id": "file_abc123xyz"
    },
    {
      "type": "input_text",
      "text": "Resume les points clés de ce document."
    }
  ]
}

Grok reçoit le fichier, active de lui-même l’outil attachment_search côté serveur, en extrait les passages pertinents et rédige sa réponse à partir de ceux-ci. Aucune activation manuelle n’est nécessaire, et aucun paramètre supplémentaire n’est à ajouter : la présence d’un input_file suffit à déclencher toute la chaîne. Chaque appel d’attachement est facturé sur la base de $10 par tranche de 1 000, ce qui rend rentable un upload unique interrogé dix fois plutôt que dix envois du même document.

Tarifs relevés le 5 août 2026 — les prix évoluent régulièrement : avant tout calcul de budget, vérifiez la grille en vigueur sur la page officielle des modèles et tarifs xAI.

Points clés à retenir

• L’endpoint POST /v1/files accepte des fichiers jusqu’à 48 MB en multipart/form-data
• Le paramètre purpose doit être "assistants"
• Le file_id retourné est votre référence pour toutes les opérations ultérieures
• L’outil attachment_search s’active automatiquement quand un fichier est référencé dans une requête
• Le coût est de $10 par 1 000 appels d’attachement