input_file et attachment_search dans l'API Responses

Deux chemins vers le même bloc

L’API Responses de Grok accepte un document de deux façons : par file_id, c’est-à-dire un fichier que vous avez préalablement uploadé, ou par file_url, une adresse publique que xAI ira chercher au moment de la requête. Le bloc utilisé porte le même nom dans les deux cas, input_file, et le traitement en aval est identique : Grok active l’outil attachment_search et extrait les passages qui répondent à votre question. Ce qui change, c’est le cycle de vie du document, sa confidentialité et le coût de chaque appel répété.

Le chemin file_id

Une fois le fichier envoyé par POST /v1/files, vous le désignez par son identifiant, accompagné de votre question en texte libre :

{
  "model": "grok-4.5",
  "input": [
    {
      "type": "input_file",
      "file_id": "file_abc123"
    },
    {
      "type": "input_text",
      "text": "Quels sont les principaux risques mentionnés dans ce rapport ?"
    }
  ]
}

Cette voie s’impose dans trois situations. La première est l’interrogation répétée : si votre équipe juridique pose quinze questions successives au même contrat, un upload unique suivi de quinze références vaut mieux que quinze transferts du même PDF. La deuxième est la confidentialité, dès lors que le document ne doit pas être exposé derrière une URL accessible à quiconque possède le lien. La troisième est l’architecture de votre application : si les fichiers sont pré-uploadés lors d’une ingestion nocturne, vos requêtes ne manipulent plus que des identifiants.

Le chemin file_url

Quand le document est déjà publié quelque part, l’upload devient une étape inutile et vous pouvez pointer directement l’adresse :

{
  "model": "grok-4.5",
  "input": [
    {
      "type": "input_file",
      "file_url": "https://exemple.com/specifications-api.pdf"
    },
    {
      "type": "input_text",
      "text": "Resume les endpoints décrits dans cette documentation."
    }
  ]
}

L’usage typique est celui de la documentation ouverte que vous n’avez aucune raison de stocker, du fichier hébergé sur votre propre infrastructure derrière une URL temporaire, ou du test rapide où l’on veut vérifier une hypothèse sans monter tout un pipeline d’upload.

Trois limites accompagnent ce confort, et elles se paient toutes en production. L’URL doit être réellement publique, sans authentification : une adresse protégée par un jeton ou un cookie renverra à xAI une page d’erreur, que le modèle analysera consciencieusement à la place de votre document. Le téléchargement s’ajoute au temps de traitement de la requête, ce qui rend les gros PDF sensiblement plus lents qu’en file_id. Enfin, il n’existe pas de cache côté xAI : chaque appel retélécharge le fichier, si bien qu’un même document interrogé cinquante fois par jour traverse le réseau cinquante fois.

Ce que fait attachment_search

Dès qu’un input_file figure dans votre requête, Grok déclenche attachment_search sans que vous ayez rien à configurer. Le traitement se déroule en quatre temps :

1. Extraction du contenu du fichier : texte, tableaux, structure
2. Indexation temporaire de ce contenu, pour la durée de la requête
3. Recherche des passages pertinents au regard de votre question
4. Injection des extraits dans le contexte du modèle

Arrêtez-vous sur l’adjectif « temporaire » de la deuxième étape, car il explique une différence de coût que beaucoup découvrent tard : l’index est reconstruit à chaque appel et disparaît ensuite. C’est précisément le problème que les collections viendront résoudre avec une indexation persistante. Notez enfin que le modèle cite dans sa réponse les passages qu’il a effectivement utilisés, ce qui vous permet de vérifier son travail plutôt que de le croire sur parole.

Croiser plusieurs documents

Rien n’oblige à s’en tenir à un fichier par requête. En empilant plusieurs blocs input_file, vous demandez au modèle de raisonner sur l’ensemble :

{
  "model": "grok-4.5",
  "input": [
    {
      "type": "input_file",
      "file_id": "file_rapport_q1"
    },
    {
      "type": "input_file",
      "file_id": "file_rapport_q2"
    },
    {
      "type": "input_text",
      "text": "Compare les résultats du Q1 et du Q2."
    }
  ]
}

Grok analyse les deux documents et croise les informations pour répondre, ce qui ouvre la porte aux comparaisons trimestrielles, aux relectures de versions successives d’un contrat ou aux confrontations entre une spécification et son implémentation.

Arbitrer entre les deux

Points clés à retenir

• input_file avec file_id référence un fichier uploadé, file_url un document public
• L’outil attachment_search s’active automatiquement pour extraire le contenu pertinent
• Vous pouvez combiner plusieurs fichiers dans une même requête
• Privilégiez file_id pour les fichiers confidentiels ou interrogés fréquemment
• Privilégiez file_url pour les documents publics ou les tests rapides