Coordenadas e caixas delimitadoras

O Claude pode localizar e rotular regiões de uma imagem (por exemplo, retornando "bounding boxes" (caixas delimitadoras) para tabelas, campos de formulário, elementos de gráficos ou componentes de interface). Este guia aborda como o Claude redimensiona imagens antes de processá-las e como trabalhar com as coordenadas em pixels que ele retorna, para que caixas e pontos se alinhem com sua imagem original.

Você precisará disso para pipelines de OCR, extração de formulários, análise de gráficos, localização de elementos de interface e qualquer tarefa em que você atue sobre uma região específica de uma imagem. Para envio de imagens, formatos suportados e limites de resolução por modelo, consulte Visão.

As coordenadas seguem a convenção padrão de imagens: a origem (0, 0) é o canto superior esquerdo da imagem, com x aumentando para a direita e y aumentando para baixo. As coordenadas que o Claude retorna são posições em pixels na imagem que o Claude vê: sua imagem depois que o Claude a redimensiona para caber na resolução nativa do modelo (consulte Como o Claude redimensiona e preenche imagens). Para obter coordenadas que você possa usar diretamente, pré-redimensione sua imagem para que as coordenadas correspondam uma a uma à imagem que você tem (consulte Redimensione sua imagem antes de enviar) ou reescale as coordenadas que o Claude retorna (consulte Reescale coordenadas quando não puder pré-redimensionar).

Como o Claude redimensiona e preenche imagens

O Claude encontra o maior tamanho que preserva a proporção e satisfaz ambos os limites de imagem do modelo:

1. Limite de borda: nenhum lado excede o comprimento máximo de borda (1568 px no nível padrão, 2576 px no nível de alta resolução).
2. Limite de tokens visuais: o custo em tokens da imagem ⌈width / 28⌉ × ⌈height / 28⌉ não excede o orçamento de tokens visuais do modelo (1568 tokens no nível padrão, 4784 no nível de alta resolução).

Consulte Resolução e custo em tokens para saber quais modelos estão em qual nível.

Para quase todas as fotos e capturas de tela, o limite de tokens visuais é o que determina o tamanho final. O limite de borda prevalece apenas para imagens alongadas, como panoramas ou capturas de tela altas de celular. Calcule o tamanho com a implementação de referência em vez de escalar manualmente para o comprimento de borda: uma captura de tela de 1920×1080 é redimensionada para 1456×819, não 1568×882, e presumir o limite de borda deixa todas as coordenadas visivelmente fora do alvo.

O limite de tokens também pode acionar um redimensionamento quando nenhum lado excede o limite de borda. Ignorar isso é a causa mais comum de coordenadas desalinhadas. Por exemplo, uma página A4 digitalizada a 130 DPI tem 1075×1520 pixels: ambos os lados estão abaixo de 1568 px, mas ela custa 39 × 55 = 2145 tokens visuais, então o Claude a redimensiona para 924×1307.

O Claude então aplica "padding" (preenchimento) a toda imagem, redimensionada ou não, até o próximo múltiplo de 28 pixels nas bordas inferior e direita (924×1307 torna-se 924×1316 no exemplo). O preenchimento não contém conteúdo: o Claude percebe a imagem preenchida, mas o conteúdo da página ocupa apenas a região redimensionada sem preenchimento. Sempre normalize ou reescale pelas dimensões redimensionadas, não pelas dimensões com preenchimento; dividir pelas dimensões com preenchimento escala todas as coordenadas por uma pequena quantidade.

Redimensione sua imagem antes de enviar

A abordagem mais confiável é redimensionar sua imagem você mesmo antes de enviar, de modo que a imagem que você tem seja exatamente a imagem que o Claude vê e as coordenadas que o Claude retorna não precisem de conversão.

Primeiro verifique em qual nível de resolução seu modelo está (consulte Resolução e custo em tokens) e passe os limites de borda e de tokens correspondentes. A implementação de referência a seguir calcula o tamanho exato para o qual o Claude redimensiona uma imagem:

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)

    # Busca binária ao longo da borda maior pelo maior tamanho que preserva
    # a proporção e cabe.
    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))


# O exemplo A4 de "Como o Claude redimensiona e preenche imagens":
print(resized_size(1075, 1520))  # (924, 1307)

# Para aplicar o redimensionamento, use sua biblioteca de imagens, por exemplo Pillow:
# image.resize(resized_size(*image.size))

1. Redimensione a imagem para as dimensões retornadas pelo helper de redimensionamento. Se a imagem já cabe dentro dos limites do modelo, o helper retorna suas dimensões inalteradas e nenhum redimensionamento é necessário.
2. Envie a imagem redimensionada para a API. Não aplique preenchimento você mesmo. O Claude cuida do preenchimento, e o preenchimento não desloca a origem das coordenadas.
3. No seu prompt, peça explicitamente coordenadas em pixels. Por exemplo: "Retorne o ponto de clique do botão Submit como [x, y] em coordenadas de pixels."
4. Use as coordenadas retornadas diretamente sobre a imagem que você enviou. Se precisar de coordenadas normalizadas, divida pelas dimensões da imagem que você enviou, não pelas dimensões da imagem original nem pelas dimensões com preenchimento.

Transforme o redimensionamento em um erro com transformations

