Visão

Este guia descreve como trabalhar com imagens no Claude, incluindo melhores práticas, exemplos de código e limitações a serem consideradas.



Como usar a visão

Use as capacidades de visão do Claude através de:

• claude.ai. Faça upload de uma imagem como faria com um arquivo, ou arraste e solte uma imagem diretamente na janela de chat.
• O Console Workbench. Um botão para adicionar imagens aparece no canto superior direito de cada bloco de mensagem do Usuário.
• Requisição de API. Veja os exemplos neste guia.

Várias imagens podem ser incluídas em uma única requisição, e o Claude as analisará em conjunto ao formular sua resposta. Isso pode ser útil para comparar ou contrastar imagens.



Antes de fazer upload



Limites gerais

O número máximo de imagens por mensagem ou requisição é:

• 20 por mensagem no claude.ai.
• 100 por requisição na API, para modelos com uma janela de contexto de 200k tokens.
• 600 por requisição na API, para todos os outros modelos.

As dimensões máximas por imagem são 8000x8000 px. Se você enviar mais de 20 imagens em uma requisição de API, esse limite é reduzido para 2000x2000 px.

O tamanho máximo por imagem é:

• 10 MB (codificada em base64) ao usar a API do Claude diretamente.
• 5 MB (codificada em base64) no Amazon Bedrock e Vertex AI.
• 10 MB no claude.ai.



Avaliar o tamanho da imagem

O Claude visualiza imagens em patches em vez de pixels. Cada patch é um bloco de 28×28 pixels da imagem, chamado de token visual. Uma imagem, portanto, custa ⌈width / 28⌉ × ⌈height / 28⌉ tokens visuais.

Se o Claude receber uma imagem muito grande, ele a redimensiona. A resolução nativa máxima de imagem é:

• Para Claude Fable 5 e Claude Mythos 5: 4784 tokens, e no máximo 2576 pixels na borda mais longa.
• Para Claude Opus 4.8: 4784 tokens, e no máximo 2576 pixels na borda mais longa.
• Para Claude Opus 4.7: 4784 tokens, e no máximo 2576 pixels na borda mais longa.
• Para outros modelos: 1568 tokens, e no máximo 1568 pixels na borda mais longa.

Para minimizar a latência e simplificar fluxos de trabalho baseados em coordenadas, você deve preferir redimensionar as imagens antes de fazer upload.



Calcular custos de imagem

Cada imagem que você inclui em uma requisição ao Claude conta para seu uso de tokens. Para calcular o custo aproximado, multiplique a contagem de tokens visuais da imagem (veja Avaliar o tamanho da imagem) pelo preço por token do modelo que você está usando.

Aqui estão exemplos de tokenização e custos aproximados para diferentes tamanhos de imagem dentro das restrições de tamanho da API, com base no preço por token do Claude Sonnet 4.6 de $3 por milhão de tokens de entrada:

Observe que as três últimas imagens excedem a resolução nativa e são reduzidas antes do processamento (para 1456x819 px, 1270x952 px e 1456x819 px respectivamente), o que limita seu custo em tokens. A imagem 4K não custa mais do que a imagem 1920x1080 porque ambas são reduzidas para o mesmo tamanho; a resolução extra é descartada.



Suporte a imagens de alta resolução

O Claude Opus 4.7 é o primeiro modelo Claude com suporte a imagens de alta resolução; Claude Opus 4.8, Claude Fable 5, Claude Mythos 5 e modelos posteriores também o suportam. A resolução máxima de imagem é de 2576 pixels na borda mais longa, acima dos 1568 px em modelos anteriores. Isso desbloqueia ganhos de desempenho em cargas de trabalho intensivas em visão e é particularmente valioso para uso de computador, compreensão de capturas de tela e análise de documentos.

O suporte a alta resolução é automático no Claude Opus 4.7 e modelos posteriores e não requer cabeçalho beta ou opt-in do lado do cliente.

Imagens de alta resolução no Claude Opus 4.7, Claude Opus 4.8, Claude Fable 5 e Claude Mythos 5 podem usar até aproximadamente 3x mais tokens de imagem do que em modelos anteriores (4784 versus 1568 tokens por imagem). Se você não precisa da fidelidade adicional, reduza a resolução das imagens antes de enviá-las para controlar os custos de tokens.

