Ir al contenido principal
Español— Elegir un idioma
Menú

Carga de archivos con la API de Files

Lección 1 de 16 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Del copiar y pegar a los documentos nativos
  2. Tu primera carga
  3. Parámetros y autenticación
  4. Uso del archivo
  5. Puntos clave

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.

48 MB
Tamaño máximo por archivo
POST
Método de carga HTTP
10 $
Por cada 1.000 llamadas
Automático
Activación de attachment_search

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/files acepta archivos de hasta 48 MB en multipart/form-data.
  • El parámetro purpose debe ser "assistants".
  • El file_id devuelto es tu referencia para todas las operaciones posteriores.
  • La herramienta attachment_search se activa automáticamente cuando se referencia un archivo en una solicitud.
  • El coste es de 10 $ por cada 1.000 llamadas con adjuntos.