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 visão

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

• claude.ai. Carregue 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.
• Solicitação de API. Veja os exemplos neste guia.

Antes de fazer upload

Noções básicas e limites

Você pode incluir várias imagens em uma única solicitação: até 20 para claude.ai, e até 600 para solicitações de API (100 para modelos com uma janela de contexto de 200k tokens). Claude analisa todas as imagens fornecidas ao formular sua resposta. Isso pode ser útil para comparar ou contrastar imagens.

Se você enviar uma imagem maior que 8000x8000 px, ela será rejeitada. Se você enviar mais de 20 imagens em uma solicitação de API, este limite é 2000x2000 px.

Avaliar tamanho da imagem

Para minimizar a latência sem sacrificar a qualidade da saída, redimensione as imagens antes de fazer upload se forem muito grandes. No Claude Opus 4.6, Claude Sonnet 4.6 e modelos anteriores, se a borda longa da sua imagem tiver mais de 1568 pixels, ou sua imagem tiver mais de ~1.600 tokens, ela será primeiro reduzida, preservando a proporção de aspecto, até estar dentro dos limites de tamanho.

Se sua imagem de entrada for muito grande e precisar ser redimensionada, isso aumenta a latência do time-to-first-token, sem benefício para a qualidade da saída. Imagens muito pequenas com menos de 200 pixels em qualquer borda podem degradar a qualidade da saída.

Suporte de imagem de alta resolução no Claude Opus 4.7

Claude Opus 4.7 é o primeiro modelo Claude com suporte de imagem de alta resolução. A resolução máxima de imagem é 2576 pixels na borda longa (acima de 1568 px em modelos anteriores). Isso desbloqueia ganhos de desempenho em cargas de trabalho pesadas em visão e é particularmente valioso para uso de computador, compreensão de capturas de tela e análise de documentos.

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

Custo de token: Imagens em resolução completa no Claude Opus 4.7 podem usar até aproximadamente 3x mais tokens de imagem do que em modelos anteriores (até 4784 tokens por imagem, em comparação com o limite anterior de aproximadamente ~1.600 tokens por imagem). Se você não precisar da fidelidade adicional, faça downsampling das imagens antes de enviar para controlar os custos de token.

Matemática de coordenadas: No Claude Opus 4.7, as coordenadas de apontamento e caixa delimitadora retornadas pelo modelo são 1

Aqui está uma tabela de tamanhos máximos de imagem aceitos pela API que não serão redimensionados para proporções de aspecto comuns. Com Claude Sonnet 4.6, essas imagens usam aproximadamente 1.600 tokens e cerca de $4,80/1k imagens.

Calcular custos de imagem

Cada imagem que você inclui em uma solicitação ao Claude conta para seu uso de tokens. Para calcular o custo aproximado, multiplique o número aproximado de tokens de imagem pelo preço por token do modelo que você está usando.

Se sua imagem não precisar ser redimensionada, você pode estimar o número de tokens usados através deste algoritmo: tokens = (width px * height px)/750

Aqui estão exemplos de tokenização aproximada e custos 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:

Garantindo qualidade de imagem

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

• Formato de imagem: Use um formato de imagem suportado: JPEG, PNG, GIF ou WebP.
• Clareza da imagem: Certifique-se de que as imagens são claras e não muito desfocadas ou pixeladas.
• Texto: Se a imagem contiver texto importante, certifique-se de que seja legível e não muito pequeno. Evite cortar o contexto visual chave apenas para ampliar o texto.

Exemplos de prompt

Muitas das técnicas de prompt que funcionam bem para interações baseadas em texto com 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 (fazer upload uma vez, usar várias vezes)

Os prompts de exemplo base64 usam estas variáveis:

import base64
import httpx

# Para imagens codificadas em base64
image1_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image1_media_type = "image/jpeg"
image1_data = base64.standard_b64encode(httpx.get(image1_url).content).decode("utf-8")

image2_url = "https://upload.wikimedia.org/wikipedia/commons/b/b5/Iridescent.green.sweat.bee1.jpg"
image2_media_type = "image/jpeg"
image2_data = base64.standard_b64encode(httpx.get(image2_url).content).decode("utf-8")

# Para imagens baseadas em URL, você pode usar as URLs diretamente em suas solicitações

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

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-4-7",
    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-4-7",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
                    },
                },
                {"type": "text", "text": "Describe this image."},
            ],
        }
    ],
)
print(message)

Exemplo de imagem da API de Arquivos

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

client = anthropic.Anthropic()

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

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

print(message.content)

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

Limitações

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

• Identificação de pessoas: Claude não pode ser usado para nomear pessoas em imagens e se recusa a fazer isso.
• Precisã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 capacidades de raciocínio espacial do Claude são limitadas. Pode ter dificuldade com tarefas que exigem localização precisa ou layouts, como ler o rosto de um relógio analógico ou descrever posições exatas de peças de xadrez.
• Contagem: Claude pode dar contagens aproximadas de objetos em uma imagem, mas pode não ser sempre precisamente preciso, especialmente com grandes números de objetos pequenos.
• Imagens geradas por IA: Claude não sabe 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: Claude não processa imagens inadequadas ou explícitas que violem a Política de Uso Aceitável.
• Aplicações de saúde: Embora Claude possa analisar imagens médicas gerais, não foi projetado para interpretar varreduras diagnósticas complexas, como CTs ou RMs. Os resultados do Claude não devem ser considerados um substituto para aconselhamento médico profissional ou diagnóstico.

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

Perguntas Frequentes

Aprofunde-se em visão

Pronto para começar a construir com imagens usando 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 de mais alta qualidade com imagens. Veja como você pode solicitar efetivamente o Claude com imagens para realizar tarefas como interpretar e analisar gráficos ou extrair conteúdo de formulários.
• Referência de API: Documentação para a API de Mensagens, incluindo exemplos de chamadas de API envolvendo imagens.

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