Cómo hacer que Claude analice imágenes con la API

Antes de escribir código necesitas dos cosas: la librería oficial de Anthropic y una clave de acceso. Entra en console.anthropic.com, ve a la sección API Keys y crea una nueva clave. Cópiala en un lugar seguro porque solo se muestra una vez. Después instala el SDK de Python desde la terminal. En España y LATAM funciona igual: la facturación es en dólares pero puedes usar tarjetas locales. Guarda la clave como variable de entorno para no dejarla escrita en el código, algo básico de seguridad que evita subir credenciales a GitHub por accidente.

pip install anthropic

# Guarda tu clave como variable de entorno
export ANTHROPIC_API_KEY='sk-ant-tu-clave-aqui'

Claude no recibe archivos directamente: la imagen viaja dentro de la petición como texto codificado en base64. Este paso convierte tu archivo local (JPG, PNG, GIF o WebP) en esa cadena. Escribe una pequeña función que abra el archivo en modo binario y lo codifique. También necesitas conocer el 'media_type' exacto (por ejemplo image/jpeg o image/png) porque la API lo usa para interpretar los bytes. Si el tipo no coincide con el archivo real, la petición fallará. Ten en cuenta el límite de tamaño: cada imagen puede pesar hasta unos 5 MB y conviene no superar los 1568 píxeles en el lado largo para no gastar tokens de más.

import base64

def codificar_imagen(ruta):
    with open(ruta, 'rb') as f:
        return base64.standard_b64encode(f.read()).decode('utf-8')

imagen_b64 = codificar_imagen('factura.jpg')
print('Imagen codificada, longitud:', len(imagen_b64))

Ahora combinas texto e imagen en un solo mensaje. El campo 'content' del mensaje del usuario es una lista de bloques: uno de tipo 'image' con los datos base64 y otro de tipo 'text' con tu instrucción. Usamos el modelo claude-opus-4-8, que entiende imágenes de forma nativa. El orden importa poco, pero por claridad suele ponerse primero la imagen y después la pregunta. En 'max_tokens' defines cuánto puede responder Claude. Este mismo patrón sirve para describir una foto, analizar un gráfico o leer un documento escaneado: solo cambias el texto de la instrucción.

import anthropic

client = anthropic.Anthropic()  # lee la clave de la variable de entorno

mensaje = client.messages.create(
    model='claude-opus-4-8',
    max_tokens=1024,
    messages=[{
        'role': 'user',
        'content': [
            {
                'type': 'image',
                'source': {
                    'type': 'base64',
                    'media_type': 'image/jpeg',
                    'data': imagen_b64,
                },
            },
            {
                'type': 'text',
                'text': 'Describe con detalle qué aparece en esta imagen.',
            },
        ],
    }],
)

print(mensaje.content[0].text)

Uno de los usos más prácticos es leer texto de facturas, tickets, capturas o documentos escaneados. Claude no solo transcribe: entiende la estructura, así que puedes pedirle directamente los datos en formato JSON. Cambia la instrucción para que devuelva campos concretos. Esto te ahorra montar un OCR tradicional y luego parsear el resultado. Para builders en España es útil con facturas que incluyen IVA, o en LATAM con comprobantes fiscales. Pide siempre un formato explícito y da un ejemplo de las claves que quieres para que la salida sea consistente y fácil de procesar en tu aplicación.

instruccion = '''Extrae los datos de esta factura y devuélvelos
en JSON con estas claves: emisor, fecha, total, iva.
Si un dato no aparece, usa null.'''

mensaje = client.messages.create(
    model='claude-opus-4-8',
    max_tokens=1024,
    messages=[{
        'role': 'user',
        'content': [
            {'type': 'image', 'source': {'type': 'base64',
              'media_type': 'image/jpeg', 'data': imagen_b64}},
            {'type': 'text', 'text': instruccion},
        ],
    }],
)
print(mensaje.content[0].text)

Si tu imagen ya está en internet, no hace falta descargarla ni codificarla: la API acepta una fuente de tipo 'url'. Es más cómodo para prototipos y para imágenes que ya están alojadas en tu CDN o almacenamiento. La URL debe ser accesible públicamente, sin autenticación, porque los servidores de Anthropic la descargan directamente. Para datos sensibles o privados sigue usando base64, que nunca expone la imagen en una URL abierta. Este método reduce el código y es ideal cuando trabajas con catálogos de productos o imágenes ya publicadas.

mensaje = client.messages.create(
    model='claude-opus-4-8',
    max_tokens=512,
    messages=[{
        'role': 'user',
        'content': [
            {'type': 'image', 'source': {
                'type': 'url',
                'url': 'https://ejemplo.com/producto.jpg'}},
            {'type': 'text', 'text': '¿Qué producto es y qué color tiene?'},
        ],
    }],
)
print(mensaje.content[0].text)