Tutorial de la API de Claude con visión 2026: Análisis de imágenes en Python y C#

Crear software que entienda imágenes — capturas de pantalla, mockups de UI, diálogos de error, páginas de PDF, diagramas — solía significar conectar un modelo de visión separado, un servicio OCR o un pipeline personalizado. La capacidad de visión de la API de Claude cambia esto por completo. Pasas las imágenes directamente al mismo endpoint de Messages que ya usas para texto, y Claude puede describir, analizar, extraer datos y razonar sobre lo que ve.

En este tutorial voy a explicar exactamente cómo llamar a la API de visión desde Python y C#, cómo funciona el cálculo de tokens y tres patrones prácticos que usaría en producción: un pipeline de screenshot-a-bug-report, un helper de extracción de formularios y un workflow de diff visual para CI/CD. Todo el código está listo para ejecutar; solo cambia tu API key y listo.

Cómo funciona la API de visión de Claude

La capacidad de visión de la API de Claude está integrada en el endpoint messages existente. En lugar de una llamada API separada, compones un mensaje cuyo content es un array de bloques de contenido — una mezcla de bloques text e image, en el orden que tenga sentido para tu prompt. Claude lee el mensaje completo en contexto, tratando las imágenes como inputs de primera clase junto con el texto.

Según la documentación de Anthropic, se admiten dos tipos de fuente para los bloques de imagen. El primero es una URL directa: Claude obtiene la imagen en tiempo de solicitud. El segundo son datos en base64: codificas el archivo tú mismo y lo incluyes en el cuerpo de la solicitud. Las fuentes de URL son más simples cuando la imagen ya está alojada en algún lugar; base64 es lo que necesitas para archivos locales, capturas generadas o cualquier cosa que no debería ser públicamente accesible.

Los formatos de imagen admitidos son JPEG, PNG, GIF y WebP, según los docs de Anthropic. El tamaño máximo de imagen es de 20 MB por imagen y puedes incluir hasta 20 imágenes en una sola solicitud. Para el conteo de tokens de imagen, Anthropic usa un cálculo por bloques: una imagen de 1,092 × 1,092 píxeles cuesta aproximadamente 1,334 tokens según sus directrices publicadas — las imágenes de mayor resolución cuestan proporcionalmente más. Esto importa mucho cuando estás construyendo un pipeline de alto volumen; trataré la selección de modelos y los costos más abajo.

Todos los modelos Claude 3 y posteriores admiten visión, incluyendo claude-haiku-4-5, claude-sonnet-4-6 y claude-opus-4-5, según la página de descripción general de modelos de Anthropic. Haiku es la opción correcta para tareas de clasificación simples de alto volumen; Sonnet es el punto óptimo para extracción compleja; Opus vale el costo solo cuando la calidad de razonamiento es primordial.

Configurar tu entorno

Instala el SDK oficial de Anthropic para Python:

pip install anthropic

Para C#, agrega el paquete NuGet Anthropic.SDK a tu proyecto:

dotnet add package Anthropic.SDK

Guarda tu API key como variable de entorno en lugar de incluirla directamente en el código. El SDK de Python lee ANTHROPIC_API_KEY automáticamente; en C# la pasarás explícitamente al constructor del cliente. Mantén la key fuera del control de versiones — usa un archivo .env o el gestor de secretos de tu CI/CD.

# Linux / macOS
export ANTHROPIC_API_KEY="sk-ant-..."

# Windows (PowerShell)
$env:ANTHROPIC_API_KEY = "sk-ant-..."

Analizar imágenes desde URLs en Python

La llamada de visión más simple toma una URL de imagen y un prompt de texto. Aquí hay un ejemplo mínimo funcional:

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from env

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://example.com/screenshots/app-error.png",
                    },
                },
                {
                    "type": "text",
                    "text": "Describe the error shown in this screenshot. What is the likely cause and what should a developer check first?"
                }
            ],
        }
    ],
)

print(message.content[0].text)

Observa el orden de los bloques de contenido: imagen primero, luego texto. Claude maneja cualquier orden, pero poner la imagen al inicio le da al modelo contexto visual antes de leer la pregunta — un pequeño hábito de prompt engineering que vale la pena adoptar. La estructura de respuesta es idéntica a una llamada solo de texto: message.content[0].text te da la respuesta.