O pré-redimensionamento só protege suas coordenadas enquanto seu pipeline continua produzindo os tamanhos corretos. Uma nova fonte de imagens ou uma troca para um modelo em um nível de resolução diferente pode reintroduzir silenciosamente o redimensionamento no lado do servidor. Para transformar esse desvio silencioso em um erro visível, defina o campo opcional transformations em um bloco de conteúdo de imagem em uma requisição Messages:

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

Uma requisição cuja imagem marcada (qualquer bloco que defina "oversized_image": "error") seria redimensionada é rejeitada com um 400 invalid_request_error informando as dimensões da imagem e as maiores dimensões que cabem. Se uma imagem aciona a rejeição depende dos limites de cada modelo que a requisição nomeia: o exemplo de 1920×1080 abaixo é rejeitado por um modelo do nível padrão, mas cabe dentro do nível de alta resolução:

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"

Reescale para o alvo informado e reenvie: o alvo é o maior tamanho, na proporção da sua imagem, que todos os modelos nomeados na requisição aceitam. Como imagens marcadas interagem com o beta de fallback no lado do servidor é descrito junto com esse recurso; em todos os modos, uma imagem marcada nunca é servida redimensionada.

A configuração é por imagem. "oversized_image": "downsize" (o padrão quando o campo é omitido) mantém o redimensionamento automático conforme descrito nesta página. Cada bloco de imagem é verificado apenas em relação à sua própria configuração, portanto uma requisição pode misturar imagens cujas dimensões são essenciais (uma captura de tela na qual você vai clicar) com imagens em que o redimensionamento é inofensivo (um logotipo). O que a configuração altera e o que não altera:

• O preenchimento (que nunca descarta conteúdo), a conversão de formato e a correção de orientação prosseguem normalmente.
• Os limites rígidos (8000 px no lado mais longo e o limite por imagem mais restrito em requisições com muitas imagens) são rejeições separadas; esta configuração nunca permite que uma imagem os ultrapasse.
• Imagens fornecidas por URL ou ID de arquivo são verificadas depois que seus bytes são obtidos; essas rejeições trazem a mesma mensagem sem a posição inicial, portanto não identificam qual imagem falhou; apenas imagens base64 incorporadas são nomeadas por posição no erro.
• Páginas de PDF são rasterizadas no lado do servidor em dimensões que você não controla; o bloco document não aceita o campo (um bloco de imagem aninhado dentro do conteúdo de um documento o aceita como qualquer outro).
• Uma imagem marcada cujas dimensões não podem ser determinadas é rejeitada em vez de ser repassada: essa rejeição informa que as dimensões de origem da imagem não puderam ser determinadas, não a mensagem de redimensionamento citada acima. Nenhuma imagem que define "error" chega ao modelo redimensionada.

O endpoint de Contagem de tokens também respeita transformations, rejeitando uma imagem incorporada exatamente como a Messages API faria, para que você possa verificar se uma imagem incorporada cabe sem ser redimensionada antes de executar a inferência. A contagem rejeita imagens fornecidas por URL ou ID de arquivo em vez de obtê-las, portanto uma imagem marcada dessas fontes só é verificada no momento da chamada à Messages.

Reescale coordenadas quando não puder pré-redimensionar

Se você não puder pré-redimensionar (por exemplo, quando a imagem vem de um sistema upstream que você não pode modificar), use o helper de redimensionamento de Redimensione sua imagem antes de enviar para recuperar as dimensões que o Claude viu e, em seguida, mapeie as coordenadas que o Claude retorna para coordenadas normalizadas ou de volta para sua imagem original. A menos que uma imagem opte por um erro em vez disso, o Claude redimensiona imagens grandes demais em vez de rejeitá-las, até os limites de requisição da API. Além desses limites, a requisição falha com um erro de validação. Passe os limites de nível que correspondem ao modelo que você chamou: os limites do nível errado recuperam as dimensões redimensionadas erradas e deslocam silenciosamente todas as coordenadas. Esta abordagem requer conhecer as dimensões em pixels da imagem que você enviou, portanto não se aplica a uploads de PDF.

Capturas de tela e imagens de zoom que você retorna para os conjuntos de ferramentas de uso de computador e uso de navegador são uma exceção ao redimensionamento automático. A API rejeita uma imagem de tool_result que excede os limites do modelo com um erro de validação em vez de redimensioná-la. Redimensione essas imagens na sua aplicação antes de retorná-las e, em seguida, escale as coordenadas que o Claude retorna de volta para as dimensões da sua tela.

# Este helper chama resized_size do exemplo de redimensionamento nesta 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)


# Um canto de tabela que o Claude retorna em (462, 653.5) na página A4 redimensionada
# mapeia de volta para o original 1075x1520 assim:
rel_x, rel_y = to_relative_coordinates(462, 653.5, 1075, 1520)
print((rel_x * 1075, rel_y * 1520))  # (537.5, 760.0)

O preenchimento é aplicado apenas às bordas inferior e direita, portanto a origem não se desloca e um reescalonamento linear por eixo é suficiente. Limite as coordenadas retornadas às dimensões redimensionadas antes de reescalar, para que um ponto ligeiramente fora da imagem não possa ser mapeado para fora do seu original.

As coordenadas relativas são multiplicadas pela superfície sobre a qual você atua: a imagem original, uma digitalização em resolução total ou uma tela. Quando você atua sobre uma tela e os pixels da captura de tela diferem das coordenadas lógicas (telas HiDPI), divida também pelo fator de escala da tela. A orientação de escalonamento da ferramenta de uso de computador aborda esse padrão.

Próximos passos