Upravljaj svojim datotekama: popis, dohvat, brisanje
Na ovoj stranici
Što se događa nakon stotog prijenosa
Prijenos datoteke traje tri sekunde; pronalazak one koju si poslao prije šest tjedana traje znatno duže ako nisi unaprijed planirao. Nakon početnih testova, račun akumulira desetke, a zatim i stotine dokumenata. Neki su zastarjeli, drugi duplicirani, a treće koriste aplikacije koje su još uvijek aktivne. Files API izlaže tri operacije za upravljanje ovim inventarom: popis, dohvat i brisanje. Čine se sporednima dok je volumen mali, ali kasnije postaju neophodne.
Napravi inventar
GET /v1/files vraća sve datoteke prenesene na tvoj račun:
curl https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY"
Odgovor je popis s paginacijom, gdje svaki unos ponavlja metapodatke viđene prilikom prijenosa:
{
"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"
}
]
}
Ovaj pregled rješava tri vrlo konkretne situacije: oporavak file_id koji nisi spremio tijekom prijenosa, provjeru stvarne veličine dokumenta koji se čini nenormalno teškim i uočavanje kandidata za brisanje sortiranjem po created_at. To je također jedino mjesto gdje ćeš u jednom pogledu vidjeti da je isto izvješće poslano tri puta pod tri različita imena.
Provjeri određenu datoteku
Kada već znaš identifikator, GET /v1/files/{file_id} upituje jedan dokument:
curl https://api.x.ai/v1/files/file_abc123 \
-H "Authorization: Bearer $XAI_API_KEY"
Dohvaćaš iste informacije kao i prilikom prijenosa: identifikator, ime, veličinu, datum stvaranja i svrhu. Najkorisnija uporaba ovog poziva je obrambena. Prije pokretanja procesa koji referencira file_id pohranjen dulje vrijeme u tvojoj bazi podataka, provjera koja traje nekoliko milisekundi spašava te od pogreške usred lanca naplaćenih zahtjeva.
Briši i što provjeriti prije toga
Brisanje se vrši s DELETE /v1/files/{file_id}, a odgovor potvrđuje operaciju:
curl -X DELETE https://api.x.ai/v1/files/file_abc123 \
-H "Authorization: Bearer $XAI_API_KEY"
{
"id": "file_abc123",
"object": "file",
"deleted": true
}
Prije povlačenja okidača potrebne su dvije provjere. Prvo, datoteka može biti referencirana u kolekciji – koncept koji ćemo detaljno obraditi u nadolazećim lekcijama. Njezino brisanje putem Files API-ja ne uklanja je automatski iz kolekcije, ostavljajući te s mrtvom referencom u tvom indeksu: prvo je ukloni iz kolekcije, zatim iz pohrane. Dalje, datoteku mogu koristiti aktivni radni tokovi; svaka aplikacija koja drži ovaj file_id u svojoj bazi podatatka primit će pogreške čim se izvrši brisanje, često u produkciji i rijetko dok pratiš zapise (logove).
Održavaj svoju pohranu čistom
Imenovanje je tvoj prvi alat za upravljanje jer se izvorno ime zadržava u metapodacima i čini jedinu čitljivu oznaku na popisu od stotinu unosa. rapport-q1-2026.pdf značit će ti nešto za osam mjeseci; document.pdf nikada neće. Isti razlog vrijedi za api-specs-v2.json nasuprot data.json. Učini to navikom kada pripremaš datoteku na svom disku, a ne u trenutku prijenosa: lokalno ime je ono koje se prenosi.
Prenesene datoteke ostaju pohranjene neodređeno, bez automatskog isteka. Kvartalna rutina čišćenja dovoljna je za izbjegavanje odstupanja, u tri koraka:
- Izlistaj svoje datoteke s
GET /v1/files - Identificiraj one koje se više ne koriste, prema datumu stvaranja ili imenu
- Obriši ih s
DELETE /v1/files/{file_id}
Tri koda pogreške pojavljuju se u ovim operacijama i odmah se dijagnosticiraju. 404 signalizira nepostojeću ili već obrisano datoteku, što je tipičan slučaj skripte za čišćenje pokrenute dvaput. 401 proizlazi iz nedostajućeg ili nevažećeg API ključa, često varijable okruženja koja nije učitana u trenutnoj ljusci. 413 označava da datoteka premašuje dopuštenih 48 MB i javlja se prilikom prijenosa, a ne tijekom upravljanja.
Ključne točke
GET /v1/filesizlistava sve tvoje datoteke s njihovim metapodacimaGET /v1/files/{id}dohvaća određenu datotekuDELETE /v1/files/{id}trajno briše datoteku- Imenuj svoje datoteke eksplicitno kako bi olakšao upravljanje
- Provjeri ovisnosti (kolekcije, radni tokovi) prije brisanja