Hantera dina filer: lista, hämta, radera
På denna sida
Vad händer efter den hundrade uppladdningen
Att ladda upp en fil tar tre sekunder; att hitta den du skickade för sex veckor sedan tar betydligt längre tid om du inte har planerat i förväg. Efter de första testerna ackumulerar ett konto dussintals och sedan hundratals dokument. Vissa är föråldrade, andra är duplicerade och åter andra refereras till av applikationer som fortfarande körs. Files API exponerar tre operationer för att hantera detta lager: lista, hämta och radera. De verkar sekundära så länge volymen är låg, men blir oumbärliga senare.
Gör inventering
GET /v1/files returnerar alla filer som laddats upp till ditt konto:
curl https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY"
Svaret är en paginerad lista där varje post upprepar metadata som sågs vid uppladdningen:
{
"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"
}
]
}
Denna vy löser tre mycket konkreta situationer: att återskaffa ett file_id som du inte sparade vid uppladdningstillfället, att kontrollera den faktiska storleken på ett dokument som verkar onormalt tungt, och att identifiera kandidater för radering genom att sortera på created_at. Det är också den enda platsen där du vid en första anblick ser att samma rapport har skickats tre gånger under tre olika namn.
Verifiera en specifik fil
När du redan känner till identifieraren frågar GET /v1/files/{file_id} efter ett enskilt dokument:
curl https://api.x.ai/v1/files/file_abc123 \
-H "Authorization: Bearer $XAI_API_KEY"
Du hämtar samma information som vid uppladdningen: identifierare, namn, storlek, skapandedatum och syfte. Den mest användbara tillämpningen av detta anrop är defensiv. Innan du startar en process som refererar till ett file_id som lagrats under lång tid i din databas, sparar en kontroll som tar några millisekunder dig från ett fel mitt i en kedja av fakturerade förfrågningar.
Radera och vad du måste kontrollera innan
Radering sker med DELETE /v1/files/{file_id} och svaret bekräftar 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
}
Två kontroller krävs innan du trycker på avtryckaren. För det första kan filen refereras i en samling – ett koncept vi kommer att detaljera i kommande lektioner. Att radera den via Files API tar inte automatiskt bort den från samlingen, vilket lämnar dig med en död referens i ditt index: ta bort den från samlingen först, och sedan från lagringen. Därefter kan filen användas av aktiva arbetsflöden; varje applikation som behåller detta file_id i sin databas kommer att få fel så snart raderingen utförs, ofta i produktion och sällan medan du övervakar loggar.
Håll din lagring ren
Namngivning är ditt första hanteringsverktyg, eftersom det ursprungliga namnet behålls i metadata och utgör den enda läsbara markören i en lista på hundra poster. rapport-q1-2026.pdf kommer att betyda något för dig om åtta månader; document.pdf kommer aldrig att göra det. Samma resonemang gäller för api-specs-v2.json jämfört med data.json. Gör detta till en vana när du förbereder filen på din disk, inte vid uppladdningstillfället: det är det lokala namnet som överförs.
Uppladdade filer förblir lagrade på obestämd tid utan automatisk utgång. En kvartalsvis städrutin räcker för att undvika avdrift, i tre steg:
- Lista dina filer med
GET /v1/files - Identifiera de som inte längre används, efter skapandedatum eller namn
- Radera dem med
DELETE /v1/files/{file_id}
Tre felkoder dyker upp i dessa operationer och diagnosticeras omedelbart. En 404 signalerar en fil som inte finns eller redan har raderats, ett typiskt fall av ett städskript som körs två gånger. En 401 kommer från en saknad eller ogiltig API-nyckel, ofta en miljövariabel som inte laddats i det aktuella skalet. En 413 indikerar att filen överskrider den tillåtna gränsen på 48 MB och inträffar vid uppladdning, inte under hantering.
Viktiga punkter
GET /v1/fileslistar alla dina filer med deras metadataGET /v1/files/{id}hämtar en specifik filDELETE /v1/files/{id}raderar en fil permanent- Namnge dina filer explicit för att underlätta hantering
- Kontrollera beroenden (samlingar, arbetsflöden) innan radering