Carga de archivos con la API de Files
En esta página
Del copiar y pegar a los documentos nativos
Seguro que alguna vez has pegado quince páginas de un informe en un prompt con la esperanza de que el formato se mantenga. Nunca funciona: las columnas de las tablas se mezclan y el modelo termina razonando sobre una masa de texto informe. La API de Files de xAI resuelve exactamente este problema. Envías el documento original, xAI lo analiza en el servidor y Grok trabaja sobre un contenido donde se preservan la estructura, las tablas y los saltos de sección.
El mecanismo se integra en un único extremo, POST /v1/files. Envías tu archivo como multipart/form-data con un parámetro purpose establecido en "assistants", y la API devuelve un identificador único llamado file_id. Este identificador se convierte en la clave para todo lo que hagas a continuación: consultar el documento, comprobar sus metadatos, eliminarlo o añadirlo a una colección.
Tu primera carga
Toma un informe anual en formato PDF que tengas en tu disco. La solicitud de carga no es JSON, sino multipart/form-data, lo que explica el uso de la sintaxis -F en lugar de -d:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
La respuesta llega en unos segundos y contiene el identificador del archivo junto con sus características:
{
"id": "file_abc123xyz",
"object": "file",
"bytes": 2458901,
"created_at": 1710000000,
"filename": "annual-report.pdf",
"purpose": "assistants"
}
Este file_id —en este caso file_abc123xyz— es tu referencia permanente al documento. Anótalo nada más recibir la respuesta: perder el identificador significa tener un archivo huérfano que consume cuota sin poder utilizarse.
Parámetros y autenticación
Solo hay dos parámetros, ambos obligatorios:
- file: El contenido binario del archivo, enviado como multipart. El tamaño máximo es de 48 MB.
- purpose: Siempre
"assistants", el único valor aceptado hasta la fecha. Indica que el archivo se utilizará para interacciones con el modelo.
Alcanzarás el límite de 48 MB más rápido de lo que imaginas: una exportación de registros de un día o la documentación completa de un producto suelen superarlo. En ese caso, divide tu fuente en varios archivos coherentes en lugar de truncarla arbitrariamente; luego los encontrarás todos en la misma colección.
En cuanto a la autenticación, cada solicitud a la API de Files lleva tu clave de API estándar en la cabecera Authorization: Bearer. Ten presente desde ya que esta clave no es la Clave de API de Gestión (Management API Key): esa otra, reservada para las colecciones, se verá más adelante en el curso y suele confundirse con la primera durante los primeros intentos.
Uso del archivo
El archivo cargado es inútil si no se referencia en una solicitud. Esta es la función del bloque input_file en la API de Responses, que acompañas con una instrucción en texto libre:
{
"model": "grok-4.5",
"input": [
{
"type": "input_file",
"file_id": "file_abc123xyz"
},
{
"type": "input_text",
"text": "Resume los puntos clave de este documento."
}
]
}
Grok recibe el archivo, activa automáticamente la herramienta attachment_search en el servidor, extrae los pasajes relevantes y escribe su respuesta basándose en ellos. No es necesaria ninguna activación manual ni hay que añadir parámetros adicionales: la presencia de un input_file basta para desencadenar toda la cadena. Cada llamada con adjunto se factura a 10 $ por 1.000, lo que hace que una sola carga consultada diez veces sea más rentable que diez cargas del mismo documento.
Precios a 5 de agosto de 2026: los precios cambian con frecuencia; antes de realizar cualquier cálculo presupuestario, consulta la tarifa actual en la página oficial de modelos y precios de xAI.
Puntos clave
- El extremo
POST /v1/filesacepta archivos de hasta 48 MB enmultipart/form-data. - El parámetro
purposedebe ser"assistants". - El
file_iddevuelto es tu referencia para todas las operaciones posteriores. - La herramienta
attachment_searchse activa automáticamente cuando se referencia un archivo en una solicitud. - El coste es de 10 $ por cada 1.000 llamadas con adjuntos.