Coordenadas y cuadros delimitadores

Claude puede localizar y etiquetar regiones de una imagen (por ejemplo, devolviendo "bounding boxes" (cuadros delimitadores) para tablas, campos de formulario, elementos de gráficos o componentes de interfaz de usuario). Esta guía cubre cómo Claude redimensiona las imágenes antes de procesarlas y cómo trabajar con las coordenadas en píxeles que devuelve, de modo que los cuadros y puntos se alineen con tu imagen original.

Necesitarás esto para pipelines de OCR, extracción de formularios, análisis de gráficos, localización de elementos de interfaz de usuario y cualquier tarea en la que actúes sobre una región específica de una imagen. Para el envío de imágenes, los formatos compatibles y los límites de resolución por modelo, consulta Visión.

Las coordenadas siguen la convención estándar de imágenes: el origen (0, 0) es la esquina superior izquierda de la imagen, con x aumentando hacia la derecha e y aumentando hacia abajo. Las coordenadas que Claude devuelve son posiciones en píxeles en la imagen que Claude ve: tu imagen después de que Claude la redimensiona para ajustarse a la resolución nativa del modelo (consulta Cómo Claude redimensiona y rellena las imágenes). Para obtener coordenadas que puedas usar directamente, redimensiona previamente tu imagen para que las coordenadas se correspondan uno a uno con la imagen que tienes (consulta Redimensiona tu imagen antes de subirla), o reescala las coordenadas que Claude devuelve (consulta Reescala las coordenadas cuando no puedas redimensionar previamente).

Cómo Claude redimensiona y rellena las imágenes

Claude encuentra el tamaño más grande que preserva la relación de aspecto y que satisface ambos límites de imagen del modelo:

1. Límite de borde: ningún lado excede la longitud máxima de borde (1568 px en el nivel estándar, 2576 px en el nivel de alta resolución).
2. Límite de tokens visuales: el costo en tokens de la imagen ⌈width / 28⌉ × ⌈height / 28⌉ no excede el presupuesto de tokens visuales del modelo (1568 tokens en el nivel estándar, 4784 en el nivel de alta resolución).

Consulta Resolución y costo en tokens para saber qué modelos están en qué nivel.

Para casi todas las fotos y capturas de pantalla, el límite de tokens visuales es lo que determina el tamaño final. El límite de borde solo prevalece para imágenes alargadas como panoramas o capturas de pantalla altas de teléfonos. Calcula el tamaño con la implementación de referencia en lugar de escalar manualmente a la longitud de borde: una captura de pantalla de 1920×1080 se redimensiona a 1456×819, no a 1568×882, y asumir el límite de borde deja cada coordenada notablemente fuera de su objetivo.

El límite de tokens también puede provocar un redimensionamiento cuando ningún lado excede el límite de borde. Pasar esto por alto es la causa más común de coordenadas desalineadas. Por ejemplo, una página A4 escaneada a 130 DPI mide 1075×1520 píxeles: ambos lados están por debajo de 1568 px, pero cuesta 39 × 55 = 2145 tokens visuales, por lo que Claude la redimensiona a 924×1307.

Luego Claude rellena cada imagen, redimensionada o no, hasta el siguiente múltiplo de 28 píxeles en los bordes inferior y derecho (924×1307 se convierte en 924×1316 en el ejemplo). El "padding" (relleno) no contiene contenido: Claude percibe la imagen rellenada, pero el contenido de la página solo ocupa la región redimensionada sin relleno. Normaliza o reescala siempre según las dimensiones redimensionadas, no las dimensiones con relleno; dividir por las dimensiones con relleno escala cada coordenada en una pequeña cantidad.

Redimensiona tu imagen antes de subirla

El enfoque más confiable es redimensionar tú mismo la imagen antes de subirla, de modo que la imagen que tienes sea exactamente la imagen que Claude ve y las coordenadas que Claude devuelve no necesiten conversión.

Primero verifica en qué nivel de resolución está tu modelo (consulta Resolución y costo en tokens) y pasa los límites de borde y de tokens correspondientes. La siguiente implementación de referencia calcula el tamaño exacto al que Claude redimensiona una imagen:

import math


def count_image_tokens(width: int, height: int) -> int:
    """Visual tokens consumed by an image: one token per 28x28 pixel patch."""
    return math.ceil(width / 28) * math.ceil(height / 28)


