Visão

Este guia descreve como enviar imagens ao Claude, os limites e custos aplicáveis e onde encontrar orientações para fluxos de trabalho baseados em coordenadas.

Enviar imagens ao Claude

Use os recursos de visão do Claude por meio 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.
• Playground no Claude Console. Adicione imagens diretamente a qualquer bloco de mensagem User.
• Requisição de API. Veja os exemplos a seguir.

Na API, forneça imagens ao Claude como blocos de conteúdo image usando um de três tipos de origem:

1. Uma imagem codificada em base64 incorporada no corpo da requisição
2. Uma referência de URL para uma imagem hospedada online
3. Um file_id retornado pela Files API (faça upload uma vez, referencie muitas vezes)

Exemplo de imagem codificada em base64

image1_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"
image1_media_type = "image/png"

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image1_media_type,
                        "data": image1_data,
                    },
                },
                {"type": "text", "text": "Describe this image."},
            ],
        }
    ],
)
print(message)

Exemplo de imagem baseada em URL

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://platform.claude.com/docs/images/vision-example.jpg",
                    },
                },
                {"type": "text", "text": "Describe this image."},
            ],
        }
    ],
)
print(message)

Exemplo de imagem com a 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 e, em seguida, referencie o file_id retornado nas mensagens subsequentes em vez de reenviar dados em base64.

client = anthropic.Anthropic()

# Faça o upload do arquivo de imagem
with open("vision-example.jpg", "rb") as f:
    file_upload = client.files.upload(file=("vision-example.jpg", f, "image/jpeg"))

# Use o arquivo enviado em uma mensagem
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {"type": "file", "file_id": file_upload.id},
                },
                {"type": "text", "text": "Describe this image."},
            ],
        }
    ],
)

print(message.content)

Consulte os exemplos da Messages API para mais códigos de exemplo e detalhes de parâmetros.

Múltiplas imagens

Você pode incluir múltiplas imagens em uma única requisição, e o Claude as analisa em conjunto. Isso é útil para comparar imagens, perguntar sobre diferenças ou trabalhar com uma sequência, como as páginas de um documento. Ao enviar várias imagens, introduza cada uma com um rótulo de texto curto (Image 1:, Image 2: e assim por diante) para que você possa se referir a elas pelo nome no seu prompt e nos turnos seguintes.

image1_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"
image2_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGNgYPgPAAEDAQAIicLsAAAAAElFTkSuQmCC"

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Image 1:"},
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image1_data,
                    },
                },
                {"type": "text", "text": "Image 2:"},
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image2_data,
                    },
                },
                {"type": "text", "text": "How are these images different?"},
            ],
        }
    ],
)
print(message)

Em uma conversa com múltiplos turnos, adicione novas imagens em turnos user posteriores da mesma forma. O Claude tem acesso a todas as imagens dos turnos anteriores, então perguntas de acompanhamento como "Estas são semelhantes às duas primeiras?" funcionam sem incluir novamente as imagens anteriores no conteúdo do novo turno.

Limites e custos de imagens

