Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Failide üleslaadimine Files API kaudu

Õppetund 1 / 16 Värskendatud 29. juuli 2026 Arendajatele
Sellel lehel
  1. Kopeerimisest ja kleepimisest päris dokumentideni
  2. Sinu esimene üleslaadimine
  3. Parameetrid ja autentimine
  4. Faili kasutamine
  5. Peamised punktid

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.

48 MB
Maksimaalne suurus faili kohta
POST
HTTP üleslaadimise meetod
$10
1000 päringu kohta
Auto
attachment_search aktiveerimine

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/files aktsepteerib faile kuni 48 MB vormingus multipart/form-data
  • Parameeter purpose peab olema "assistants"
  • Tagastatud file_id on sinu viide kõigile järgnevatele toimingutele
  • Tööriist attachment_search aktiveerub automaatselt, kui failile viidatakse päringus
  • Maksumus on 10 dollarit 1000 manuse päringu kohta