Zarządzaj swoimi plikami: lista, pobieranie, usuwanie
Na tej stronie
Co się dzieje po setnym przesłaniu
Przesłanie pliku zajmuje trzy sekundy; znalezienie tego, który wysłałeś sześć tygodni temu, trwa znacznie dłużej, jeśli nie zaplanowałeś tego wcześniej. Po początkowych testach na koncie gromadzą się dziesiątki, a następnie setki dokumentów. Niektóre są nieaktualne, inne zduplikowane, a jeszcze inne są używane przez nadal działające aplikacje. Files API udostępnia trzy operacje do zarządzania tym zasobem: listowanie, pobieranie i usuwanie. Wydają się one drugorzędne, gdy wolumen jest niski, ale później stają się niezbędne.
Sporządź inwentarz
GET /v1/files zwraca wszystkie pliki przesłane na Twoje konto:
curl https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY"
Odpowiedź to stronicowana lista, gdzie każdy wpis powtarza metadane widoczne podczas przesyłania:
{
"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"
}
]
}
Widok ten rozwiązuje trzy bardzo konkretne sytuacje: odzyskanie file_id, którego nie zapisałeś w momencie przesyłania, sprawdzenie rzeczywistego rozmiaru dokumentu, który wydaje się nienormalnie duży, oraz wykrycie kandydatów do usunięcia poprzez sortowanie po created_at. To również jedyne miejsce, gdzie jednym rzutem oka zobaczysz, że ten sam raport został wysłany trzy razy pod trzema różnymi nazwami.
Zweryfikuj konkretny plik
Gdy już znasz identyfikator, GET /v1/files/{file_id} odpytuje pojedynczy dokument:
curl https://api.x.ai/v1/files/file_abc123 \
-H "Authorization: Bearer $XAI_API_KEY"
Odzyskujesz te same informacje co przy przesyłaniu: identyfikator, nazwę, rozmiar, datę utworzenia i cel. Najbardziej przydatnym zastosowaniem tego wywołania jest działanie prewencyjne. Przed uruchomieniem procesu odwołującego się do file_id przechowywanego od dawna w Twojej bazie danych, sprawdzenie trwające kilka milisekund uchroni Cię przed błędem w środku łańcucha płatnych żądań.
Usuwanie i co sprawdzić przed naciśnięciem spustu
Usunięcia dokonuje się za pomocą DELETE /v1/files/{file_id}, a odpowiedź potwierdza operację:
curl -X DELETE https://api.x.ai/v1/files/file_abc123 \
-H "Authorization: Bearer $XAI_API_KEY"
{
"id": "file_abc123",
"object": "file",
"deleted": true
}
Przed naciśnięciem spustu wymagane są dwie kontrole. Po pierwsze, plik może być referencjonowany w kolekcji – koncepcję tę szczegółowo omówimy w nadchodzących lekcjach. Usunięcie go przez Files API nie usuwa go automatycznie z kolekcji, pozostawiając martwą referencję w Twoim indeksie: najpierw usuń go z kolekcji, a następnie z magazynu. Po drugie, plik może być używany przez aktywne przepływy pracy; każda aplikacja przechowująca ten file_id w swojej bazie danych otrzyma błędy natychmiast po wykonaniu usunięcia, często w środowisku produkcyjnym i rzadko w momencie, gdy monitorujesz logi.
Utrzymuj porządek w magazynie
Nazywanie to Twoje pierwsze narzędzie zarządzania, ponieważ oryginalna nazwa jest zachowywana w metadanych i stanowi jedyny czytelny znacznik na liście stu wpisów. rapport-q1-2026.pdf będzie dla Ciebie coś znaczyć za osiem miesięcy; document.pdf – nigdy. To samo rozumowanie dotyczy api-specs-v2.json w kontraście do data.json. Wyrób sobie ten nawyk podczas przygotowywania pliku na dysku, a nie w momencie przesyłania: to nazwa lokalna jest transmitowana.
Przesłane pliki pozostają przechowywane w nieskończoność, bez automatycznego wygasania. Kwartalna rutina czyszczenia wystarczy, aby uniknąć chaosu, w trzech krokach:
- Wylistuj swoje pliki za pomocą
GET /v1/files - Zidentyfikuj te, które nie są już używane, po dacie utworzenia lub nazwie
- Usuń je za pomocą
DELETE /v1/files/{file_id}
W tych operacjach pojawiają się trzy kody błędów, które diagnozuje się natychmiast. 404 sygnalizuje plik nieistniejący lub już usunięty, co jest typowym przypadkiem skryptu czyszczącego uruchomionego dwukrotnie. 401 wynika z brakującego lub nieprawidłowego klucza API, często ze zmiennej środowiskowej niezaładowanej w bieżącej powłoce. 413 wskazuje, że plik przekracza dozwolone 48 MB i występuje podczas przesyłania, a nie podczas zarządzania.
Kluczowe wnioski
GET /v1/fileswyświetla listę wszystkich Twoich plików wraz z ich metadanymiGET /v1/files/{id}pobiera konkretny plikDELETE /v1/files/{id}trwale usuwa plik- Nadawaj plikom wyraźne nazwy, aby ułatwić zarządzanie
- Sprawdź zależności (kolekcje, przepływy pracy) przed usunięciem