o problema
Texto tem unidade de conta. Você conta token, sabe o preço, sabe quanto sobra da janela. Imagem não tem nada disso de graça: um jpeg de 3 MB e um png de 300 KB podem custar a mesma coisa, ou custar dez vezes mais um que o outro, e nada no arquivo diz qual é o caso. Quem monta um agente que manda um screenshot por passo descobre a resposta no fim do mês.
O segundo problema é pior porque é silencioso. A api não recusa imagem grande demais — ela reduz. O print de 3840×2160 que você mandou chegou ao modelo como 1456×819 no tier padrão, e o número de série impresso pequeno no canto virou borrão. O modelo então erra a leitura, você culpa a capacidade de visão, e a causa foi um downscale que ninguém mencionou.
a ideia
Claude não olha pixel: olha patch. Cada bloco de 28×28 px da imagem é um visual token. Isso transforma custo de imagem em aritmética fechada — ⌈largura / 28⌉ × ⌈altura / 28⌉ — e converte a pergunta “quanto vai custar esse screenshot” numa multiplicação que você faz antes de abrir o socket.
Em cima disso vem um teto por modelo, expresso como limite de lado maior e limite de visual tokens. Passou do teto, a imagem é reduzida ao maior tamanho que cabe, preservando o aspect ratio. O efeito colateral é útil: o custo por imagem tem um máximo conhecido. O efeito colateral é ruim: a fidelidade não tem piso.
como funciona
Imagem entra como content block image, com três tipos de source: base64 no corpo da requisição, url de imagem hospedada, ou file_id devolvido pela Files API. Em Amazon Bedrock e Google Cloud, só base64. A recomendação de ordem é imagem antes de texto — o inverso funciona, mas rende menos. Com várias imagens, rotule cada uma (Image 1:, Image 2:) para poder referenciá-las no prompt e nos turnos seguintes; imagens de turnos anteriores continuam acessíveis sem reenvio.
Os tiers de resolução: alta resolução para Claude 4.7 e posteriores, lado maior de 2.576 px e teto de 4.784 visual tokens; padrão para os demais, 1.568 px e 1.568 tokens. Não há beta header nem opt-in — é automático pelo modelo. Uma imagem de 1000×1000 custa 1.296 tokens nos dois tiers. Uma de 1920×1080 custa 1.560 no padrão (reduzida para 1456×819) e 2.691 no alto, sem redução. A conta em dinheiro sai da multiplicação pelo preço de entrada: a US$ 1 por milhão do Haiku 4.5, aquela imagem de 1000×1000 dá cerca de US$ 1,30 por mil imagens; a US$ 5 por milhão do Opus 5, cerca de US$ 6,48 — e o 4K, US$ 23,92.
Os limites duros: 100 imagens por requisição em modelos com janela de 200 mil tokens, 600 nos demais, 20 por mensagem no claude.ai. Máximo de 8.000×8.000 px e 10 MB por imagem na api direta (5 MB em Bedrock e Google Cloud). O limite de tamanho da requisição — 32 MB nos endpoints padrão — costuma bater antes da contagem de imagens. Formatos: JPEG, PNG, GIF e WebP; GIF animado entra pelo primeiro frame.
o que isso custou
Alta resolução gasta até cerca de três vezes mais visual tokens na mesma imagem. Se o caso de uso não precisa da fidelidade extra, a recomendação é reduzir a imagem antes de enviar — ou seja, a melhoria de qualidade vem com uma conta que você tem de administrar manualmente.
O downscale automático é a decisão mais cara de reverter. Para tê-lo trocado por erro explícito, é preciso marcar o bloco com o campo transformations. A exceção já vem invertida: imagem devolvida em tool_result do computer use é rejeitada com erro de validação em vez de reduzida, porque coordenada e redimensionamento não convivem.
E há uma lista de limitações que os próprios autores declaram. Claude se recusa a nomear pessoas em imagens, por política de uso. Erra com imagens de baixa qualidade, rotacionadas ou abaixo de 200 px. Coordenada e localização são aproximadas. Contagem de objetos pequenos é aproximada. Não sabe determinar se uma imagem foi gerada por ia e pode responder errado se perguntado. Não interpreta exame diagnóstico complexo como tomografia ou ressonância. Não lê metadata. E não gera nem edita imagem: é modelo de compreensão, só.
onde isso aparece hoje
O teto de resolução e a regra de redimensionamento existem em boa parte por causa de fluxos de coordenada — daí a exceção para screenshots do Computer use tool, onde um pixel deslocado vira clique no lugar errado. O limite de 100 imagens em modelos de 200 mil tokens amarra a vision diretamente ao orçamento da janela de contexto: visual token e token de texto disputam o mesmo espaço.
A contagem por patch tem linhagem: tratar a imagem como sequência de retalhos, e não como grade de pixels, é a ideia que o ViT colocou em circulação. O que a página adiciona é o preço na etiqueta — o patch deixou de ser detalhe de arquitetura e virou unidade de fatura.