Failide üleslaadimine Files API kaudu
Sellel lehel
Kopeerimisest ja kleepimisest päris dokumentideni
Oled ilmselt kleepinud viisteist lehekülge aruannet sisendisse, lootes, et paigutus säilib. Seda ei juhtu kunagi: tabeliveerud lähevad segamini ja mudel lõpetab mõtlemise tekstisupiga. xAI Files API lahendab täpselt selle probleemi. Saadad algse dokumendi, xAI analüüsib seda serveripoolselt ja Grok töötab sisuga, kus struktuur, tabelid ja jaotuste vahed on säilinud.
Mehhanism mahub ühte lõpppunkti: POST /v1/files. Saadad faili kujul multipart/form-data parameetriga purpose, mille väärtuseks on "assistants", ja API tagastab unikaalse identifikaatori nimega file_id. See identifikaator on võtmeks kõigele, mida edasi teed: dokumendi päring, metaandmete kontrollimine, selle kustutamine või kollektsiooni lisamine.
Sinu esimene üleslaadimine
Võta PDF-formaadis aastaruanne, mis seisab sinu kettaga. Üleslaadimise päring ei ole JSON, vaid multipart/form-data, mis seletab süntaksit -F asemel -d:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
Vastus saubub mõne sekundiga ja sisaldab faili identifikaatorit koos selle omadustega:
{
"id": "file_abc123xyz",
"object": "file",
"bytes": 2458901,
"created_at": 1710000000,
"filename": "annual-report.pdf",
"purpose": "assistants"
}
See file_id – antud juhul file_abc123xyz – on sinu püsiv viide dokumendile. Pane see kirja kohe, kui vastuse saad: kadunud identifikaator tähendab orbfaili, mis tarbib kvooti, ilma et seda oleks võimalik kasutada.
Parameetrid ja autentimine
Ainult kaks parameetrit, mõlemad kohustuslikud:
- file: Faili binaarne sisu, saadetuna multipartina. Maksimaalne suurus on 48 MB.
- purpose: Alati
"assistants", ainus seni aktsepteeritud väärtus. See näitab, et faili kasutatakse mudeliga suhtlemiseks.
Sa jõuad 48 MB piiranguni kiiremini, kui arvata oskad: ühe päeva logide eksport või täielik tootedokumentatsioon ületavad seda regulaarselt. Sel juhul jaga allikas mitmeks kooskõlaliseks failiks, mitte ei lühenda seda meelevaldselt – hiljem leiad need kõik samast kollektsioonist.
Autentimise poolelt kannab iga Files API päring sinu tavalist API võtit päises Authorization: Bearer. Pea meeles, et see võti ei ole Management API Key: see, mis on reserveeritud kollektsioonidele, tuleb kursusel hiljem ja seda aetakse alguses sageli esimesega segamini.
Faili kasutamine
Üles laaditud fail on kasutu, kui sa seda päringus ei viita. See on Responses API ploki input_file roll, millele lisad vabatekstilise juhise:
{
"model": "grok-4.5",
"input": [
{
"type": "input_file",
"file_id": "file_abc123xyz"
},
{
"type": "input_text",
"text": "Võta kokku selle dokumendi põhipunktid."
}
]
}
Grok saab faili kätte, aktiveerib automaatselt serveripoolselt tööriista attachment_search, ekstraheerib asjakohased lõigud ja kirjutab vastuse nende põhjal. Manuaalne aktiveerimine pole vajalik ja täiendavaid parameetreid pole vaja lisada: input_file olemasolu piisab kogu ahela käivitamiseks. Iga manuse päring maksab 10 dollarit 1000 kõne kohta, muutes ühe üleslaadimise, mida päritakse kümme korda, kuluefektiivsemaks kui sama dokumendi kümme eraldi üleslaadimist.
Hinnad seisuga 5. august 2026 – hinnad muutuvad regulaarselt: enne eelarve arvutamist kontrolli kehtivat hinnakirja xAI ametlikul mudelite ja hindade lehel.
Peamised punktid
- Lõpppunkt
POST /v1/filesaktsepteerib faile kuni 48 MB vormingusmultipart/form-data - Parameeter
purposepeab olema"assistants" - Tagastatud
file_idon sinu viide kõigile järgnevatele toimingutele - Tööriist
attachment_searchaktiveerub automaatselt, kui failile viidatakse päringus - Maksumus on 10 dollarit 1000 manuse päringu kohta