Bestanden uploaden met de Files API
Op deze pagina
Van kopiëren en plakken naar native documenten
U heeft waarschijnlijk al eens vijftien pagina’s van een rapport in een prompt geplakt in de hoop dat de lay-out behouden blijft. Dat lukt nooit: kolomindelingen van tabellen raken door de war en het model redeneert uiteindelijk over een brij aan tekst. De Files API van xAI lost dit probleem exact op. U stuurt het oorspronkelijke document, xAI analyseert het server-side, en Grok werkt met inhoud waarbij de structuur, tabellen en sectie-einden behouden blijven.
Het mechanisme past in één enkel endpoint, POST /v1/files. U verzendt uw bestand als multipart/form-data met een parameter purpose ingesteld op "assistants". De API retourneert een unieke identificatiecode, een file_id. Deze identificatiecode wordt de sleutel voor alles wat u daarna doet: het document bevragen, de metadata controleren, het verwijderen of het toevoegen aan een collectie.
Uw eerste upload
Neem een jaarverslag in PDF-formaat dat op uw schijf staat. Het uploadverzoek is geen JSON, maar multipart/form-data. Dit verklaart de syntaxis -F in plaats van -d:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
Het antwoord komt binnen enkele seconden binnen en bevat de bestandsidentificatiecode samen met de kenmerken ervan:
{
"id": "file_abc123xyz",
"object": "file",
"bytes": 2458901,
"created_at": 1710000000,
"filename": "annual-report.pdf",
"purpose": "assistants"
}
Deze file_id—hier file_abc123xyz—is uw permanente referentie naar het document. Noteer deze direct zodra u het antwoord ontvangt: een verloren identificatiecode betekent een verweesd bestand dat quota verbruikt zonder bruikbaar te zijn.
Parameters en authenticatie
Er zijn slechts twee parameters, beide verplicht:
- file: De binaire inhoud van het bestand, verzonden als multipart. De maximale grootte is 48 MB.
- purpose: Altijd
"assistants", de enige waarde die tot nu toe wordt geaccepteerd. Dit geeft aan dat het bestand zal worden gebruikt voor interacties met het model.
U zult de limiet van 48 MB sneller bereiken dan u misschien denkt: een logexport van één dag of volledige productdocumentatie overschrijdt deze regelmatig. Splits in dat geval uw bron op in meerdere coherente bestanden in plaats van willekeurig af te kappen; u vindt ze later allemaal terug in dezelfde collectie.
Wat authenticatie betreft: elk verzoek aan de Files API bevat uw standaard API-sleutel in de header Authorization: Bearer. Houd er rekening mee dat deze sleutel niet de Management API Key is: die is gereserveerd voor collecties, komt later in de cursus aan bod en wordt tijdens eerste pogingen vaak verward met de eerste sleutel.
Het bestand gebruiken
Het geüploade bestand is nutteloos tenzij u ernaar verwijst in een verzoek. Dit is de rol van het blok input_file in de Responses API, dat u vergezelt van een instructie in vrije tekst:
{
"model": "grok-4.5",
"input": [
{
"type": "input_file",
"file_id": "file_abc123xyz"
},
{
"type": "input_text",
"text": "Summarize the key points of this document."
}
]
}
Grok ontvangt het bestand, activeert automatisch de tool attachment_search server-side, haalt relevante passages op en schrijft zijn antwoord op basis daarvan. Geen handmatige activering is nodig en er hoeven geen extra parameters te worden toegevoegd: de aanwezigheid van een input_file volstaat om de hele keten te activeren. Elke oproep met een bijlage wordt gefactureerd tegen $10 per 1.000, waardoor één upload die tien keer wordt bevraagd kosteneffectiever is dan tien uploads van hetzelfde document.
Prijzen per 5 augustus 2026 — prijzen wijzigen regelmatig: controleer voor elke budgetberekening de huidige tarieven op de officiële xAI-pagina voor modellen en prijzen.
Belangrijkste punten
- Het endpoint
POST /v1/filesaccepteert bestanden tot 48 MB inmultipart/form-data - De parameter
purposemoet"assistants"zijn - De geretourneerde
file_idis uw referentie voor alle daaropvolgende bewerkingen - De tool
attachment_searchwordt automatisch geactiveerd wanneer een bestand in een verzoek wordt genoemd - De kosten bedragen $10 per 1.000 oproepen met bijlagen