Administrer dine filer: liste, hent, slet
På denne side
Hvad sker der efter den hundredede upload
Det tager tre sekunder at uploade en fil; at finde den, du sendte for seks uger siden, tager meget længere tid, hvis du ikke har planlagt det på forhånd. Efter de indledende tests ophober en konto dusinvis og derefter hundreder af dokumenter. Nogle er forældede, andre er duplikerede, og atter andre refereres til af applikationer, der stadig kører. Files API eksponerer tre operationer til at administrere dette lager: liste, hent og slet. De virker sekundære, så længe volumenet er lavt, men bliver uundværlige senere hen.
Tag inventar
GET /v1/files returnerer alle filer, der er uploadet til din konto:
curl https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY"
Svaret er en pagineret liste, hvor hver post gentager de metadata, du så ved upload:
{
"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"
}
]
}
Dette overblik løser tre meget konkrete situationer: at genfinde et file_id, du ikke gemte ved upload, at tjekke den faktiske størrelse på et dokument, der virker unormalt tungt, og at spotte kandidater til sletning ved at sortere på created_at. Det er også det eneste sted, hvor du med ét blik kan se, at den samme rapport er blevet sendt tre gange under tre forskellige navne.
Verificer en specifik fil
Når du allerede kender identifikatoren, spørger GET /v1/files/{file_id} efter et enkelt dokument:
curl https://api.x.ai/v1/files/file_abc123 \
-H "Authorization: Bearer $XAI_API_KEY"
Du henter de samme oplysninger som ved upload: identifikator, navn, størrelse, oprettelsesdato og formål. Den mest nyttige anvendelse af dette kald er defensiv. Før du starter en proces, der refererer til et file_id, der har været gemt i lang tid i din database, sparer et tjek, der varer få millisekunder, dig for en fejl midt i en kæde af fakturerbare forespørgsler.
Slet, og hvad du skal tjekke før
Sletning foretages med DELETE /v1/files/{file_id}, og svaret bekræfter operationen:
curl -X DELETE https://api.x.ai/v1/files/file_abc123 \
-H "Authorization: Bearer $XAI_API_KEY"
{
"id": "file_abc123",
"object": "file",
"deleted": true
}
To tjek er nødvendige, før du trykker på aftrækkeren. For det første kan filen være refereret i en samling – et begreb, vi vil uddybe i kommende lektioner. At slette den via Files API fjerner den ikke automatisk fra samlingen, hvilket efterlader dig med en død reference i dit indeks: fjern den først fra samlingen og derefter fra lageret. For det andet kan filen være i brug af aktive workflows; enhver applikation, der beholder dette file_id i sin database, vil modtage fejl, så snart sletningen er udført, ofte i produktion og sjældent mens du overvåger logfiler.
Hold dit lager rent
Navngivning er dit første administrationsværktøj, fordi det oprindelige navn bevares i metadata og udgør den eneste læsbare markør i en liste på hundrede poster. rapport-q1-2026.pdf vil betyde noget for dig om otte måneder; document.pdf vil aldrig gøre det. Den samme ræsonnement gælder for api-specs-v2.json kontra data.json. Gør dette til en vane, når du forbereder filen på din disk, ikke ved upload-tidspunktet: det er det lokale navn, der transmitteres.
Uploadede filer forbliver lagret på ubestemt tid uden automatisk udløb. En kvartalsvis oprydningsrutine er nok til at undgå drift, i tre trin:
- List dine filer med
GET /v1/files - Identificer dem, der ikke længere er i brug, efter oprettelsesdato eller navn
- Slet dem med
DELETE /v1/files/{file_id}
Tre fejlkode dukker op i disse operationer og diagnosticeres øjeblikkeligt. En 404 signalerer en ikke-eksisterende eller allerede slettet fil, et typisk tilfælde af et oprydningsscript, der køres to gange. En 401 skyldes en manglende eller ugyldig API-nøgle, ofte en miljøvariabel, der ikke er indlæst i den aktuelle shell. En 413 indikerer, at filen overskrider den tilladte grænse på 48 MB, og dette sker ved upload, ikke under administration.
Vigtige pointer
GET /v1/fileslister alle dine filer med deres metadataGET /v1/files/{id}henter en specifik filDELETE /v1/files/{id}sletter permanent en fil- Navngiv dine filer eksplicit for at lette administrationen
- Tjek afhængigheder (samlinger, workflows) før sletning