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

input_file y attachment_search en la API de Responses

Lección 4 de 16 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Dos caminos hacia el mismo bloque
  2. El camino de file_id
  3. El camino de file_url
  4. Qué hace attachment_search
  5. Combinación de varios documentos
  6. Elección entre las dos opciones
  7. Puntos clave

Dos caminos hacia el mismo bloque

La API de Responses de Grok acepta un documento de dos formas: mediante file_id, que hace referencia a un archivo que has subido previamente, o mediante file_url, una dirección pública que xAI recupera en el momento de la solicitud. El bloque utiliza el mismo nombre en ambos casos, input_file, y el procesamiento posterior es idéntico: Grok activa la herramienta attachment_search y extrae los pasajes que responden a tu pregunta. Lo que cambia es el ciclo de vida del documento, su confidencialidad y el coste de cada llamada repetida.

El camino de file_id

Una vez que envías el archivo mediante POST /v1/files, haces referencia a él por su identificador, junto con tu pregunta en texto plano:

{
  "model": "grok-4.5",
  "input": [
    {
      "type": "input_file",
      "file_id": "file_abc123"
    },
    {
      "type": "input_text",
      "text": "¿Cuáles son los principales riesgos mencionados en este informe?"
    }
  ]
}

Este enfoque tiene sentido en tres situaciones. La primera son las consultas repetidas: si tu equipo jurídico formula quince preguntas sucesivas sobre el mismo contrato, una única subida seguida de quince referencias es más eficiente que quince transferencias del mismo PDF. La segunda es la confidencialidad, cuando el documento no debe quedar expuesto detrás de una URL accesible para cualquiera que tenga el enlace. La tercera es la arquitectura de tu aplicación: si los archivos se suben previamente durante la ingesta nocturna, tus solicitudes solo gestionan identificadores.

El camino de file_url

Cuando el documento ya está publicado en algún lugar, la subida se convierte en un paso innecesario y puedes apuntar directamente a la dirección:

{
  "model": "grok-4.5",
  "input": [
    {
      "type": "input_file",
      "file_url": "https://exemple.com/specifications-api.pdf"
    },
    {
      "type": "input_text",
      "text": "Resume los endpoints descritos en esta documentación."
    }
  ]
}

Los casos de uso típicos incluyen documentación abierta que no tienes motivo para almacenar, un archivo alojado en tu propia infraestructura detrás de una URL temporal, o una prueba rápida donde quieras verificar una hipótesis sin configurar toda una tubería de subida.

Esta comodidad conlleva tres limitaciones, y todas te pasan factura en producción. La URL debe ser realmente pública, sin autenticación: una dirección protegida por un token o una cookie devolverá una página de error a xAI, que el modelo analizará diligentemente en lugar de tu documento. La descarga se suma al tiempo de procesamiento de la solicitud, lo que hace que los PDF grandes sean significativamente más lentos que con file_id. Por último, no hay caché por parte de xAI: cada llamada vuelve a descargar el archivo, por lo que un único documento consultado cincuenta veces al día cruza la red cincuenta veces.

En cuanto aparece un input_file en tu solicitud, Grok activa attachment_search sin necesidad de configuración alguna por tu parte. El procesamiento se desarrolla en cuatro pasos:

  1. Extracción de contenido del archivo: texto, tablas, estructura
  2. Indexación temporal de este contenido, durante la duración de la solicitud
  3. Búsqueda de pasajes relevantes basada en tu pregunta
  4. Inyección de extractos en el contexto del modelo

Céntrate en el adjetivo «temporal» del segundo paso, porque explica una diferencia de costes que muchos descubren demasiado tarde: el índice se reconstruye en cada llamada y desaparece después. Este es precisamente el problema que resuelven las colecciones con la indexación persistente. Ten en cuenta también que el modelo cita los pasajes que ha utilizado realmente en su respuesta, lo que te permite verificar su trabajo en lugar de fiarte de su palabra.

Combinación de varios documentos

Nada te obliga a limitarte a un archivo por solicitud. Al apilar varios bloques input_file, pides al modelo que razone sobre el conjunto:

{
  "model": "grok-4.5",
  "input": [
    {
      "type": "input_file",
      "file_id": "file_rapport_q1"
    },
    {
      "type": "input_file",
      "file_id": "file_rapport_q2"
    },
    {
      "type": "input_text",
      "text": "Compara los resultados del primer y del segundo trimestre."
    }
  ]
}

Grok analiza ambos documentos y cruza la información para responder, lo que abre la puerta a comparaciones trimestrales, revisiones de versiones sucesivas de un contrato o confrontaciones entre una especificación y su implementación.

Elección entre las dos opciones

Criteriofile_idfile_url
Subida previaSíNo
Archivo confidencialRecomendadoDesaconsejado
Consultas repetidasEficiente (1 subida)Lento (redescarga)
Archivo públicoPosibleIdeal
Gestión del ciclo de vidaTú controlasDepende del host

Puntos clave

  • input_file con file_id hace referencia a un archivo subido; file_url, a un documento público
  • La herramienta attachment_search se activa automáticamente para extraer contenido relevante
  • Puedes combinar varios archivos en una única solicitud
  • Prefiere file_id para archivos confidenciales o consultados con frecuencia
  • Prefiere file_url para documentos públicos o pruebas rápidas