Spravujte své soubory: výpis, získání, smazání
Na této stránce
Co se děje po stovce nahraných souborů
Nahrání souboru trvá tři sekundy; nalezení toho, který jste odeslali před šesti týdny, zabere mnohem více času, pokud jste to předem neplánovali. Po počátečních testech se na účtu hromadí desítky a poté stovky dokumentů. Některé jsou zastaralé, jiné duplicitní a další jsou stále využívány běžícími aplikacemi. Files API nabízí tři operace pro správu tohoto inventáře: výpis, získání a smazání. Zatímco je objem nízký, zdají se být druhořadé, ale později se stanou nepostradatelnými.
Proveďte inventuru
GET /v1/files vrátí všechny soubory nahrané na váš účet:
curl https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY"
Odpovědí je stránkovaný seznam, kde každá položka opakuje metadata viděná při nahrávání:
{
"object": "list",
"data": [
{
"id": "file_abc123",
"object": "file",
"bytes": 2458901,
"created_at": 1710000000,
"filename": "rapport-annuel.pdf",
"purpose": "assistants"
},
{
"id": "file_def456",
"object": "file",
"bytes": 15230,
"created_at": 1710100000,
"filename": "données-clients.csv",
"purpose": "assistants"
}
]
}
Tento pohled řeší tři velmi konkrétní situace: získání file_id, které jste si při nahrávání neuložili, ověření skutečné velikosti dokumentu, který se zdá abnormálně velký, a identifikaci kandidátů ke smazání seřazením podle created_at. Je to také jediné místo, kde na první pohled uvidíte, že stejná zpráva byla odeslána třikrát pod třemi různými názvy.
Ověření konkrétního souboru
Pokud již znáte identifikátor, GET /v1/files/{file_id} dotazuje jediný dokument:
curl https://api.x.ai/v1/files/file_abc123 \
-H "Authorization: Bearer $XAI_API_KEY"
Získáte stejné informace jako při nahrávání: identifikátor, název, velikost, datum vytvoření a účel. Nejužitečnějším využitím tohoto volání je prevence chyb. Před spuštěním procesu, který odkazuje na file_id dlouhodobě uložený ve vaší databázi, vás kontrola trvající několik milisekund ušetří chyby uprostřed řetězce zpoplatněných požadavků.
Smazání a co zkontrolovat předem
Smazání se provádí pomocí DELETE /v1/files/{file_id} a odpověď operaci potvrzuje:
curl -X DELETE https://api.x.ai/v1/files/file_abc123 \
-H "Authorization: Bearer $XAI_API_KEY"
{
"id": "file_abc123",
"object": "file",
"deleted": true
}
Před stiskem spouště jsou nutné dvě kontroly. Zaprvé, soubor může být odkazován v kolekci – koncept, který podrobně rozebereme v nadcházejících lekcích. Jeho smazání přes Files API jej automaticky neodstraní z kolekce, což ve vašem indexu zanechá nefunkční odkaz: nejprve jej odstraňte z kolekce a až poté z úložiště. Zadruhé, soubor může být využíván aktivními pracovními postupy; jakákoli aplikace, která má toto file_id ve své databázi, začne ihned po smazání dostávat chyby, často v produkčním prostředí a zřídka v době, kdy sledujete logy.
Udržujte své úložiště čisté
Pojmenovávání je vaším prvním nástrojem pro správu, protože původní název zůstává v metadatech a představuje jediný čitelný marker v seznamu stovek položek. rapport-q1-2026.pdf vám bude něco říkat i za osm měsíců; document.pdf nikdy. Stejná logika platí pro api-specs-v2.json oproti data.json. Udělejte z toho zvyk při přípravě souboru na disku, nikoliv až v době nahrávání: přenáší se totiž lokální název.
Nahrané soubory zůstávají uloženy na dobu neurčitou bez automatického vypršení platnosti. Čtvrtletní rutina čištění stačí k tomu, aby se věci nevymkly kontrole, a to ve třech krocích:
- Vypište své soubory pomocí
GET /v1/files - Identifikujte ty, které se již nepoužívají, podle data vytvoření nebo názvu
- Smažte je pomocí
DELETE /v1/files/{file_id}
Při těchto operacích se vyskytují tři chybové kódy, které lze okamžitě diagnostikovat. 404 signalizuje neexistující nebo již smazaný soubor, což je typický případ spuštění čistícího skriptu dvakrát. 401 vzniká kvůli chybějícímu nebo neplatnému API klíči, často jde o proměnnou prostředí, která není v aktuálním shellu načtena. 413 indikuje, že soubor překračuje povolených 48 MB, k čemuž dochází při nahrávání, nikoliv během správy.
Klíčové poznatky
GET /v1/filesvypíše všechny vaše soubory s jejich metadatyGET /v1/files/{id}získá konkrétní souborDELETE /v1/files/{id}trvale smaže soubor- Pojmenovávejte soubory explicitně pro usnadnění správy
- Před smazáním zkontrolujte závislosti (kolekce, pracovní postupy)