Prenos datotek z API-jem Files
Na tej strani
Od kopiranja in lepljenja do izvornih dokumentov
Verjetno si že petnajst strani poročila prilepil v poziv z upanjem, da se bo ohranila postavitev. Nikoli se ne: stolpci v tabelah se pomešajo in model na koncu sklepa na podlagi besedilne kaše. API Files podjetja xAI rešuje prav ta problem. Pošlješ izvorni dokument, xAI ga analizira na strani strežnika in Grok dela z vsebino, kjer so ohranjena struktura, tabele in prelomi razdelkov.
Mehanizem se prilega eni sami končni točki, POST /v1/files. Datoteko pošlješ kot multipart/form-data s parametrom purpose, nastavljenim na "assistants", API pa vrne edinstven identifikator, imenovan file_id. Ta identifikator postane ključ za vse, kar narediš naprej: poizvedovanje po dokumentu, preverjanje njegovih metapodatkov, brisanje ali dodajanje v zbirko.
Tvoje prvo nalaganje
Vzemi letno poročilo v formatu PDF, ki čaka na tvojem disku. Zahtevek za nalaganje ni JSON, temveč multipart/form-data, kar pojasnjuje sintakso -F namesto -d:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
Odgovor prispe v nekaj sekundah in vsebuje identifikator datoteke skupaj z njenimi značilnostmi:
{
"id": "file_abc123xyz",
"object": "file",
"bytes": 2458901,
"created_at": 1710000000,
"filename": "annual-report.pdf",
"purpose": "assistants"
}
Ta file_id – tukaj file_abc123xyz – je tvoja stalna referenca na dokument. Zapiši si ga takoj, ko prejmeš odgovor: izgubljen identifikator pomeni osirotelo datoteko, ki porablja kvoto, ne da bi bila uporabna.
Parametri in avtentikacija
Samo dva parametra, oba obvezna:
- file: Binarna vsebina datoteke, poslana kot multipart. Največja velikost je 48 MB
- purpose: Vedno
"assistants", edina doslej sprejeta vrednost. Označuje, da bo datoteka uporabljena za interakcije z modelom
Mejo 48 MB boš dosegel hitreje, kot morda pričakuješ: izvoz dnevnika za en dan ali popolna dokumentacija izdelka jo redno presežeta. V tem primeru razdeli svoj vir na več koherentnih datotek namesto poljubnega obrezovanja – kasneje jih boš našel vse v isti zbirki.
Kar zadeva avtentikacijo, vsak zahtevek do API-ja Files nosi tvoj standardni ključ API v glavi Authorization: Bearer. Takoj imej v mislih, da ta ključ ni ključ Management API: ta, rezerviran za zbirke, pride kasneje v tečaju in ga med prvimi poskusi pogosto zamenjamo s prvim.
Uporaba datoteke
Naložena datoteka je neuporabna, razen če se nanjo sklicuješ v zahtevku. To je vloga bloka input_file v API-ju Responses, ki ga spremlja navodilo v prostem besedilu:
{
"model": "grok-4.5",
"input": [
{
"type": "input_file",
"file_id": "file_abc123xyz"
},
{
"type": "input_text",
"text": "Povzemi ključne točke tega dokumenta."
}
]
}
Grok prejme datoteko, samodejno aktivira orodje attachment_search na strani strežnika, izvleče ustrezne odlomke in na njihovi podlagi napiše svoj odgovor. Ročna aktivacija ni potrebna in ni treba dodajati dodatnih parametrov: prisotnost input_file zadostuje za sprožitev celotnega veriga. Vsak klic priloge se zaračuna po 10 $ na 1.000, zaradi česar je eno nalaganje, po katerem se desetkrat poizveduje, stroškovno učinkovitejše od desetih nalaganj istega dokumenta.
Cene z dne 5. avgusta 2026 – cene se redno spreminjajo: pred vsakim izračunom proračuna preveri trenutni cenik na uradni strani modelov in cen xAI.
Ključne ugotovitve
- Končna točka
POST /v1/filessprejme datoteke do 48 MB v formatumultipart/form-data - Parameter
purposemora biti"assistants" - Vrnjeni
file_idje tvoja referenca za vse nadaljnje operacije - Orodje
attachment_searchse samodejno aktivira, ko je datoteka navedena v zahtevku - Strošek znaša 10 $ na 1.000 klicev priloge