Files API de Claude
La Files API de Claude es el servicio de Anthropic que permite subir un archivo una sola vez, obtener un identificador file_id y reutilizarlo en múltiples peticiones a la API sin volver a enviar su contenido.
La Files API es el endpoint de la plataforma de Anthropic para subir, almacenar, listar y borrar archivos que después se referencian desde la API de Mensajes mediante un file_id. En lugar de codificar un PDF en base64 y mandarlo entero en cada llamada, lo subes una vez y lo citas por su identificador tantas veces como quieras. Es la pieza que convierte los documentos en recursos persistentes de tu aplicación, no en carga repetida dentro de cada request.
Cómo funciona
El flujo tiene dos pasos. Primero haces un POST /v1/files con el archivo en multipart; la respuesta devuelve metadatos (id, nombre, tipo MIME, tamaño). Después, en la petición a Messages, incluyes un bloque de contenido cuyo source es de tipo file:
file = client.beta.files.upload(
file=("contrato.pdf", open("contrato.pdf", "rb"), "application/pdf")
)
resp = client.beta.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
betas=["files-api-2025-04-14"],
messages=[{"role": "user", "content": [
{"type": "text", "text": "Resume las cláusulas de penalización"},
{"type": "document", "source": {"type": "file", "file_id": file.id}}
]}]
)El tipo de bloque depende del archivo: document para PDF y texto plano, image para imágenes y container_upload cuando quieres que la herramienta de ejecución de código trabaje con formatos como CSV o Excel. La API se lanzó en beta con la cabecera anthropic-beta: files-api-2025-04-14; consulta la documentación vigente por si ese requisito ha cambiado.
Además de subir, puedes listar archivos, consultar metadatos y eliminarlos. Los archivos pertenecen al workspace de la API key que los creó y persisten hasta que los borras.
Por qué importa
- Peticiones más ligeras: no reenvías megas de base64 en cada turno de una conversación larga ni en cada iteración de un agente.
- Arquitectura más limpia: tu backend guarda
file_iden base de datos en lugar de rutas a ficheros que hay que releer y codificar. - Salidas de Claude como archivos: los ficheros que genera la ejecución de código (un gráfico, un Excel procesado) se recuperan descargándolos por su id.
Lo que no cambia es el consumo de contexto: cada vez que referencias un archivo, su contenido se procesa como tokens de entrada. Por eso suele combinarse con prompt caching cuando el mismo documento se consulta muchas veces. Es el tipo de decisión de diseño que se trabaja al construir aplicaciones completas sobre la API de Claude.
Límites y costes
- Tamaño máximo por archivo: 500 MB en el momento de su lanzamiento.
- Almacenamiento total por organización: 100 GB, según la documentación inicial.
- Las operaciones de subir, listar o borrar no se facturan; pagas los tokens cuando el archivo entra en un mensaje.
- Disponibilidad: nació en la API directa de Anthropic; verifica si tu proveedor cloud (Bedrock, Vertex AI) la soporta antes de depender de ella.
Errores comunes
- Pensar que es RAG: la Files API no indexa ni busca. Si el archivo no cabe en la ventana de contexto, subirlo no lo soluciona.
- Esperar descargar lo que subiste: la descarga está pensada para archivos generados por Claude o sus herramientas, no para recuperar tus propios uploads.
- Olvidar la limpieza: los archivos no caducan solos; sin una política de borrado, acumulas datos sensibles y cuota.
- Usar un tipo de bloque incorrecto: un CSV como
documentfalla; requiere ejecución de código concontainer_upload.
Preguntas frecuentes
¿Subir un archivo con la Files API ahorra tokens?
No. Ahorra ancho de banda y simplifica el código, pero el contenido del archivo se cuenta como tokens de entrada cada vez que lo referencias. Para abaratar consultas repetidas sobre el mismo documento conviene activar prompt caching.
¿Cuánto tiempo se guardan los archivos subidos?
Persisten hasta que los eliminas explícitamente con el endpoint de borrado. No hay caducidad automática, así que es responsabilidad de tu aplicación gestionar su ciclo de vida.
¿Qué formatos puedo usar directamente en un mensaje?
PDF y texto plano como bloque document, e imágenes como bloque image. Otros formatos como CSV, Excel o JSON se procesan a través de la herramienta de ejecución de código mediante container_upload.
¿Los archivos son visibles para otras API keys?
Están ligados al workspace de la API key que los creó, por lo que otras claves del mismo workspace pueden acceder a ellos, pero no las de otros workspaces.