Dateien verwalten: Auflisten, abrufen, löschen
Auf dieser Seite
Was passiert nach dem hundertsten Upload
Ein Datei-Upload dauert drei Sekunden; die Suche nach einer Datei, die Sie vor sechs Wochen gesendet haben, dauert viel länger, wenn Sie nicht im Voraus geplant haben. Nach den ersten Tests sammelt ein Konto Dutzende, dann Hunderte von Dokumenten an. Manche sind veraltet, andere dupliziert, und andere werden von noch laufenden Anwendungen referenziert. Die Files API stellt drei Operationen zur Verwaltung dieses Inventars bereit: Auflisten, Abrufen und Löschen. Sie scheinen sekundär, solange das Volumen gering ist, werden aber später unverzichtbar.
Inventur erstellen
GET /v1/files gibt alle Dateien zurück, die in Ihr Konto hochgeladen wurden:
curl https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY"
Die Antwort ist eine paginierte Liste, bei der jeder Eintrag die beim Upload sichtbaren Metadaten wiederholt:
{
"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"
}
]
}
Diese Ansicht löst drei sehr konkrete Situationen: Wiederherstellung eines file_id, das zum Zeitpunkt des Uploads nicht gespeichert wurde, Überprüfung der tatsächlichen Größe eines Dokuments, das ungewöhnlich schwer erscheint, und Erkennung von Lösungskandidaten durch Sortierung nach created_at. Es ist auch der einzige Ort, an dem Sie auf einen Blick erkennen, dass derselbe Bericht drei Mal unter drei verschiedenen Namen gesendet wurde.
Eine spezifische Datei verifizieren
Wenn Sie den Identifier bereits kennen, fragt GET /v1/files/{file_id} ein einzelnes Dokument ab:
curl https://api.x.ai/v1/files/file_abc123 \
-H "Authorization: Bearer $XAI_API_KEY"
Sie erhalten dieselben Informationen wie beim Upload: Identifier, Name, Größe, Erstellungsdatum und Zweck. Der nützlichste Einsatz dieses Aufrufs ist defensiv. Bevor ein Prozess gestartet wird, der ein in Ihrer Datenbank langfristig gespeichertes file_id referenziert, spart eine Überprüfung, die nur wenige Millisekunden dauert, Ihnen einen Fehler mitten in einer Kette von abgerechneten Anfragen.
Löschen und was vorher zu prüfen ist
Das Löschen erfolgt mit DELETE /v1/files/{file_id} und die Antwort bestätigt die Operation:
curl -X DELETE https://api.x.ai/v1/files/file_abc123 \
-H "Authorization: Bearer $XAI_API_KEY"
{
"id": "file_abc123",
"object": "file",
"deleted": true
}
Zwei Prüfungen sind erforderlich, bevor der Auslöser gezerrt wird. Erstens kann die Datei in einer Collection referenziert sein – ein Konzept, das wir in kommenden Lektionen detailliert behandeln werden. Das Löschen über die Files API entfernt sie nicht automatisch aus der Collection, sodass Sie eine tote Referenz in Ihrem Index zurücklassen: Entfernen Sie sie zuerst aus der Collection, dann aus der Speicherung. Zweitens kann die Datei von aktiven Workflows verwendet werden; jede Anwendung, die dieses file_id in ihrer Datenbank speichert, erhält Fehler, sobald das Löschen durchgeführt wird, oft in der Produktion und selten, während Sie Logs überwachen.
Ihren Speicher sauber halten
Namensgebung ist Ihr erstes Verwaltungswerkzeug, da der ursprüngliche Name in den Metadaten erhalten bleibt und das einzige lesbare Merkmal in einer Liste von hundert Einträgen darstellt. rapport-q1-2026.pdf wird Ihnen in acht Monaten etwas bedeuten; document.pdf niemals. Dasselbe gilt für api-specs-v2.json gegenüber data.json. Machen Sie dies zur Gewohnheit, wenn Sie die Datei auf Ihrem Disk vorbereiten, nicht zum Zeitpunkt des Uploads: Es ist der lokale Name, der übermittelt wird.
Hochgeladene Dateien bleiben unbegrenzt gespeichert, ohne automatische Ablaufzeit. Eine vierteljährliche Bereinigungsroutine reicht aus, um Drift zu vermeiden, in drei Schritten:
- Listen Sie Ihre Dateien mit
GET /v1/files - Identifizieren Sie diejenigen, die nicht mehr verwendet werden, nach Erstellungsdatum oder Name
- Löschen Sie sie mit
DELETE /v1/files/{file_id}
Drei Fehlercodes treten bei diesen Operationen auf und werden sofort diagnostiziert. Ein 404 signalisiert eine nicht existierende oder bereits gelöschte Datei, ein typischer Fall eines Bereinigungsskripts, das zweimal ausgeführt wird. Ein 401 stammt von einem fehlenden oder ungültigen API-Schlüssel, oft einer Umgebungsvariable, die nicht in der aktuellen Shell geladen wurde. Ein 413 zeigt an, dass die Datei das erlaubte Limit von 48 MB überschreitet und tritt beim Upload auf, nicht während der Verwaltung.
Kernaussagen
GET /v1/fileslistet alle Ihre Dateien mit ihren Metadaten aufGET /v1/files/{id}ruft eine spezifische Datei abDELETE /v1/files/{id}löscht eine Datei dauerhaft- Benennen Sie Ihre Dateien explizit, um die Verwaltung zu erleichtern
- Prüfen Sie Abhängigkeiten (Collections, Workflows) vor dem Löschen