def resized_size(
    width: int,
    height: int,
    max_edge: int = 1568,
    max_tokens: int = 1568,
) -> tuple[int, int]:
    """The size Claude resizes an image to before padding.

    Defaults are for the standard resolution tier. For high-resolution-tier
    models, use max_edge=2576 and max_tokens=4784. Returns (width, height).
    Images that already fit within the limits are returned unchanged.
    """

    def fits(w: int, h: int) -> bool:
        return (
            math.ceil(w / 28) * 28 <= max_edge
            and math.ceil(h / 28) * 28 <= max_edge
            and count_image_tokens(w, h) <= max_tokens
        )

    if fits(width, height):
        return (width, height)
    if height > width:
        resized_h, resized_w = resized_size(height, width, max_edge, max_tokens)
        return (resized_w, resized_h)

    # Búsqueda binaria a lo largo del borde largo para el mayor tamaño que preserve
    # la relación de aspecto y quepa.
    aspect_ratio = width / height
    lo, hi = 1, width  # lo always fits; hi never fits
    while lo + 1 < hi:
        mid = (lo + hi) // 2
        if fits(mid, max(round(mid / aspect_ratio), 1)):
            lo = mid
        else:
            hi = mid
    return (lo, max(round(lo / aspect_ratio), 1))


# El ejemplo A4 de "Cómo Claude redimensiona y rellena imágenes":
print(resized_size(1075, 1520))  # (924, 1307)

# Para aplicar el redimensionamiento, usa tu biblioteca de imágenes, por ejemplo Pillow:
# image.resize(resized_size(*image.size))

1. Redimensiona la imagen a las dimensiones devueltas por el helper de redimensionamiento. Si la imagen ya cabe dentro de los límites del modelo, el helper devuelve sus dimensiones sin cambios y no se necesita redimensionar.
2. Envía la imagen redimensionada a la API. No la rellenes tú mismo. Claude se encarga del relleno, y el relleno no desplaza el origen de coordenadas.
3. En tu prompt, pide explícitamente coordenadas en píxeles. Por ejemplo: "Devuelve el punto de clic para el botón Submit como [x, y] en coordenadas en píxeles."
4. Usa las coordenadas devueltas directamente sobre la imagen que enviaste. Si necesitas coordenadas normalizadas, divide por las dimensiones de la imagen que enviaste, no por las dimensiones de la imagen original ni por las dimensiones con relleno.

Convierte el redimensionamiento en un error con transformations

El redimensionamiento previo solo protege tus coordenadas mientras tu pipeline siga produciendo los tamaños correctos. Una nueva fuente de imágenes o un cambio a un modelo de un nivel de resolución diferente puede reintroducir silenciosamente el redimensionamiento del lado del servidor. Para convertir esa desviación silenciosa en un error visible, establece el campo opcional transformations en un bloque de contenido de imagen en una solicitud de Messages:

{
  "type": "image",
  "source": { "type": "base64", "media_type": "image/png", "data": "..." },
  "transformations": { "oversized_image": "error" }
}

Una solicitud cuya imagen marcada (cualquier bloque que establezca "oversized_image": "error") sería redimensionada se rechaza con un 400 invalid_request_error que indica las dimensiones de la imagen y las dimensiones más grandes que caben. Que una imagen provoque el rechazo depende de los límites de cada modelo que la solicitud nombra: el ejemplo de 1920×1080 a continuación es rechazado por un modelo del nivel estándar pero cabe dentro del nivel de alta resolución:

messages.0.content.0: image dimensions 1920x1080 exceed the maximum image size of a model named on this request and would be downsized to 1456x819; scale the image to at most 1456x819 or set the image's oversized_image setting to "downsize"

Reescala al objetivo informado y vuelve a enviar: el objetivo es el tamaño más grande, con la relación de aspecto de tu imagen, que todos los modelos nombrados en la solicitud aceptan. Cómo interactúan las imágenes marcadas con la beta de fallback del lado del servidor se describe junto con esa funcionalidad; en todos los modos, una imagen marcada nunca se sirve redimensionada.

La configuración es por imagen. "oversized_image": "downsize" (el valor predeterminado cuando se omite el campo) mantiene el redimensionamiento automático tal como se describe en esta página. Cada bloque de imagen se verifica solo contra su propia configuración, por lo que una solicitud puede mezclar imágenes cuyas dimensiones son determinantes (una captura de pantalla sobre la que harás clic) con imágenes donde el redimensionamiento es inofensivo (un logotipo). Lo que la configuración cambia y lo que no:

• El relleno (que nunca descarta contenido), la conversión de formato y la corrección de orientación proceden como de costumbre.
• Los límites estrictos (8000 px en el lado más largo, y el límite por imagen más estricto en solicitudes con muchas imágenes) son rechazos independientes; esta configuración nunca permite que una imagen los supere.
• Las imágenes proporcionadas por URL o ID de archivo se verifican una vez que se han obtenido sus bytes; esos rechazos llevan el mismo mensaje sin la posición inicial, por lo que no identifican qué imagen falló; solo las imágenes base64 incrustadas se nombran por posición en el error.
• Las páginas PDF se rasterizan del lado del servidor con dimensiones que no controlas; el bloque document no acepta el campo (un bloque de imagen anidado dentro del contenido de un documento lo acepta como cualquier otro).
• Una imagen marcada cuyas dimensiones no pueden determinarse se rechaza en lugar de dejarse pasar: ese rechazo informa que no se pudieron determinar las dimensiones de origen de la imagen, no el mensaje de redimensionamiento citado arriba. Ninguna imagen que establezca "error" llega al modelo redimensionada.

El endpoint de Conteo de tokens también respeta transformations y rechaza una imagen incrustada exactamente como lo haría la Messages API, por lo que puedes verificar si una imagen incrustada cabe sin ser redimensionada antes de ejecutar la inferencia. El conteo rechaza las imágenes proporcionadas por URL o ID de archivo en lugar de obtenerlas, por lo que una imagen marcada de esas fuentes solo se verifica en el momento de Messages.

Reescala las coordenadas cuando no puedas redimensionar previamente

Si no puedes redimensionar previamente (por ejemplo, cuando la imagen proviene de un sistema upstream que no puedes modificar), usa el helper de redimensionamiento de Redimensiona tu imagen antes de subirla para recuperar las dimensiones que Claude vio, y luego mapea las coordenadas que Claude devuelve a coordenadas normalizadas o de vuelta a tu imagen original. A menos que una imagen opte por un error en su lugar, Claude redimensiona las imágenes demasiado grandes en lugar de rechazarlas, hasta los límites de solicitud de la API. Más allá de esos límites, la solicitud falla con un error de validación. Pasa los límites de nivel que correspondan al modelo que llamaste: los límites del nivel equivocado recuperan las dimensiones redimensionadas equivocadas y desplazan silenciosamente cada coordenada. Este enfoque requiere conocer las dimensiones en píxeles de la imagen que subiste, por lo que no aplica a las subidas de PDF.

Las capturas de pantalla y las imágenes de zoom que devuelves a los conjuntos de herramientas de uso de computadora y uso de navegador son una excepción al redimensionamiento automático. La API rechaza una imagen de tool_result que exceda los límites del modelo con un error de validación en lugar de redimensionarla. Redimensiona esas imágenes en tu aplicación antes de devolverlas, y luego escala las coordenadas que Claude devuelve de vuelta a las dimensiones de tu pantalla.

# Este helper llama a resized_size del ejemplo de redimensionamiento en esta página.
def to_relative_coordinates(
    x: float,
    y: float,
    original_width: int,
    original_height: int,
    max_edge: int = 1568,
    max_tokens: int = 1568,
) -> tuple[float, float]:
    """Map a pixel coordinate returned by Claude to relative coordinates in [0, 1].

    Pass the dimensions of the image you uploaded. For high-resolution-tier
    models, use max_edge=2576 and max_tokens=4784.
    """
    resized_w, resized_h = resized_size(
        original_width, original_height, max_edge, max_tokens
    )
    return (x / resized_w, y / resized_h)


# Una esquina de tabla que Claude devuelve en (462, 653.5) en la página A4 redimensionada
# se mapea de vuelta al original de 1075x1520 así:
rel_x, rel_y = to_relative_coordinates(462, 653.5, 1075, 1520)
print((rel_x * 1075, rel_y * 1520))  # (537.5, 760.0)

El relleno se aplica solo a los bordes inferior y derecho, por lo que el origen no se desplaza y un reescalado lineal por eje es suficiente. Limita las coordenadas devueltas a las dimensiones redimensionadas antes de reescalar, de modo que un punto ligeramente fuera de la imagen no pueda mapearse fuera de tu original.

Las coordenadas relativas se multiplican por cualquier superficie sobre la que actúes: la imagen original, un escaneo a resolución completa o una pantalla. Cuando actúas sobre una pantalla y los píxeles de la captura difieren de las coordenadas lógicas (pantallas HiDPI), divide también por el factor de escala de la pantalla. La guía de escalado de la herramienta de uso de computadora cubre ese patrón.

Próximos pasos