Įkelkite failus naudodami Files API
Šiame puslapyje
Nuo kopijavimo ir įklijavimo iki natūralių dokumentų
Turbūt esi įklijavęs penkiolika ataskaitos puslapių į užklausą tikėdamasis, kad išdėstymas išliks. To niekada neįvyksta: lentelių stulpeliai susipainioja, o modelis pradeda samprotauti remdamasis teksto koše. xAI „Files API“ išsprendžia būtent šią problemą. Siunti originalų dokumentą, xAI jį analizuoja serverio pusėje, o „Grok“ dirba su turiniu, kuriame išsaugoma struktūra, lentelės ir skyrių skirtukai.
Mechanizmas telpa į vieną galinį tašką: POST /v1/files. Failą siunči kaip multipart/form-data su parametru purpose, nustatytu į "assistants", o API grąžina unikalų identifikatorių, vadinamą file_id. Šis identifikatorius tampa raktu viskam, ką darysi toliau: dokumento užklausoms, metaduomenų tikrinimui, trynimui arba pridėjimui į kolekciją.
Tavo pirmasis įkėlimas
Paimk metinę ataskaitą PDF formatu, esančią tavo diske. Įkėlimo užklausa yra ne JSON, o multipart/form-data, todėl naudojama -F sintaksė, o ne -d:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
Atsakymas ateina per kelias sekundes ir jame yra failo identifikatorius bei jo charakteristikos:
{
"id": "file_abc123xyz",
"object": "file",
"bytes": 2458901,
"created_at": 1710000000,
"filename": "annual-report.pdf",
"purpose": "assistants"
}
Šis file_id – šiuo atveju file_abc123xyz – yra tavo nuolatinė nuoroda į dokumentą. Užsirašyk jį iškart gavęs atsakymą: prarastas identifikatorius reiškia našlaičiu tapusį failą, kuris eikvoja kvotą, bet negali būti naudojamas.
Parametrai ir autentifikavimas
Tik du parametrai, abu privalomi:
- file: Dvejetainis failo turinys, siunčiamas kaip multipart. Maksimalus dydis – 48 MB.
- purpose: Visada
"assistants"– tai vienintelė iki šiol priimtina reikšmė. Ji nurodo, kad failas bus naudojamas sąveikai su modeliu.
48 MB ribą pasieksi greičiau, nei gali manyti: vienos dienos žurnalų eksportas arba išsami produkto dokumentacija ją dažnai viršija. Tokiu atveju šaltinį suskirstyk į kelis logiškus failus, o ne savavališkai trumpink – vėliau visus juos rasi toje pačioje kolekcijoje.
Autentifikavimo požiūriu, kiekvienoje „Files API“ užklausoje standartinis API raktas perduodamas antraštėje Authorization: Bearer. Dabar įsimink, kad šis raktas nėra „Management API Key“: pastarasis, skirtas kolekcijoms, bus aptariamas vėliau kurse ir pradinėse stadijose jis dažnai painiojamas su pirmuoju.
Failo naudojimas
Įkeltas failas yra nenaudingas, jei nenurodai jo užklausoje. Tam skirtas input_file blokas „Responses API“, kurį papildai laisvos formos instrukcija:
{
"model": "grok-4.5",
"input": [
{
"type": "input_file",
"file_id": "file_abc123xyz"
},
{
"type": "input_text",
"text": "Apibendrink pagrindinius šio dokumento punktus."
}
]
}
„Grok“ gauna failą, automatiškai serverio pusėje aktyvuoja įrankį attachment_search, ištraukia atitinkamas ištraukas ir pagal jas suformuluoja atsakymą. Joks rankinis aktyvinimas nereikalingas, jokių papildomų parametrų pridėti nereikia: pakanka vien input_file buvimo, kad būtų suveikinta visa grandinė. Kiekvienas priedo kvietimas kainuoja 10 USD už 1 000 kartų, todėl vieną kartą įkeltas failas, užklausiamas dešimt kartų, yra ekonomiškiau nei dešimt kartų įkelti tą patį dokumentą.
Kainodara pagal 2026 m. rugpjūčio 5 d. duomenis – kainos keičiasi reguliariai: prieš atlikdami bet kokius biudžeto skaičiavimus, patikrinkite dabartinį kainoraštį oficialiame xAI modelių ir kainodaros puslapyje.
Svarbiausi punktai
- Galinis taškas
POST /v1/filespriima failus iki 48 MB formatumultipart/form-data - Parametras
purposeprivalo būti"assistants" - Grąžintas
file_idyra tavo nuoroda visoms tolesnėms operacijoms - Įrankis
attachment_searchautomatiškai aktyvuojamas, kai užklausoje nurodomas failas - Kaina yra 10 USD už 1 000 priedo kvietimų