input_file und attachment_search in der Responses API
Auf dieser Seite
Zwei Wege zum selben Block
Die Grok Responses API akzeptiert ein Dokument auf zwei Arten: über file_id, was ein zuvor hochgeladenes File bedeutet, oder über file_url, eine öffentliche Adresse, die xAI zum Zeitpunkt der Anfrage abruft. Der Block verwendet in beiden Fällen denselben Namen, input_file, und die nachgelagerte Verarbeitung ist identisch: Grok aktiviert das Tool attachment_search und extrahiert die Passagen, die Ihre Frage beantworten. Was sich ändert, ist der Lebenszyklus des Dokuments, seine Vertraulichkeit und die Kosten jeder wiederholten Anfrage.
Der Weg über file_id
Sobald Sie das File über POST /v1/files gesendet haben, beziehen Sie sich auf seine Kennung, zusammen mit Ihrer Frage als reinen Text:
{
"model": "grok-4.5",
"input": [
{
"type": "input_file",
"file_id": "file_abc123"
},
{
"type": "input_text",
"text": "Welche Hauptrisiken werden in diesem Bericht erwähnt?"
}
]
}
Dieser Weg macht sich in drei Situationen Sinn. Erstens bei wiederholten Abfragen: Wenn Ihre Rechtsabteilung fünfzehn aufeinanderfolgende Fragen zum selben Vertrag stellt, ist ein einziger Upload gefolgt von fünfzehn Referenzen effizienter als fünfzehn Übertragungen desselben PDFs. Zweitens bei Vertraulichkeit, wenn das Dokument nicht hinter einer URL offengelegt werden darf, auf die jeder mit dem Link zugreifen kann. Drittens Ihre Anwendungsarchitektur: Wenn Files während der nächtlichen Ingestion vorab hochgeladen werden, behandeln Ihre Anfragen lediglich Kennungen.
Der Weg über file_url
Wenn das Dokument bereits irgendwo veröffentlicht ist, wird der Upload zu einem unnötigen Schritt, und Sie können direkt auf die Adresse verweisen:
{
"model": "grok-4.5",
"input": [
{
"type": "input_file",
"file_url": "https://exemple.com/specifications-api.pdf"
},
{
"type": "input_text",
"text": "Fassen Sie die Endpunkte zusammen, die in dieser Dokumentation beschrieben sind."
}
]
}
Typische Anwendungsfälle umfassen offene Dokumentation, die Sie aus keinem Grund speichern müssen, ein File, das auf Ihrer eigenen Infrastruktur hinter einer temporären URL gehostet wird, oder ein schneller Test, bei dem Sie eine Hypothese überprüfen wollen, ohne eine gesamte Upload-Pipeline einzurichten.
Drei Einschränkungen gehen mit dieser Bequemlichkeit einher, und alle kosten Sie in der Produktion. Die URL muss wirklich öffentlich sein, ohne Authentifizierung: Eine Adresse, die durch einen Token oder ein Cookie geschützt ist, führt xAI zu einer Fehlerseite, die das Modell sorgfältig analysiert anstatt Ihres Dokuments. Der Download erhöht die Verarbeitungszeit der Anfrage, wodurch große PDFs deutlich langsamer sind als bei file_id. Schließlich gibt es auf der Seite von xAI keinen Cache: Jede Anfrage lädt das File erneut herunter, sodass ein einzelnes Dokument, das fünfmal am Tag abgefragt wird, fünfmal über das Netzwerk übertragen wird.
Was attachment_search tut
Sobald ein input_file in Ihrer Anfrage erscheint, löst Grok attachment_search aus, ohne dass Sie dies konfigurieren müssen. Die Verarbeitung erfolgt in vier Schritten:
- Inhaltsextraktion aus dem File: Text, Tabellen, Struktur
- Vorläufige Indizierung dieses Inhalts, für die Dauer der Anfrage
- Suche nach relevanten Passagen basierend auf Ihrer Frage
- Einspritzung von Auszügen in den Modell-Kontext
Konzentrieren Sie sich auf das Adjektiv „vorläufig” im zweiten Schritt, denn es erklärt einen Kostendifferenzpunkt, den viele zu spät entdecken: Die Indizierung wird bei jeder Anfrage neu erstellt und verschwindet danach. Genau dieses Problem lösen Collections mit einer persistenten Indizierung. Beachten Sie auch, dass das Modell die Passagen zitiert, die es tatsächlich in seiner Antwort verwendet hat, sodass Sie seine Arbeit überprüfen können, anstatt seinem Wort zu glauben.
Kombination mehrerer Dokumente
Es gibt nichts, was Sie zwingt, sich auf ein File pro Anfrage festzulegen. Durch das Stapeln mehrerer input_file-Blöcke bitten Sie das Modell, über den Satz hinweg zu schlüsseln:
{
"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": "Vergleichen Sie die Ergebnisse von Q1 und Q2."
}
]
}
Grok analysiert beide Dokumente und verknüpft Informationen, um zu antworten, was die Tür für quartalsweise Vergleiche, Überprüfungen aufeinanderfolgender Vertragsversionen oder Konfrontationen zwischen einer Spezifikation und ihrer Implementierung öffnet.
Wahl zwischen den beiden
| Kriterium | file_id | file_url |
|---|---|---|
| Vorheriger Upload | Ja | Nein |
| Vertrauliches File | Empfohlen | Abgeraten |
| Wiederholte Abfragen | Performant (1 Upload) | Langsam (Neu-Download) |
| Öffentliches File | Möglich | Ideal |
| Lebenszyklus-Management | Sie kontrollieren | Abhängig vom Host |
Kernaussagen
input_filemitfile_idverweist auf ein hochgeladenes File,file_urlauf ein öffentliches Dokument- Das Tool
attachment_searchaktiviert sich automatisch, um relevanten Inhalt zu extrahieren - Sie können mehrere Files in einer einzigen Anfrage kombinieren
- Bevorzugen Sie
file_idfür vertrauliche oder häufig abgefragte Files - Bevorzugen Sie
file_urlfür öffentliche Dokumente oder schnelle Tests