Dateien mit der Files API hochladen
Auf dieser Seite
Vom Kopieren und Einfügen zu nativen Dokumenten
Sie haben wahrscheinlich bereits versucht, fünfzehn Seiten eines Berichts in einen Prompt einzufügen, in der Hoffnung, dass das Layout erhalten bleibt. Das funktioniert nie: Spalten in Tabellen vermischen sich, und das Modell schlussfolgert auf einem Textbrei. Die Files API von xAI löst genau dieses Problem. Sie senden das Originaldokument, xAI analysiert es serverseitig, und Grok arbeitet mit Inhalten, bei denen Struktur, Tabellen und Abschnittsunterbrechungen erhalten bleiben.
Der Mechanismus passt in einen einzigen Endpunkt, POST /v1/files. Sie senden Ihre Datei als multipart/form-data mit einem purpose-Parameter, der auf "assistants" gesetzt ist, und die API gibt eine eindeutige Kennung namens file_id zurück. Diese Kennung wird zum Schlüssel für alles, was Sie danach tun: Abfragen des Dokuments, Überprüfung seiner Metadaten, Löschen oder Hinzufügen zu einer Sammlung.
Ihr erster Upload
Nehmen Sie einen Jahresbericht im PDF-Format, der auf Ihrem Laufwerk liegt. Die Upload-Anfrage ist kein JSON, sondern multipart/form-data, was die Syntax mit -F statt -d erklärt:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
Die Antwort kommt in wenigen Sekunden an und enthält die Dateikennung sowie deren Eigenschaften:
{
"id": "file_abc123xyz",
"object": "file",
"bytes": 2458901,
"created_at": 1710000000,
"filename": "annual-report.pdf",
"purpose": "assistants"
}
Diese file_id – hier file_abc123xyz – ist Ihre dauerhafte Referenz für das Dokument. Notieren Sie sich diese Kennung sofort, sobald Sie die Antwort erhalten: Eine verlorene Kennung bedeutet eine verwaisende Datei, die Kontingent verbraucht, ohne nutzbar zu sein.
Parameter und Authentifizierung
Nur zwei Parameter, beide erforderlich:
- file: Der binäre Inhalt der Datei, gesendet als multipart. Maximale Größe beträgt 48 MB.
- purpose: Immer
"assistants", der bisher einzige akzeptierte Wert. Er gibt an, dass die Datei für Modellinteraktionen verwendet wird.
Sie werden die 48-MB-Grenze schneller erreichen, als Sie vielleicht erwarten: Ein Log-Export für einen Tag oder eine vollständige Produktdokumentation überschreiten diese regelmäßig. In diesem Fall teilen Sie Ihre Quelle in mehrere kohärente Dateien auf, anstatt sie willkürlich zu kürzen – Sie finden sie später alle in derselben Sammlung.
Auf der Authentifizierungsseite trägt jede Anfrage an die Files API Ihren Standard-API-Schlüssel im Header Authorization: Bearer. Halten Sie fest, dass dieser Schlüssel derzeit nicht der Management-API-Schlüssel ist: Dieser, der für Sammlungen reserviert ist, kommt später im Kurs und wird bei ersten Versuchen häufig mit dem ersten verwechselt.
Verwendung der Datei
Die hochgeladene Datei ist nutzlos, wenn Sie sie nicht in einer Anfrage referenzieren. Dies ist die Rolle des input_file-Blocks in der Responses API, den Sie mit einer freien Textanweisung begleiten:
{
"model": "grok-4.5",
"input": [
{
"type": "input_file",
"file_id": "file_abc123xyz"
},
{
"type": "input_text",
"text": "Fassen Sie die wichtigsten Punkte dieses Dokuments zusammen."
}
]
}
Grok erhält die Datei, aktiviert das Tool attachment_search automatisch serverseitig, extrahiert relevante Passagen und schreibt seine Antwort darauf basierend. Eine manuelle Aktivierung ist nicht erforderlich, und es müssen keine zusätzlichen Parameter hinzugefügt werden: Das Vorhandensein eines input_file reicht aus, um die gesamte Kette auszulösen. Jeder Aufruf einer Anhangfunktion wird mit $10 pro 1.000 berechnet, wodurch eine einzelne hochgeladene Datei, die zehnmal abgefragt wird, kosteneffizienter ist als zehn Uploads desselben Dokuments.
Preise Stand 5. August 2026 — Preise ändern sich regelmäßig: Bevor Sie eine Budgetberechnung durchführen, prüfen Sie das aktuelle Raster auf der offiziellen Seite für xAI-Modelle und Preise.
Kernaussagen
- Der Endpunkt
POST /v1/filesakzeptiert Dateien bis zu 48 MB inmultipart/form-data - Der Parameter
purposemuss"assistants"sein - Die zurückgegebene
file_idist Ihre Referenz für alle nachfolgenden Operationen - Das Tool
attachment_searchwird automatisch aktiviert, wenn eine Datei in einer Anfrage referenziert wird - Die Kosten betragen $10 pro 1.000 Anhangaufrufe