Nahrávání souborů pomocí Files API
Na této stránce
Od kopírování a vkládání k nativním dokumentům
Pravděpodobně jsi už vložil patnáct stran reportu přímo do promptu s nadějí, že se zachová rozložení. Nikdy se to nestane: sloupce v tabulkách se pomíchají a model nakonec usuzuje nad textovou kaší. Files API od xAI řeší přesně tento problém. Pošleš původní dokument, xAI jej analyzuje na straně serveru a Grok pracuje s obsahem, kde zůstávají zachována struktura, tabulky i oddíly.
Mechanismus zapadá do jediného koncového bodu, POST /v1/files. Soubor odešleš jako multipart/form-data s parametrem purpose nastaveným na "assistants" a API vrátí jedinečný identifikátor nazývaný file_id. Tento identifikátor se stane klíčem pro vše, co budeš dělat dál: dotazování na dokument, kontrolu jeho metadat, jeho smazání nebo přidání do kolekce.
Tvůj první upload
Vezmi výroční zprávu ve formátu PDF, kterou máš na disku. Požadavek na upload není ve formátu JSON, ale multipart/form-data, což vysvětluje použití syntaxe -F místo -d:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
Odpověď dorazí během několika sekund a obsahuje identifikátor souboru spolu s jeho charakteristikami:
{
"id": "file_abc123xyz",
"object": "file",
"bytes": 2458901,
"created_at": 1710000000,
"filename": "annual-report.pdf",
"purpose": "assistants"
}
Tento file_id – zde file_abc123xyz – je tvou trvalou referencí na dokument. Poznamenej si jej hned, jakmile obdržíš odpověď: ztracený identifikátor znamená osiřelý soubor, který spotřebovává kvótu, aniž by byl použitelný.
Parametry a autentizace
Jsou potřeba pouze dva parametry, oba povinné:
- file: Binární obsah souboru odeslaný jako multipart. Maximální velikost je 48 MB.
- purpose: Vždy
"assistants", což je doposud jediná přijímaná hodnota. Označuje, že soubor bude použit pro interakce s modelem.
Na limit 48 MB narazíš rychleji, než čekáš: export logů za jeden den nebo kompletní produktová dokumentace jej běžně překračují. V takovém případě rozděl zdrojový materiál na několik ucelených souborů místo libovolného zkracování – později je všechny najdeš ve stejné kolekci.
Co se týče autentizace, každý požadavek na Files API nese tvůj standardní API klíč v hlavičce Authorization: Bearer. Měj hned na paměti, že tento klíč není Management API Key: ten, vyhrazený pro kolekce, přijde na řadu až později v kurzu a začátečníci jej často s tím prvním zaměňují.
Použití souboru
Nahraný soubor je k ničemu, pokud na něj neodkážeš v požadavku. To je role bloku input_file v Responses API, který doprovodíš instrukcí v prostém textu:
{
"model": "grok-4.5",
"input": [
{
"type": "input_file",
"file_id": "file_abc123xyz"
},
{
"type": "input_text",
"text": "Shrň klíčové body tohoto dokumentu."
}
]
}
Grok obdrží soubor, automaticky aktivuje nástroj attachment_search na straně serveru, extrahuje relevantní pasáže a na jejich základě napíše odpověď. Není potřeba žádná manuální aktivace ani přidávání dalších parametrů: samotná přítomnost input_file stačí ke spuštění celého řetězce. Každé volání s přílohou je zpoplatněno částkou 10 USD za 1 000 volání, což činí jeden upload dotazovaný desetkrát nákladově efektivnějším než deset uploadů téhož dokumentu.
Ceny platné k 5. srpnu 2026 – ceny se pravidelně mění: před jakýmkoli výpočtem rozpočtu si ověř aktuální ceník na oficiální stránce modelů a cen xAI.
Klíčové poznatky
- Koncový bod
POST /v1/filespřijímá soubory do 48 MB ve formátumultipart/form-data - Parametr
purposemusí být nastaven na"assistants" - Vrácený
file_idje tvou referencí pro všechny následné operace - Nástroj
attachment_searchse aktivuje automaticky, když je soubor uveden v požadavku - Náklady činí 10 USD za 1 000 volání s přílohou