Aqui estão os mesmos tamanhos de imagem tokenizados para Claude Opus 4.7 e Claude Opus 4.8, com base em seu preço por token de $5 por milhão de tokens de entrada:

Apenas a última imagem excede os limites mais altos: a imagem 4K é reduzida para 2576x1449 px antes do processamento. O suporte a alta resolução aumenta os limites de resolução, mas não os remove; imagens maiores que 2576 px na borda mais longa (ou 4784 tokens visuais) ainda são reduzidas.



Garantir a qualidade da imagem

Ao fornecer imagens ao Claude, tenha em mente o seguinte para obter melhores resultados:

• Formato da imagem: Use um formato de imagem suportado: JPEG, PNG, GIF ou WebP.
  Animações não são suportadas, e apenas o primeiro quadro será usado.
• Clareza da imagem: Certifique-se de que as imagens estejam claras e não muito borradas ou pixeladas.
• Texto: Se a imagem contiver texto importante, certifique-se de que esteja legível e não muito pequeno. Evite cortar contexto visual importante apenas para ampliar o texto.
• Redimensionamento: Leve em conta que sua imagem pode ser redimensionada se for muito grande (veja acima); isso pode, por exemplo, tornar o texto menos legível. Considere pré-redimensionar suas imagens, cortá-las, ou ambos.
• Compressão de imagem: Comprimir imagens antes de enviá-las, usando um formato com perdas como JPEG ou WebP (modo com perdas), pode reduzir a latência ao reduzir o tamanho das requisições. No entanto, isso pode introduzir artefatos que prejudicam o desempenho do modelo, especialmente quando várias passagens de compressão são aplicadas. Por exemplo, compressão JPEG pesada pode tornar o texto difícil de ler. Confirme que suas configurações de compressão são apropriadas para a tarefa inspecionando as imagens reais enviadas à API.



Trabalhando com coordenadas e bounding boxes

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áfico ou componentes de UI).

As coordenadas seguem a convenção padrão de imagem: 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 de pixel na imagem que o Claude vê: sua imagem depois que o Claude a redimensiona para caber na resolução nativa do modelo (veja Como o Claude redimensiona e preenche imagens). Para obter coordenadas que você possa usar diretamente, pré-redimensione sua imagem para que as coordenadas mapeiem um-para-um na imagem que você tem (veja Redimensione sua imagem antes de fazer upload), ou reescale as coordenadas que o Claude retorna (veja Reescalar coordenadas quando você não pode 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 para a maioria dos modelos, 2576 px para Claude Opus 4.7 e modelos posteriores).
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 para a maioria dos modelos, 4784 para Claude Opus 4.7 e modelos posteriores).

Para a maioria das fotos e capturas de tela, o limite de borda é o que aciona um redimensionamento. Para documentos em retrato, o limite de tokens visuais geralmente é acionado primeiro, e ignorá-lo é 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 custa 39 × 55 = 2145 tokens visuais, então o Claude a redimensiona para 924×1307.

O Claude então preenche cada imagem, tenha sido 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 preenchidas; dividir pelas dimensões preenchidas escala cada coordenada por uma pequena quantidade.



Redimensione sua imagem antes de fazer upload

A abordagem mais confiável é redimensionar sua imagem você mesmo antes de fazer upload, para 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.

A seguinte implementação de referência 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 most models. For Claude Opus 4.7 and later 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 para o maior tamanho que preserva
    # a proporção e ainda 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 "How Claude resizes and pads images":
print(resized_size(1075, 1520))  # (924, 1307)

1. Redimensione a imagem para as dimensões retornadas por resized_size. Se a imagem já couber dentro dos limites do modelo, resized_size retorna suas dimensões inalteradas e nenhum redimensionamento é necessário.
2. Envie a imagem redimensionada para a API. Não a preencha você mesmo; o Claude lida com o preenchimento, e o preenchimento não desloca a origem das coordenadas.
3. Em seu prompt, peça explicitamente por coordenadas em pixels. Por exemplo: "Retorne a bounding box de cada tabela como [x1, y1, x2, y2] em coordenadas de pixel."
4. Use as coordenadas retornadas diretamente na 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 e não pelas dimensões preenchidas.



