Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Nahrávání souborů pomocí Files API

Lekce 1 z 16 Aktualizováno 29. července 2026 Vývojář
Na této stránce
  1. Od kopírování a vkládání k nativním dokumentům
  2. Tvůj první upload
  3. Parametry a autentizace
  4. Použití souboru
  5. Klíčové poznatky

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.

48 MB
Maximální velikost na soubor
POST
Metoda HTTP uploadu
$10
Za 1 000 volání
Auto
Aktivace attachment_search

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/files přijímá soubory do 48 MB ve formátu multipart/form-data
  • Parametr purpose musí být nastaven na "assistants"
  • Vrácený file_id je tvou referencí pro všechny následné operace
  • Nástroj attachment_search se aktivuje automaticky, když je soubor uveden v požadavku
  • Náklady činí 10 USD za 1 000 volání s přílohou