Gestiona tus archivos: listar, recuperar, eliminar
En esta página
Qué ocurre después del centésimo archivo
Subir un archivo tarda tres segundos; encontrar el que enviaste hace seis semanas lleva mucho más tiempo si no lo has planificado con antelación. Tras las pruebas iniciales, una cuenta acumula decenas y luego cientos de documentos. Algunos están obsoletos, otros duplicados y otros son referenciados por aplicaciones que siguen en ejecución. La API de Files expone tres operaciones para gestionar este inventario: listar, recuperar y eliminar. Parecen secundarias mientras el volumen es bajo, pero se vuelven indispensables más adelante.
Haz un inventario
GET /v1/files devuelve todos los archivos subidos a tu cuenta:
curl https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY"
La respuesta es una lista paginada, donde cada entrada repite los metadatos vistos durante la subida:
{
"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"
}
]
}
Esta vista resuelve tres situaciones muy concretas: recuperar un file_id que no guardaste en el momento de la subida, comprobar el tamaño real de un documento que parece anormalmente pesado y detectar candidatos a eliminación ordenando por created_at. También es el único lugar donde verás de un vistazo que el mismo informe se ha enviado tres veces bajo tres nombres diferentes.
Verifica un archivo específico
Cuando ya conoces el identificador, GET /v1/files/{file_id} consulta un único documento:
curl https://api.x.ai/v1/files/file_abc123 \
-H "Authorization: Bearer $XAI_API_KEY"
Recuperas la misma información que al subirlo: identificador, nombre, tamaño, fecha de creación y propósito. El uso más útil de esta llamada es preventivo. Antes de lanzar un proceso que referencie un file_id almacenado desde hace tiempo en tu base de datos, una comprobación que dura unos milisegundos te evita un error en mitad de una cadena de solicitudes facturadas.
Eliminar y qué comprobar antes
La eliminación se realiza con DELETE /v1/files/{file_id} y la respuesta confirma la operación:
curl -X DELETE https://api.x.ai/v1/files/file_abc123 \
-H "Authorization: Bearer $XAI_API_KEY"
{
"id": "file_abc123",
"object": "file",
"deleted": true
}
Son necesarias dos comprobaciones antes de apretar el gatillo. Primero, el archivo puede estar referenciado en una colección, un concepto que detallaremos en próximas lecciones. Eliminarlo mediante la API de Files no lo quita automáticamente de la colección, lo que te deja con una referencia muerta en tu índice: elimínalo primero de la colección y luego del almacenamiento. Segundo, el archivo puede estar siendo usado por flujos de trabajo activos; cualquier aplicación que mantenga este file_id en su base de datos recibirá errores en cuanto se realice la eliminación, a menudo en producción y raramente mientras estás supervisando los registros.
Mantén limpio tu almacenamiento
La nomenclatura es tu primera herramienta de gestión, porque el nombre original se conserva en los metadatos y constituye el único marcador legible en una lista de cien entradas. rapport-q1-2026.pdf tendrá significado para ti dentro de ocho meses; document.pdf nunca lo tendrá. El mismo razonamiento se aplica a api-specs-v2.json frente a data.json. Convierte esto en un hábito cuando prepares el archivo en tu disco, no en el momento de la subida: es el nombre local el que se transmite.
Los archivos subidos permanecen almacenados indefinidamente, sin caducidad automática. Una rutina de limpieza trimestral es suficiente para evitar la deriva, en tres pasos:
- Lista tus archivos con
GET /v1/files - Identifica los que ya no están en uso, por fecha de creación o nombre
- Elimínalos con
DELETE /v1/files/{file_id}
Tres códigos de error aparecen habitualmente en estas operaciones y se diagnostican de inmediato. Un 404 indica un archivo inexistente o ya eliminado, un caso típico de un script de limpieza ejecutado dos veces. Un 401 proviene de una clave de API faltante o no válida, a menudo una variable de entorno no cargada en el shell actual. Un 413 indica que el archivo supera los 48 MB permitidos y ocurre durante la subida, no durante la gestión.
Puntos clave
GET /v1/fileslista todos tus archivos con sus metadatosGET /v1/files/{id}recupera un archivo específicoDELETE /v1/files/{id}elimina permanentemente un archivo- Nombra tus archivos de forma explícita para facilitar la gestión
- Comprueba las dependencias (colecciones, flujos de trabajo) antes de eliminar