Reescalar coordenadas quando você não pode 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 resized_size de Redimensione sua imagem antes de fazer upload para recuperar as dimensões que o Claude viu, então mapeie as coordenadas que o Claude retorna para coordenadas normalizadas ou de volta para sua imagem original. Essa abordagem requer conhecer as dimensões em pixels da imagem que você enviou, então não se aplica a uploads de PDF.

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 Claude Opus 4.7 and
    later 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)


# Para expressar a coordenada no espaço de pixels da sua imagem original, multiplique a
# coordenada relativa pelas dimensões originais:
# (rel_x * original_width, rel_y * original_height)

O preenchimento é aplicado apenas às bordas inferior e direita, então a origem não se desloca e um reescalonamento linear por eixo é suficiente.



Exemplos de prompt

Muitas das técnicas de prompting que funcionam bem para interações baseadas em texto com o Claude também podem ser aplicadas a prompts baseados em imagem.

Esses exemplos demonstram estruturas de prompt de melhores práticas envolvendo imagens.



Sobre os exemplos de prompt

Os exemplos a seguir demonstram como usar as capacidades de visão do Claude usando várias linguagens de programação e abordagens. Você pode fornecer imagens ao Claude de três maneiras:

1. Como uma imagem codificada em base64 em blocos de conteúdo image
2. Como uma referência de URL para uma imagem hospedada online
3. Usando a Files API (faça upload uma vez, use várias vezes)

Os exemplos de prompt em base64 usam estas variáveis:

Abaixo estão exemplos de como incluir imagens em uma requisição da Messages API usando imagens codificadas em base64 e referências de URL:



Exemplo de imagem codificada em base64



Exemplo de imagem baseada em URL



Exemplo de imagem com Files API

Para imagens que você usará repetidamente ou quando quiser evitar a sobrecarga de codificação, use a Files API. Faça upload da imagem uma vez, depois referencie o file_id retornado em mensagens subsequentes em vez de reenviar dados base64.

Veja exemplos da Messages API para mais exemplos de código e detalhes de parâmetros.



Limitações

Embora as capacidades de compreensão de imagem do Claude sejam de ponta, há algumas limitações a serem consideradas:

• Identificação de pessoas: O Claude não pode ser usado para nomear pessoas em imagens e se recusa a fazê-lo.
• Precisão: O Claude pode alucinar ou cometer erros ao interpretar imagens de baixa qualidade, rotacionadas ou muito pequenas com menos de 200 pixels.
• Raciocínio espacial: As saídas de coordenadas e localização do Claude são aproximadas. Siga as orientações em Trabalhando com coordenadas e bounding boxes e verifique as saídas antes de confiar nelas.
• Contagem: O Claude pode fornecer contagens aproximadas de objetos em uma imagem, mas nem sempre pode ser precisamente exato, especialmente com grandes números de objetos pequenos.
• Imagens geradas por IA: O Claude não sabe se uma imagem é gerada por IA e pode estar incorreto se perguntado. Não confie nele para detectar imagens falsas ou sintéticas.
• Conteúdo inapropriado: O Claude não processa imagens inapropriadas ou explícitas que violam a Política de Uso Aceitável.
• Aplicações de saúde: Embora o Claude possa analisar imagens médicas gerais, ele não foi projetado para interpretar exames diagnósticos complexos, como tomografias computadorizadas ou ressonâncias magnéticas. As saídas do Claude não devem ser consideradas um substituto para aconselhamento médico profissional ou diagnóstico.

Sempre revise e verifique cuidadosamente as interpretações de imagem do Claude, especialmente para casos de uso de alto risco. Não use o Claude para tarefas que exigem precisão perfeita ou análise de imagem sensível sem supervisão humana.



FAQ



Aprofunde-se em visão

Pronto para começar a construir com imagens usando o Claude? Aqui estão alguns recursos úteis:

• Cookbook multimodal: Este cookbook tem dicas sobre como começar com imagens e técnicas de melhores práticas para garantir o desempenho da mais alta qualidade com imagens. Veja como você pode efetivamente fazer prompts ao Claude com imagens para realizar tarefas como interpretar e analisar gráficos ou extrair conteúdo de formulários.
• Referência da API: Documentação para a Messages API, incluindo exemplos de chamadas de API envolvendo imagens.

Se você tiver outras perguntas, entre em contato com a equipe de suporte. Você também pode participar da comunidade de desenvolvedores para se conectar com outros criadores e obter ajuda de especialistas da Anthropic.