Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Nahrávanie súborov pomocou Files API

Lekcia 1 z 16 Aktualizované 29. júla 2026 Vývojár
Na tejto strane
  1. Od kopírovania a vkladania k natívnym dokumentom
  2. Tvoje prvé nahratie
  3. Parametre a autentifikácia
  4. Používanie súboru
  5. Kľúčové poznatky

Od kopírovania a vkladania k natívnym dokumentom

Pravdepodobne si už vložil pätnásť stránok správy priamo do promptu v nádeji, že sa zachová rozloženie. Nikdy sa to nestane: stĺpce v tabuľkách sa pomiešajú a model nakoniec pracuje s textovou kašou. Files API od xAI rieši presne tento problém. Odošleš pôvodný dokument, xAI ho analyzuje na strane servera a Grok pracuje s obsahom, kde zostáva zachovaná štruktúra, tabuľky aj zlomy sekcií.

Celý mechanizmus sa zmestí do jediného koncového bodu, POST /v1/files. Súbor odošleš ako multipart/form-data s parametrom purpose nastaveným na "assistants" a API ti vráti jedinečný identifikátor nazývaný file_id. Tento identifikátor sa stáva kľúčom pre všetko, čo budeš robiť ďalej: dopytovanie dokumentu, kontrolu jeho metadát, jeho vymazanie alebo pridanie do kolekcie.

48 MB
Maximálna veľkosť na súbor
POST
Metóda HTTP uploadu
$10
Za 1 000 volaní
Auto
Aktivácia attachment_search

Tvoje prvé nahratie

Predstav si výročnú správu vo formáte PDF, ktorú máš uloženú na disku. Žiadosť o nahratie nie je vo formáte JSON, ale multipart/form-data, čo vysvetľuje použitie syntaxe -F namiesto -d:

curl -X POST https://api.x.ai/v1/files \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -F "[email protected]" \
  -F "purpose=assistants"

Odpoveď dorazí za niekoľko sekúnd a obsahuje identifikátor súboru spolu s jeho charakteristikami:

{
  "id": "file_abc123xyz",
  "object": "file",
  "bytes": 2458901,
  "created_at": 1710000000,
  "filename": "annual-report.pdf",
  "purpose": "assistants"
}

Tento file_id – v tomto prípade file_abc123xyz – je tvoja trvalá referencia na dokument. Zapíš si ho hneď, ako dostaneš odpoveď: stratený identifikátor znamená osirelý súbor, ktorý míňa kvótu, ale nie je použiteľný.

Parametre a autentifikácia

Existujú len dva parametre a oba sú povinné:

  • file: Binárny obsah súboru odoslaný ako multipart. Maximálna veľkosť je 48 MB
  • purpose: Vždy "assistants", čo je doposiaľ jediná akceptovaná hodnota. Označuje, že súbor sa použije na interakcie s modelom

Na limit 48 MB narazíš rýchlejšie, než by si čakal: export logov za jeden deň alebo kompletná produktová dokumentácia ho bežne presahujú. V takom prípade rozdeľ zdrojový materiál na niekoľko logických súborov namiesto toho, aby si ho svojvoľne skracoval – neskôr ich všetky nájdeš v tej istej kolekcii.

Pokiaľ ide o autentifikáciu, každá požiadavka na Files API nesie tvoj štandardný API kľúč v hlavičke Authorization: Bearer. Hneď teraz maj na pamäti, že tento kľúč nie je Management API Key: ten, vyhradený pre kolekcie, príde na rad neskôr v kurze a začiatočníci ho často zamieňajú s tým prvým.

Používanie súboru

Nahraný súbor je zbytočný, pokiaľ naň neodkážeš v požiadavke. To je úlohou bloku input_file v Responses API, ktorý doplníš inštrukciou voľným textom:

{
  "model": "grok-4.5",
  "input": [
    {
      "type": "input_file",
      "file_id": "file_abc123xyz"
    },
    {
      "type": "input_text",
      "text": "Zhrň kľúčové body tohto dokumentu."
    }
  ]
}

Grok prijme súbor, automaticky aktivuje nástroj attachment_search na strane servera, extrahuje relevantné pasáže a na ich základe napíše odpoveď. Nie je potrebná žiadna manuálna aktivácia ani pridávanie ďalších parametrov: samotná prítomnosť input_file stačí na spustenie celého reťazca. Každé volanie s prílohou sa účtuje sumou 10 USD za 1 000 volaní, čo znamená, že jedno nahratie dopytované desaťkrát je nákladovo efektívnejšie ako desať samostatných nahraní toho istého dokumentu.

Ceny platné k 5. augustu 2026 – ceny sa pravidelne menia: pred akýmkoľvek výpočtom rozpočtu si over aktuálny cenník na oficiálnej stránke modelov a cien xAI.

Kľúčové poznatky

  • Koncový bod POST /v1/files prijíma súbory do veľkosti 48 MB vo formáte multipart/form-data
  • Parameter purpose musí mať hodnotu "assistants"
  • Vrátaný file_id je tvojou referenciou pre všetky následné operácie
  • Nástroj attachment_search sa aktivuje automaticky, keď je súbor uvedený v požiadavke
  • Náklady predstavujú 10 USD za 1 000 volaní s prílohou