Cómo usar la Files API de Anthropic para procesar documentos sin re-subirlos en cada llamada
Sube un contrato o informe una sola vez a la Files API beta de Anthropic, obtén su file_id y reutilízalo en todas las llamadas que necesites. Este tutorial cubre Python, manejo de errores y un pipeline real de revisión de contratos con citación de página.
Cognitiva, agencia chilena de IA, prepara este tutorial para equipos técnicos que procesan volúmenes repetitivos de documentos —contratos, facturas, informes PDF— contra la API de Claude. El problema clásico: cada llamada retransfiere el mismo archivo, lo que consume ancho de banda, eleva la latencia y complica el código. La solución es la Files API beta de Anthropic: subes el documento una sola vez, recibes un file_id permanente y lo referencias en tantas llamadas como necesites sin volver a transferir bytes. En este tutorial construirás desde cero un pipeline de revisión de contratos de proveedor. Al terminar tendrás un script en Python que (1) sube el PDF a la Files API, (2) extrae cláusulas de riesgo con citación exacta de página usando Claude, (3) maneja errores 404 y 413, y (4) borra el archivo cuando ya no lo necesitas. Tiempo estimado para tener el pipeline corriendo en local: 30 minutos.
Qué es la Files API y cuándo usarla
La Files API de Anthropic es una funcionalidad en beta que permite subir archivos a un almacenamiento seguro y obtener un identificador único (file_id) para referenciarlos en múltiples llamadas a la API de mensajes sin retransferir el contenido. El principio es sencillo: sube una vez, usa muchas veces.
Conviene usarla cuando el mismo documento aparece en más de una llamada: revisiones iterativas de un contrato, análisis de un informe financiero desde distintos ángulos, o extracción de datos de una factura con diferentes prompts. También es útil en pipelines batch donde decenas de solicitudes comparten los mismos adjuntos.
- PDF (application/pdf): análisis de documentos, contratos, informes
- Texto plano (text/plain): logs, datos estructurados en texto
- Imágenes (image/jpeg, image/png, image/gif, image/webp): análisis visual
- Datasets y otros formatos con la herramienta de ejecución de código
La Files API está disponible en la API directa de Anthropic, en Claude Platform sobre AWS y en Microsoft Foundry. No está disponible en Amazon Bedrock ni Vertex AI a la fecha de este tutorial.
Prerrequisitos
Antes de ejecutar el código necesitas lo siguiente:
- Python 3.9 o superior instalado en tu computador
- SDK oficial de Anthropic: pip install anthropic
- Clave de API de Anthropic en la variable de entorno ANTHROPIC_API_KEY
- Un PDF de prueba (en el tutorial usaremos un contrato de proveedor de ejemplo)
- Acceso a la Files API beta (disponible para todas las cuentas con acceso a la API)
La Files API requiere el header de beta files-api-2025-04-14. El SDK de Python lo gestiona automáticamente al usar client.beta.files: no necesitas configurarlo a mano.
Subir un archivo y obtener el file_id
El primer paso del pipeline es subir el PDF. La respuesta incluye el file_id que usarás en todas las llamadas posteriores.
import anthropic
import os
client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
# Subir el contrato al almacenamiento de Anthropic
with open("contrato_proveedor.pdf", "rb") as f:
uploaded = client.beta.files.upload(
file=("contrato_proveedor.pdf", f, "application/pdf"),
)
file_id = uploaded.id
print("file_id:", file_id)
# Ejemplo de salida: file_011CNha8iCJcU1wXNR6q4V8wEl objeto de respuesta incluye también el nombre del archivo, el tipo MIME, el tamaño en bytes y la fecha de creación. Guarda el file_id en tu base de datos o archivo de configuración: es el identificador permanente del documento mientras no lo borres.
Límites de almacenamiento
- Tamaño máximo por archivo: 500 MB
- Almacenamiento total por organización: 500 GB
- El file_id es accesible por todas las API keys del mismo workspace
Reutilizar el file_id en múltiples llamadas
Una vez que tienes el file_id, lo referencias directamente en el bloque de contenido de la solicitud a Messages. No hay que leer el archivo de disco ni codificarlo en base64: solo pasas el identificador.
def analizar_contrato(client, file_id, instruccion):
"""Envía una instrucción sobre el contrato ya subido."""
response = client.beta.messages.create(
model="claude-opus-4-5",
max_tokens=2048,
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": instruccion},
{
"type": "document",
"source": {
"type": "file",
"file_id": file_id,
},
"citations": {"enabled": True},
},
],
}
],
betas=["files-api-2025-04-14"],
)
return response.content[0].text
# Primera llamada: extraer cláusulas de riesgo
resultado_1 = analizar_contrato(
client,
file_id,
"Identifica todas las cláusulas de riesgo para el comprador. "
"Por cada cláusula indica el número de página y el texto literal."
)
print(resultado_1)
# Segunda llamada sobre el mismo archivo — sin retransferirlo
resultado_2 = analizar_contrato(
client,
file_id,
"Resume las condiciones de pago y penalidades por incumplimiento "
"con referencia exacta al número de cláusula."
)
print(resultado_2)El parámetro citations: {enabled: True} activa las citas de fuente: Claude indicará el número de página o el fragmento exacto del documento donde encontró cada dato. Para contratos esto es fundamental: permite verificar cada hallazgo contra el original.
Pipeline completo de revisión de contratos
El siguiente script encapsula el flujo completo: subida, múltiples análisis, reporte final y borrado del archivo. Está diseñado para correr en local en menos de 30 minutos con un contrato real.
import anthropic
import os
import json
def revisar_contrato_proveedor(ruta_pdf: str) -> dict:
"""
Pipeline de revisión de contratos con la Files API de Anthropic.
Retorna un dict con los hallazgos por categoría.
"""
client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
# 1. Subir el PDF una sola vez
print("Subiendo contrato...")
with open(ruta_pdf, "rb") as f:
uploaded = client.beta.files.upload(
file=(os.path.basename(ruta_pdf), f, "application/pdf"),
)
file_id = uploaded.id
print("file_id obtenido:", file_id)
hallazgos = {}
# 2. Análisis 1 — cláusulas de riesgo
print("Analizando cláusulas de riesgo...")
hallazgos["riesgo"] = _llamar(client, file_id,
"Lista todas las cláusulas que representen riesgo legal o financiero para "
"el comprador. Formato: número de cláusula | página | texto literal | "
"tipo de riesgo (legal/financiero/operacional).")
# 3. Análisis 2 — condiciones de pago
print("Extrayendo condiciones de pago...")
hallazgos["pagos"] = _llamar(client, file_id,
"Extrae todas las condiciones de pago, plazos, montos y penalidades. "
"Cita el número de cláusula y la página exacta de cada punto.")
# 4. Análisis 3 — vigencia y renovación
print("Verificando vigencia y renovación...")
hallazgos["vigencia"] = _llamar(client, file_id,
"¿Cuál es la vigencia del contrato? ¿Se renueva automáticamente? "
"¿Cuál es el plazo de aviso para no renovar? Cita páginas exactas.")
# 5. Borrar el archivo del almacenamiento
print("Borrando archivo del almacenamiento...")
client.beta.files.delete(file_id)
print("Archivo eliminado.")
return hallazgos
def _llamar(client, file_id: str, instruccion: str) -> str:
resp = client.beta.messages.create(
model="claude-opus-4-5",
max_tokens=2048,
messages=[{
"role": "user",
"content": [
{"type": "text", "text": instruccion},
{
"type": "document",
"source": {"type": "file", "file_id": file_id},
"citations": {"enabled": True},
},
],
}],
betas=["files-api-2025-04-14"],
)
return resp.content[0].text
if __name__ == "__main__":
resultado = revisar_contrato_proveedor("contrato_proveedor.pdf")
print(json.dumps(resultado, ensure_ascii=False, indent=2))Manejo de errores: 404, 413 y otros
La Files API retorna errores HTTP estándar con un cuerpo JSON descriptivo. Los más frecuentes en producción son 404 cuando el file_id ya no existe (fue borrado o expiró) y 413 cuando el archivo supera el límite de 500 MB.
import anthropic
from anthropic import APIStatusError
def llamar_con_manejo_errores(client, file_id: str, instruccion: str) -> str:
try:
resp = client.beta.messages.create(
model="claude-opus-4-5",
max_tokens=2048,
messages=[{
"role": "user",
"content": [
{"type": "text", "text": instruccion},
{
"type": "document",
"source": {"type": "file", "file_id": file_id},
},
],
}],
betas=["files-api-2025-04-14"],
)
return resp.content[0].text
except APIStatusError as e:
if e.status_code == 404:
# El archivo no existe: volver a subirlo
raise FileNotFoundError(
"file_id no encontrado. El archivo fue eliminado. "
"Vuelve a subirlo con client.beta.files.upload()."
) from e
elif e.status_code == 413:
# El archivo supera el límite de 500 MB
raise ValueError(
"El archivo supera el límite de 500 MB. "
"Divide el PDF en secciones antes de subirlo."
) from e
elif e.status_code == 429:
# Rate limit: la beta permite ~100 solicitudes por minuto
raise RuntimeError("Rate limit alcanzado. Agrega un retry con backoff.") from e
else:
raiseResumen de errores comunes
| Código HTTP | Causa | Acción recomendada |
|---|---|---|
| 404 | file_id no existe o fue eliminado | Volver a subir el archivo y actualizar el file_id almacenado |
| 400 (invalid file type) | Tipo MIME no coincide con el bloque de contenido | Verificar que el PDF use application/pdf y el bloque document |
| 400 (context window) | Archivo de texto plano muy grande para el contexto | Dividir el documento en fragmentos más pequeños |
| 413 | Archivo supera los 500 MB | Comprimir o dividir el archivo antes de subirlo |
| 403 | Organización alcanzó 500 GB de almacenamiento | Borrar archivos no utilizados con files.delete() |
| 429 | Límite de ~100 solicitudes por minuto en beta | Agregar retry con backoff exponencial |
Ciclo de vida de los archivos: TTL, borrado y buenas prácticas
A diferencia de otras APIs con TTL automático, los archivos subidos a la Files API persisten indefinidamente hasta que los eliminas de forma explícita. No hay expiración automática. Esto significa que si no borras los archivos, acumulan almacenamiento y potencialmente costos de retención según la política de datos de Anthropic.
- Borra el archivo tan pronto terminen todos los análisis del pipeline
- Almacena el file_id en tu base de datos junto con la fecha de subida para auditar qué archivos tienes activos
- Usa client.beta.files.list() periódicamente para detectar archivos huérfanos
- Para documentos recurrentes (plantillas, políticas internas), mantén el file_id en una tabla de referencias y reutilízalo sin volver a subirlos
- Los archivos subidos son accesibles por cualquier API key del mismo workspace: considera quién tiene acceso a tu organización
Las operaciones de gestión de archivos (subida, listado, metadatos, eliminación, descarga) son gratuitas. El costo se genera únicamente al usar el file_id en solicitudes a Messages, donde el contenido del archivo se cobra como tokens de entrada al precio estándar del modelo elegido.
Verificar qué archivos tienes activos
import anthropic
import os
client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
# Listar todos los archivos del workspace
archivos = client.beta.files.list()
print("Archivos activos en el workspace:")
for archivo in archivos.data:
print(" -", archivo.id, "|", archivo.filename, "|", archivo.created_at)
# Obtener metadatos de un archivo específico
file_id = "file_011CNha8iCJcU1wXNR6q4V8w" # reemplaza con tu file_id
meta = client.beta.files.retrieve_metadata(file_id)
print("Nombre:", meta.filename)
print("Tamaño:", meta.size_bytes, "bytes")
print("Creado:", meta.created_at)
# Eliminar un archivo
result = client.beta.files.delete(file_id)
print("Archivo eliminado:", result)Checklist de validación antes de pasar a producción
Antes de desplegar el pipeline en un entorno productivo, valida cada punto de esta lista:
- El file_id se almacena en base de datos junto con fecha de subida y nombre del archivo original
- Existe un mecanismo de retry con backoff para errores 429 (rate limit en beta: ~100 req/min)
- El pipeline borra el archivo con files.delete() al finalizar si el documento no debe conservarse
- Los errores 404 activan una re-subida automática del archivo y actualización del file_id
- Los archivos de más de 400 MB se dividen antes de subirlos para evitar errores de contexto
- El ANTHROPIC_API_KEY está en variable de entorno, nunca en el código fuente
- Las respuestas con citations tienen logging para auditar qué página respaldó cada hallazgo
- Se probó con un PDF real en local antes del deploy
Preguntas frecuentes
Da el siguiente paso
Hablemos
Cuéntanos sobre tu negocio. Respondemos en 24 horas.
Otros canales
Escríbenos por WhatsApp o agenda una llamada de 30 minutos.