Para comparar dos imágenes — antes y después de un cambio de UI, o dos versiones de un formulario — agrega un segundo bloque de imagen al mismo array de contenido:

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "image", "source": {"type": "url", "url": before_url}},
                {"type": "image", "source": {"type": "url", "url": after_url}},
                {
                    "type": "text",
                    "text": "These are before/after screenshots of a UI change. List every visible difference."
                }
            ],
        }
    ],
)

Este patrón de dos imágenes es exactamente lo que usaría en un paso de regresión visual de CI/CD — antes del merge, después del merge, y un diff estructurado adjuntado automáticamente al pull request.

Subir y analizar archivos locales en Python

Cuando la imagen no está alojada públicamente, codifícala en base64 y configura el tipo de fuente correspondiente. Aquí hay un helper reutilizable que maneja la codificación y la detección del tipo de media:

import anthropic
import base64
from pathlib import Path

def analyze_local_image(image_path: str, prompt: str, model: str = "claude-sonnet-4-6") -> str:
    client = anthropic.Anthropic()

    image_data = Path(image_path).read_bytes()
    encoded = base64.standard_b64encode(image_data).decode("utf-8")

    suffix = Path(image_path).suffix.lower()
    media_type_map = {
        ".jpg": "image/jpeg",
        ".jpeg": "image/jpeg",
        ".png": "image/png",
        ".gif": "image/gif",
        ".webp": "image/webp",
    }
    media_type = media_type_map.get(suffix, "image/png")

    message = client.messages.create(
        model=model,
        max_tokens=1024,
        messages=[
            {
                "role": "user",
                "content": [
                    {
                        "type": "image",
                        "source": {
                            "type": "base64",
                            "media_type": media_type,
                            "data": encoded,
                        },
                    },
                    {"type": "text", "text": prompt},
                ],
            }
        ],
    )

    return message.content[0].text


# Uso
result = analyze_local_image(
    "/tmp/form-screenshot.png",
    "Extract all form field labels and their current values as a JSON object."
)
print(result)

Una cosa a tener en cuenta: para imágenes grandes — más de 2–3 MB — redimensiona o comprime antes de codificar. Un PNG de 10 MB de una pantalla Retina no le da a Claude información significativamente mayor que un JPEG de 1 MB del mismo contenido. Solo cuesta más tokens y ralentiza el round trip. Un paso de redimensionado con Pillow antes de codificar vale la pena agregar a cualquier pipeline de producción que procese imágenes subidas por usuarios o capturas de pantalla de alta resolución.

Una consideración adicional para aplicaciones .NET: si estás procesando capturas de pantalla capturadas por tu suite de pruebas, puedes integrar este helper directamente en tus fixtures de test. Genera el informe de error en el mismo paso en que falla la prueba, antes de que el contexto se pierda, y adjúntalo al artefacto del test runner.

Construir un pipeline de screenshot a bug report

Aquí hay un patrón valioso para una suite de pruebas de CI/CD que captura capturas de pantalla en caso de fallo y necesita una descripción de primer paso adjunta al ticket de bug. El objetivo: tomar una captura de pantalla de fallo de Playwright o Selenium, preguntarle a Claude qué está mal, y enviar la respuesta estructurada a tu issue tracker automáticamente.

import anthropic
import base64
import json
from pathlib import Path

def generate_bug_report(screenshot_path: str, test_name: str, expected_behavior: str) -> dict:
    client = anthropic.Anthropic()

    image_data = base64.standard_b64encode(
        Path(screenshot_path).read_bytes()
    ).decode("utf-8")

    prompt = (
        "You are a QA engineer reviewing a failing test screenshot.\n\n"
        f"Test name: {test_name}\n"
        f"Expected behavior: {expected_behavior}\n\n"
        "Analyze the screenshot and respond ONLY with valid JSON:\n"
        '{\n'
        '  "summary": "One-sentence description of what went wrong",\n'
        '  "visible_error": "Exact error text visible on screen, or null",\n'
        '  "ui_state": "What state the UI appears to be in",\n'
        '  "likely_cause": "Most probable root cause",\n'
        '  "suggested_checks": ["check1", "check2", "check3"]\n'
        '}'
    )

    message = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        messages=[
            {
                "role": "user",
                "content": [
                    {
                        "type": "image",
                        "source": {
                            "type": "base64",
                            "media_type": "image/png",
                            "data": image_data,
                        },
                    },
                    {"type": "text", "text": prompt},
                ],
            }
        ],
    )

    return json.loads(message.content[0].text)


