Cómo hacer que Claude lea un PDF (paso a paso)

Primero necesitas el SDK oficial de Anthropic para Python. Abre tu terminal y crea un entorno virtual para no ensuciar tu instalación global (buena práctica en cualquier proyecto). Luego instala el paquete. El SDK maneja toda la autenticación y las llamadas HTTP por ti, así no tienes que construir peticiones manualmente. Si usas Windows, los comandos de activación del entorno virtual cambian ligeramente (usa 'venv\Scripts\activate' en lugar de 'source'). En macOS y Linux funciona el comando tal cual aparece abajo. Verifica que la instalación fue correcta ejecutando 'pip show anthropic' — deberías ver la versión instalada.

python3 -m venv venv
source venv/bin/activate
pip install anthropic

Nunca escribas tu API key directamente en el código, porque si subes el archivo a GitHub la expondrás públicamente y cualquiera podrá gastar tus créditos. La forma correcta es usar una variable de entorno. Ve a console.anthropic.com, entra en 'API Keys' y crea una nueva. Cópiala (solo se muestra una vez) y guárdala en tu terminal con el comando de abajo. El SDK de Anthropic lee automáticamente la variable ANTHROPIC_API_KEY, así que no necesitas pasarla manualmente al cliente. Para que persista entre sesiones, añade esa línea a tu archivo ~/.bashrc o ~/.zshrc en macOS/Linux.

export ANTHROPIC_API_KEY='sk-ant-tu-clave-aqui'

La API de Claude acepta PDFs directamente como documentos. Para enviarlos, hay que leer el archivo en modo binario y codificarlo en base64, que es la forma estándar de transmitir archivos binarios dentro de una petición JSON. Claude puede procesar tanto el texto como los elementos visuales del PDF (tablas, gráficos, diseño), lo cual es una gran ventaja frente a extractores de texto tradicionales que pierden el formato. El límite actual es de 32 MB por petición y hasta 100 páginas por documento. Guarda tu PDF en la misma carpeta que el script y ajusta el nombre del archivo. Este paso solo prepara los datos; el envío lo haremos en el siguiente paso.

import base64

with open("documento.pdf", "rb") as f:
    pdf_data = base64.standard_b64encode(f.read()).decode("utf-8")

print(f"PDF codificado: {len(pdf_data)} caracteres")

Ahora construimos la petición completa. El mensaje incluye dos bloques de contenido: uno de tipo 'document' con el PDF codificado, y otro de tipo 'text' con tu pregunta. Usamos el modelo claude-opus-4-8, el más capaz para análisis de documentos complejos. El parámetro max_tokens controla cuánto puede responder Claude; 1024 es suficiente para un resumen, súbelo si necesitas respuestas largas. Fíjate en que el PDF va como source de tipo 'base64' con media_type 'application/pdf'. Puedes cambiar la pregunta del bloque de texto por lo que necesites: pedir un resumen, extraer datos concretos, traducir secciones o comparar cláusulas. Ejecuta el script y verás la respuesta de Claude impresa en tu terminal.

import anthropic

client = anthropic.Anthropic()

mensaje = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": pdf_data,
                    },
                },
                {
                    "type": "text",
                    "text": "Resume este documento en 5 puntos clave.",
                },
            ],
        }
    ],
)

print(mensaje.content[0].text)

El verdadero poder llega cuando haces preguntas concretas en lugar de resúmenes genéricos. Puedes pedir a Claude que extraiga campos específicos, verifique cifras o responda dudas puntuales sobre el contenido. Para facturas o documentos con datos estructurados, pide la respuesta en formato JSON para poder procesarla luego en tu código. Esto convierte a Claude en un extractor de datos inteligente: entiende el contexto aunque los campos estén en posiciones distintas o con nombres diferentes. Reutiliza la variable pdf_data del paso 3 (no vuelvas a codificar el archivo). Abajo tienes un ejemplo pensado para una factura española con IVA, pero adáptalo a tu caso de uso.

mensaje = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": pdf_data,
                    },
                },
                {
                    "type": "text",
                    "text": "Extrae en JSON: numero_factura, fecha, base_imponible, iva, total. Responde solo con el JSON.",
                },
            ],
        }
    ],
)

print(mensaje.content[0].text)

Cada petición con un PDF consume tokens según el número de páginas y el texto que contenga, así que conviene vigilar el uso. El objeto de respuesta incluye 'usage' con los tokens de entrada y salida, útil para estimar el coste antes de escalar. Si trabajas con muchos PDFs iguales, activa el prompt caching para reducir costes hasta un 90% en las llamadas repetidas. Envuelve tus llamadas en un try/except para capturar errores de red o de la API sin que el script se caiga. Los errores más comunes son: clave no configurada (autenticación), PDF demasiado grande (400) y límites de velocidad (429). Con este manejo básico ya tienes un flujo robusto listo para producción.

try:
    mensaje = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=1024,
        messages=[{"role": "user", "content": [
            {"type": "document", "source": {"type": "base64",
             "media_type": "application/pdf", "data": pdf_data}},
            {"type": "text", "text": "Resume el documento."},
        ]}],
    )
    print(mensaje.content[0].text)
    print(f"Tokens entrada: {mensaje.usage.input_tokens}")
    print(f"Tokens salida: {mensaje.usage.output_tokens}")
except anthropic.APIError as e:
    print(f"Error de la API: {e}")