Nahrávanie súborov pomocou Files API
Na tejto strane
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.
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/filesprijíma súbory do veľkosti 48 MB vo formátemultipart/form-data - Parameter
purposemusí mať hodnotu"assistants" - Vrátaný
file_idje tvojou referenciou pre všetky následné operácie - Nástroj
attachment_searchsa aktivuje automaticky, keď je súbor uvedený v požiadavke - Náklady predstavujú 10 USD za 1 000 volaní s prílohou