report = generate_bug_report(
    screenshot_path="test-output/login-flow-failure.png",
    test_name="user_can_login_with_valid_credentials",
    expected_behavior="User is redirected to /dashboard after successful login",
)
print(json.dumps(report, indent=2))

Combinar esto con las Salidas Estructuradas de la API de Claude (en inglés) — usando el parámetro response_format — te da JSON garantizado como válido sin necesidad de parsear texto libre, que es la evolución lista para producción de este patrón. Para profundizar en cómo funcionan las salidas estructuradas de extremo a extremo, ese tutorial cubre el workflow completo con ejemplos de validación de esquemas.

Usar visión en C# / .NET

El paquete NuGet Anthropic.SDK envuelve el mismo Messages API y maneja la autenticación, los reintentos y la deserialización de respuestas. Aquí está la llamada equivalente basada en URL en C#:

using Anthropic.SDK;
using Anthropic.SDK.Messaging;

var apiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
    ?? throw new InvalidOperationException("ANTHROPIC_API_KEY not set");

var client = new AnthropicClient(apiKey);

var messages = new List<Message>
{
    new Message
    {
        Role = RoleType.User,
        Content = new List<ContentBase>
        {
            new ImageContent
            {
                Source = new ImageSource
                {
                    Type = SourceType.Url,
                    Url = "https://example.com/screenshots/app-error.png"
                }
            },
            new TextContent
            {
                Text = "What error is shown in this screenshot? Describe the likely cause."
            }
        }
    }
};

var parameters = new MessageParameters
{
    Messages = messages,
    MaxTokens = 1024,
    Model = "claude-sonnet-4-6"
};

var response = await client.Messages.GetClaudeMessageAsync(parameters);
Console.WriteLine(response.Content[0].ToString());

Para imágenes en base64 en C#, usa Type = SourceType.Base64, establece MediaType al string MIME apropiado y asigna Data a tu string en base64. El patrón es muy similar al de Python, lo que facilita portar lógica entre servicios. Esto es especialmente útil si tienes un script de procesamiento de datos en Python que estás migrando a un microservicio .NET — la estructura del prompt y el formato de los bloques de contenido son idénticos.

Si ya usas la API de Claude para tool use o function calling (en inglés), agregar visión es aditivo — los bloques de imagen funcionan junto con las definiciones de herramientas en la misma solicitud. Claude mirará la imagen, razonará sobre ella y llamará las herramientas necesarias en un solo turno. Por ejemplo: un bot de soporte al cliente que puede recibir una captura de pantalla, identificar el producto en la imagen y luego llamar a una herramienta para buscar el estado de la garantía en tu base de datos.

Casos de uso prácticos en producción

Más allá del pipeline de screenshot a bug report, aquí hay cuatro patrones que construiría en producción, cada uno con la forma de prompt que funciona para él.

Extracción de campos de formularios de documentos escaneados. Pasa una página de PDF escaneada (renderizada como imagen con una herramienta como pdf2image) y pídele a Claude que devuelva todas las etiquetas de campos y sus valores escritos a mano o mecanografiados como JSON. Esto reemplaza el OCR basado en plantillas para formularios donde el layout varía según el proveedor o la versión. Según la documentación de Anthropic, el modelo maneja texto impreso y manuscrito; la precisión en escaneos densos y de bajo contraste disminuye, así que ejecuta un paso de mejora de contraste para documentos de archivo.

Inventario de componentes de UI. Pasa una exportación de Figma o una captura de pantalla de producción y pídele a Claude que liste cada componente de UI presente — botones, inputs, modales, elementos de navegación — con sus etiquetas y estados. Útil para generar automáticamente checklists de cobertura de pruebas o starters de auditoría de accesibilidad antes de un nuevo sprint.

Captura de dashboard a tabla de datos. Pasa una captura de pantalla de un gráfico y pídele a Claude que reconstruya los datos subyacentes como CSV. No coincidirá con los datos originales con precisión en gráficos complejos, pero para comprobaciones rápidas de cordura o cuando no tienes acceso API a la fuente de datos original, es más rápido que la extracción manual por un orden de magnitud.

Triaje de logs basado en imágenes. Algunos sistemas empresariales todavía solo muestran errores en una GUI sin exportación de texto. Toma una captura del diálogo de error, pásalo por Claude, extrae el código de error y el stack trace, y regístralo como un evento estructurado. Agrega esto como un paso en tu runbook de respuesta a incidentes y tus ingenieros de guardia pasarán menos tiempo transcribiendo manualmente mensajes de error a las 2 AM.

