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 as capacidades 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",
    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",
    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 os dados em base64.

client = anthropic.Anthropic()

# Faça 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",
    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 exemplos de código 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 páginas de um documento. Ao enviar várias imagens, apresente 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",
    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 de múltiplos turnos, adicione novas imagens em turnos user posteriores da mesma forma. O Claude tem acesso a todas as imagens dos turnos anteriores, portanto 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 200 mil 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 de conteúdo tool_result (por exemplo, capturas de tela retornadas à ferramenta de uso de 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 permanecer 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 (codificada em base64) ao usar a Claude API diretamente.
• 5 MB (codificada 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 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.

Cada modelo tem uma resolução nativa máxima de imagem, expressa como um limite de borda longa e um limite de tokens visuais. Imagens maiores que qualquer um dos limites são reduzidas antes do processamento; consulte Como o Claude redimensiona e preenche imagens para a regra exata. A exceção são capturas de tela e imagens de zoom que você retorna aos conjuntos de ferramentas de uso de computador e uso de navegador: a API rejeita uma imagem tool_result que exceda os limites do modelo com um erro de validação em vez de reduzi-la, portanto 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 se encaixa 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 Claude Haiku 4.5 a $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 Claude Opus 5 a $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 de computador, compreensão de capturas de tela e documentos densos, faça downsampling das imagens antes de enviá-las para controlar os custos em tokens. Para minimizar a latência e simplificar os fluxos de trabalho baseados em coordenadas, prefira redimensionar as imagens antes de fazer upload delas.

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 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 pré-redimensionar 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 de 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 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.

Coordenadas e caixas delimitadoras

Para 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 pré-redimensionar ou reescalar para que as coordenadas se alinhem com sua imagem original.

Limitações

Embora as capacidades 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 pode não ser sempre precisamente exato, 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 inapropriado: O Claude não processa imagens inapropriadas 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 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