Učitavanje datoteka putem Files API-ja
Na ovoj stranici
Od kopiranja i lijepljenja do izvornih dokumenata
Vjerojatno si već kopirao petnaest stranica izvješća u upit nadajući se da će se raspored zadržati. To se nikad ne dogodi: stupci tablica se pomiješaju, a model na kraju rezonira nad tekstualnom kašom. xAI-jev Files API rješava upravo taj problem. Šalješ izvorni dokument, xAI ga analizira na strani poslužitelja, a Grok radi sa sadržajem u kojem su očuvani struktura, tablice i prijelomi sekcija.
Mehanizam se uklapa u jednu krajnju točku, POST /v1/files. Datoteku šalješ kao multipart/form-data s parametrom purpose postavljenim na "assistants", a API vraća jedinstveni identifikator zvan file_id. Taj identifikator postaje ključ za sve što radiš dalje: upite dokumentu, provjeru metapodataka, brisanje ili dodavanje u kolekciju.
Tvoje prvo učitavanje
Uzmi godišnje izvješće u PDF formatu koje ti stoji na disku. Zahtjev za učitavanje nije JSON već multipart/form-data, što objašnjava sintaksu -F umjesto -d:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
Odgovor stiže za nekoliko sekundi i sadrži identifikator datoteke zajedno s njezinim karakteristikama:
{
"id": "file_abc123xyz",
"object": "file",
"bytes": 2458901,
"created_at": 1710000000,
"filename": "annual-report.pdf",
"purpose": "assistants"
}
Ovaj file_id—ovdje file_abc123xyz—tvoja je trajna referenca na dokument. Zapiši ga čim primiš odgovor: izgubljeni identifikator znači napuštenu datoteku koja troši kvotu, a da je ne možeš koristiti.
Parametri i autentifikacija
Samo dva parametra, oba obavezna:
- file: Binarni sadržaj datoteke, poslan kao multipart. Maksimalna veličina je 48 MB
- purpose: Uvijek
"assistants", jedina vrijednost prihvaćena do danas. Označava da će se datoteka koristiti za interakcije s modelom
Brže ćeš naići na ograničenje od 48 MB nego što misliš: izvoz logova za jedan dan ili cjelovita dokumentacija proizvoda redovito ga premašuju. U tom slučaju, podijeli izvor na nekoliko koherentnih datoteka umjesto da arbitrarno skraćuješ—kasnije ćeš ih sve pronaći u istoj kolekciji.
Što se tiče autentifikacije, svaki zahtjev Files API-ju nosi tvoj standardni API ključ u zaglavlju Authorization: Bearer. Imaj na umu odmah da ovaj ključ nije Management API Key: onaj je rezerviran za kolekcije, dolazi kasnije u tečaju i često se miješa s prvim tijekom početnih pokušaja.
Korištenje datoteke
Učitana datoteka je beskorisna ako je ne referenciraš u zahtjevu. To je uloga bloka input_file u Responses API-ju, koji pratiš uputom u slobodnom tekstu:
{
"model": "grok-4.5",
"input": [
{
"type": "input_file",
"file_id": "file_abc123xyz"
},
{
"type": "input_text",
"text": "Sažmi ključne točke ovog dokumenta."
}
]
}
Grok prima datoteku, automatski aktivira alat attachment_search na strani poslužitelja, izvlači relevantne odlomke i na temelju njih piše svoj odgovor. Nije potrebna ručna aktivacija niti dodavanje dodatnih parametara: prisutnost input_file dovoljna je za pokretanje cijelog lanca. Svaki poziv s privitkom naplaćuje se po $10 na 1.000 poziva, što jedno učitavanje upitno deset puta čini isplativijim od deset učitavanja istog dokumenta.
Cjenik od 5. kolovoza 2026. — cijene se redovito mijenjaju: prije bilo kakvog izračuna proračuna, provjeri trenutnu tarifu na službenoj stranici xAI modela i cjenika.
Ključne točke
- Krajnja točka
POST /v1/filesprihvaća datoteke do 48 MB u formatumultipart/form-data - Parametar
purposemora biti"assistants" - Vraćeni
file_idtvoja je referenca za sve naknadne operacije - Alat
attachment_searchaktivira se automatski kada se datoteka referencira u zahtjevu - Trošak iznosi $10 po 1.000 poziva s privitkom