Domingo, 22 de noviembre de 2026  ·  Español
Producto

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.

También: API de archivos de Claude · Files API · Claude Files API · Anthropic Files API · file_id Claude
Daniel Puentes Prias
Consultor de IA · Actualizado el 14 de noviembre de 2026

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

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

Errores comunes

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.

Términos relacionados

Fuentes