Costos de tokens y selección de modelo

Las solicitudes de visión consumen tokens tanto para la imagen como para el texto que la acompaña. Según las directrices publicadas de Anthropic, las imágenes se tokenizan según la resolución usando un enfoque por bloques: las imágenes se dividen en bloques de 512 × 512, cada uno con un costo fijo de tokens base. Una captura de pantalla estándar de 1,080 píxeles de ancho con proporción 1:1 cuesta aproximadamente 1,300–1,700 tokens según la altura. A escala esto importa — un pipeline que procesa 10,000 capturas al día con precios de Sonnet es un gasto significativo.

Usa claude-haiku-4-5 para clasificación binaria (¿hay un error en esta captura? sí/no), OCR simple o cualquier tarea donde estés enviando cientos de imágenes y el análisis no necesita razonamiento profundo. Usa claude-sonnet-4-6 para extracción estructurada, tareas de comparación y cualquier caso donde la respuesta requiere entender el contexto en lugar de solo leer texto de la pantalla. Reserva claude-opus-4-5 para tareas de razonamiento complejo donde la precisión importa más que el costo — auditar un flujo de usuario completo en una docena de pantallas, o analizar un diagrama de arquitectura técnica complejo.

Si estás construyendo un pipeline que procesa muchas imágenes al día, combina visión con prompt caching — a través del caché de prompts de la API de Claude — para cachear tu prompt de sistema, contexto de dominio y ejemplos de few-shot. Esa parte del costo del prompt baja hasta un 90% según los docs de precios de Anthropic, mientras el costo de tokens por imagen permanece variable. La combinación puede reducir a la mitad tu gasto total en la API para workloads de visión de alto volumen.

Mejores prácticas y errores comunes

Algunas cosas que le causan problemas a la gente cuando conecta visión por primera vez.

No envíes imágenes innecesariamente grandes. Una captura 4K de un formulario de login no ayuda a Claude a leer las etiquetas de los inputs mejor que una versión 720p. Redimensiona a las dimensiones más pequeñas donde el contenido relevante todavía sea legible. La librería Pillow en Python y System.Drawing.Common en .NET manejan esto en pocas líneas. La regla general: si el texto es legible al 100% de zoom en un monitor 1080p estándar, la imagen es suficientemente grande.

Sé específico en tu prompt sobre qué mirar. "¿Qué ves?" es un prompt válido, pero "Lista cada mensaje de error, badge de advertencia y botón deshabilitado visible en esta captura de pantalla" le da a Claude una tarea clara y produce una respuesta más escaneable y estructurada. La calidad de visión mejora con la especificidad igual que la calidad de texto — este es el mismo principio detrás del prompt engineering para tareas de texto.

Maneja los errores de la misma forma que los errores de la API de texto. Las solicitudes de visión pueden fallar con los códigos de error API estándar — rate limits, servidores sobrecargados, tipo de media inválido. Envuelve cada llamada en un try/except (Python) o try/catch (C#) e implementa backoff exponencial para respuestas 529 (sobrecargado). El patrón de manejo de errores del tutorial de Streaming de la API de Claude (en inglés) aplica directamente aquí.

Prueba tus prompts en una muestra pequeña antes de escalar. Ejecuta diez imágenes representativas a través de tu prompt de extracción y verifica manualmente los outputs antes de comprometerte con un pipeline de producción. Los prompts de visión se comportan de manera diferente según el tipo de imagen — un prompt que funciona bien en capturas de pantalla limpias puede necesitar ajuste para documentos escaneados o estados de UI de bajo contraste.

Si te tomas en serio la construcción de sistemas de IA en producción basados en modelos de visión y lenguaje, recomendaría AI Engineering de Chip Huyen (~$55) — cubre pipelines multimodales, estrategias de evaluación y los tradeoffs que enfrentarás cuando las tareas de visión pasen del prototipo a la producción. Para tu setup de desarrollo, un teclado Logitech MX Keys (~$99) y un mouse Logitech MX Master 3S (~$100) son los periféricos que elegiría para alguien que pasa mucho tiempo en un IDE. Y si estás ejecutando experimentos locales en un mini PC, una Crucial 32GB DDR4 SODIMM (~$59) mantiene tu estación de trabajo cómoda con grandes datasets abiertos junto a tus herramientas.