Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Įkelkite failus naudodami Files API

Paskaita 1 iš 16 Atnaujinta 2026 m. liepos 29 d. Kūrėjas
Šiame puslapyje
  1. Nuo kopijavimo ir įklijavimo iki natūralių dokumentų
  2. Tavo pirmasis įkėlimas
  3. Parametrai ir autentifikavimas
  4. Failo naudojimas
  5. Svarbiausi punktai

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ą.

48 MB
Maksimalus failo dydis
POST
HTTP įkėlimo metodas
$10
Už 1 000 kvietimų
Auto
„attachment_search“ aktyvinimas

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/files priima failus iki 48 MB formatu multipart/form-data
  • Parametras purpose privalo būti "assistants"
  • Grąžintas file_id yra tavo nuoroda visoms tolesnėms operacijoms
  • Įrankis attachment_search automatiškai aktyvuojamas, kai užklausoje nurodomas failas
  • Kaina yra 10 USD už 1 000 priedo kvietimų