Limites de requisição

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 "context window" (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 uma única requisição de API contiver mais de 20 imagens, um limite de dimensão por imagem mais rigoroso se aplica a todas as imagens dessa requisição. Todos os blocos image na requisição contam para esse limite, incluindo imagens de turnos anteriores da conversa que você reenvia e imagens aninhadas dentro do conteúdo de tool_result (por exemplo, capturas de tela retornadas à ferramenta de uso do computador). No Amazon Bedrock e no Google Cloud, blocos de documento, como PDFs, também contam para esse limite. Imagens que excedem o limite mais rigoroso são rejeitadas com um invalid_request_error cuja mensagem faz referência a "many-image requests" e informa o limite atual em pixels. Para ficar abaixo do limite em todas as plataformas, redimensione cada imagem para que nenhuma dimensão exceda 2000 px, ou mantenha a requisição com 20 ou menos blocos de imagem e documento.

O tamanho máximo por imagem é:

• 10 MB (codificado em base64) ao usar a Claude API diretamente.
• 5 MB (codificado em base64) no Amazon Bedrock e no Google Cloud.
• 10 MB no claude.ai.

Formatos suportados

O Claude suporta imagens JPEG, PNG, GIF e WebP (image/jpeg, image/png, image/gif, image/webp). Animações não são suportadas, e apenas o primeiro quadro é usado.

Resolução e custo em tokens

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

Cada modelo tem uma resolução de imagem nativa máxima, expressa como um limite de borda longa e um limite de tokens visuais. Imagens maiores que qualquer um desses limites são reduzidas antes do processamento; consulte Como o Claude redimensiona e preenche imagens para a regra exata. A exceção são as capturas de tela e imagens de zoom que você retorna aos conjuntos de ferramentas de uso do computador e uso do navegador: a API rejeita uma imagem de tool_result que excede os limites do modelo com um erro de validação em vez de reduzi-la, então redimensione essas imagens na sua aplicação antes de retorná-las. Para que qualquer outra imagem grande demais seja rejeitada com um erro em vez de reduzida, defina o campo transformations do bloco de imagem.

O suporte a alta resolução é automático nos modelos listados e não requer cabeçalho beta nem ativação no lado do cliente.

A tabela a seguir mostra a resolução reduzida e o custo em tokens visuais para vários tamanhos de imagem em cada nível:

Quando uma imagem é reduzida, o Claude a dimensiona para o maior tamanho que caiba nos limites do nível, preservando sua proporção. Isso limita o custo em tokens. Para a regra precisa e uma implementação de referência, consulte Como o Claude redimensiona e preenche imagens.

Para estimar o custo, multiplique a contagem de tokens pelo preço por token do modelo que você está usando. Por exemplo, com o preço do Claude Haiku 4.5 de $1 USD por milhão de tokens de entrada (nível padrão), a imagem de 1000×1000 custa cerca de $1,30 USD por mil imagens. Com o preço do Claude Opus 5 de $5 USD por milhão (nível de alta resolução), a mesma imagem custa cerca de $6,48 USD por mil e a imagem 4K cerca de $23,92 USD por mil.

Imagens de alta resolução podem usar até aproximadamente três vezes mais tokens visuais do que a mesma imagem em um modelo de nível padrão. Se você não precisa da fidelidade adicional que a alta resolução oferece para uso do computador, compreensão de capturas de tela e documentos densos, reduza a amostragem das imagens antes de enviá-las para controlar os custos em tokens. Para minimizar a latência e simplificar fluxos de trabalho baseados em coordenadas, prefira redimensionar as imagens antes de fazer o upload.

Orientações sobre qualidade de imagem

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

• Nitidez da imagem: Certifique-se de que as imagens estejam nítidas e não muito borradas ou pixeladas.
• Texto: Se a imagem contiver texto importante, certifique-se de que ele esteja legível e não seja muito pequeno. Evite recortar contexto visual importante apenas para ampliar o texto.
• Redimensionamento: Leve em conta que sua imagem pode ser redimensionada se for muito grande (consulte Resolução e custo em tokens); isso pode, por exemplo, tornar o texto menos legível. Considere redimensionar previamente suas imagens, recortá-las ou ambos. Para que uma imagem grande demais seja rejeitada com um erro em vez de redimensionada (importante para fluxos de trabalho com coordenadas), marque o bloco de imagem com "oversized_image": "error".
• 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 diminuir o tamanho das requisições. No entanto, isso pode introduzir artefatos prejudiciais ao desempenho do modelo, especialmente quando múltiplas passagens de compressão são aplicadas. Por exemplo, uma compressão JPEG intensa pode dificultar a leitura do texto. Confirme se suas configurações de compressão são adequadas para a tarefa inspecionando as imagens reais enviadas à API.

Coordenadas e caixas delimitadoras

Para "bounding boxes" (caixas delimitadoras), pontos e coordenadas de pixel, consulte Coordenadas e caixas delimitadoras. O Claude retorna coordenadas absolutas em pixels relativas à imagem que ele vê após o redimensionamento; esse guia aborda como o Claude redimensiona e preenche imagens e como redimensionar previamente ou reescalar para que as coordenadas se alinhem com sua imagem original.

Limitações

Embora os recursos de compreensão de imagens 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 Coordenadas e caixas delimitadoras e verifique as saídas antes de confiar nelas.
• Contagem: O Claude pode fornecer contagens aproximadas de objetos em uma imagem, mas nem sempre com precisão exata, especialmente com grandes quantidades de objetos pequenos.
• Imagens geradas por IA: O Claude não consegue determinar se uma imagem foi gerada por IA e pode estar incorreto se perguntado. Não confie nele para detectar imagens falsas ou sintéticas.
• Conteúdo inadequado: O Claude não processa imagens inadequadas ou explícitas que violem a Política de Uso Aceitável.
• Aplicações em 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 ou diagnóstico médico profissional.

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

Perguntas frequentes

Próximos passos