Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Prenos datotek z API-jem Files

Lekcija 1 od 16 Posodobljeno 29. julij 2026 Razvijalec
Na tej strani
  1. Od kopiranja in lepljenja do izvornih dokumentov
  2. Tvoje prvo nalaganje
  3. Parametri in avtentikacija
  4. Uporaba datoteke
  5. Ključne ugotovitve

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.

48 MB
Največja velikost na datoteko
POST
Metoda nalaganja HTTP
$10
Na 1.000 klicev
Samodejno
Aktivacija attachment_search

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/files sprejme datoteke do 48 MB v formatu multipart/form-data
  • Parameter purpose mora biti "assistants"
  • Vrnjeni file_id je tvoja referenca za vse nadaljnje operacije
  • Orodje attachment_search se samodejno aktivira, ko je datoteka navedena v zahtevku
  • Strošek znaša 10 $ na 1.000 klicev priloge