input_file y attachment_search en la API de Responses
En esta página
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.
Qué hace attachment_search
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:
- Extracción de contenido del archivo: texto, tablas, estructura
- Indexación temporal de este contenido, durante la duración de la solicitud
- Búsqueda de pasajes relevantes basada en tu pregunta
- 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
| Criterio | file_id | file_url |
|---|---|---|
| Subida previa | Sí | No |
| Archivo confidencial | Recomendado | Desaconsejado |
| Consultas repetidas | Eficiente (1 subida) | Lento (redescarga) |
| Archivo público | Posible | Ideal |
| Gestión del ciclo de vida | Tú controlas | Depende del host |
Puntos clave
input_fileconfile_idhace referencia a un archivo subido;file_url, a un documento público- La herramienta
attachment_searchse activa automáticamente para extraer contenido relevante - Puedes combinar varios archivos en una única solicitud
- Prefiere
file_idpara archivos confidenciales o consultados con frecuencia - Prefiere
file_urlpara documentos públicos o pruebas rápidas