---
title: Coordenadas e caixas delimitadoras
url: https://platform.claude.com/docs/pt-BR/build-with-claude/vision-coordinates
description: Como o Claude redimensiona imagens e como trabalhar com as coordenadas em pixels que ele retorna para caixas delimitadoras, pontos e elementos de interface.
---

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áficos ou componentes de interface). Este guia aborda como o Claude redimensiona imagens antes de processá-las e como trabalhar com as coordenadas em pixels que ele retorna, para que caixas e pontos se alinhem com sua imagem original.

Você precisará disso para pipelines de OCR, extração de formulários, análise de gráficos, localização de elementos de interface e qualquer tarefa em que você atue sobre uma região específica de uma imagem. Para envio de imagens, formatos suportados e limites de resolução por modelo, consulte [Visão](https://platform.claude.com/docs/pt-BR/build-with-claude/vision).

<Note>
  **O Claude funciona melhor com coordenadas absolutas em pixels.** Peça-as explicitamente no seu prompt. Por exemplo: *"Retorne a caixa delimitadora de cada tabela como `[x1, y1, x2, y2]` (cantos superior esquerdo e inferior direito) em coordenadas de pixels."* O Claude não funciona bem quando você pede coordenadas normalizadas, por exemplo: *"Retorne coordenadas de caixa delimitadora entre `0` e `1000`."* Sempre peça coordenadas em pixels e normalize no seu próprio código se precisar. Para obter coordenadas como JSON legível por máquina em vez de prosa, defina um esquema com [saídas estruturadas](https://platform.claude.com/docs/pt-BR/build-with-claude/structured-outputs), por exemplo um objeto com um array `[x1, y1, x2, y2]` por elemento detectado.
</Note>

As coordenadas seguem a convenção padrão de imagens: 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 em pixels na imagem que o Claude vê: sua imagem depois que o Claude a redimensiona para caber na resolução nativa do modelo (consulte [Como o Claude redimensiona e preenche imagens](https://platform.claude.com/docs/pt-BR/build-with-claude/vision-coordinates#how-claude-resizes-and-pads-images)). Para obter coordenadas que você possa usar diretamente, pré-redimensione sua imagem para que as coordenadas correspondam uma a uma à imagem que você tem (consulte [Redimensione sua imagem antes de enviar](https://platform.claude.com/docs/pt-BR/build-with-claude/vision-coordinates#resize-your-image-before-uploading)) ou reescale as coordenadas que o Claude retorna (consulte [Reescale coordenadas quando não puder pré-redimensionar](https://platform.claude.com/docs/pt-BR/build-with-claude/vision-coordinates#rescale-coordinates-when-you-cannot-pre-resize)).

<Note>
  O raciocínio espacial do Claude tem limites (consulte [Limitações](https://platform.claude.com/docs/pt-BR/build-with-claude/vision#limitations)). A precisão das coordenadas é melhor quando você declara o formato de coordenadas esperado no seu prompt e verifica os resultados visualmente por amostragem antes de processar em escala. Elementos pequenos perdem precisão quando uma imagem é reduzida: para alvos finos, recorte a região de interesse e envie o recorte (desloque as coordenadas retornadas pela origem do recorte) ou use um modelo do nível de alta resolução. Para [suporte a PDF](https://platform.claude.com/docs/pt-BR/build-with-claude/pdf-support), as páginas são rasterizadas em imagens no lado do servidor em dimensões que você não controla, portanto as coordenadas retornadas não podem ser mapeadas de volta para a página de forma confiável. Para trabalhar com coordenadas em conteúdo PDF, rasterize as páginas em imagens você mesmo e use a abordagem de pré-redimensionamento.
</Note>

## 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 no nível padrão, 2576 px no nível de alta resolução).
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 no nível padrão, 4784 no nível de alta resolução).

Consulte [Resolução e custo em tokens](https://platform.claude.com/docs/pt-BR/build-with-claude/vision#evaluate-image-size) para saber quais modelos estão em qual nível.

Para quase todas as fotos e capturas de tela, o limite de tokens visuais é o que determina o tamanho final. O limite de borda prevalece apenas para imagens alongadas, como panoramas ou capturas de tela altas de celular. Calcule o tamanho com a [implementação de referência](https://platform.claude.com/docs/pt-BR/build-with-claude/vision-coordinates#resize-your-image-before-uploading) em vez de escalar manualmente para o comprimento de borda: uma captura de tela de 1920×1080 é redimensionada para 1456×819, não 1568×882, e presumir o limite de borda deixa todas as coordenadas visivelmente fora do alvo.

O limite de tokens também pode acionar um redimensionamento quando nenhum lado excede o limite de borda. Ignorar isso é 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 ela custa `39 × 55 = 2145` tokens visuais, então o Claude a redimensiona para 924×1307.

<Note>
  Este exemplo presume um modelo no nível de resolução padrão. Um modelo do nível de alta resolução não redimensiona a mesma digitalização: 2145 tokens está dentro do seu orçamento de 4784 tokens, portanto as coordenadas que ele retorna correspondem diretamente ao original de 1075×1520. Os níveis dos modelos estão listados em [Resolução e custo em tokens](https://platform.claude.com/docs/pt-BR/build-with-claude/vision#evaluate-image-size).
</Note>

O Claude então aplica "padding" (preenchimento) a toda imagem, 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 com preenchimento**; dividir pelas dimensões com preenchimento escala todas as coordenadas por uma pequena quantidade.

## Redimensione sua imagem antes de enviar

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

Primeiro verifique em qual nível de resolução seu modelo está (consulte [Resolução e custo em tokens](https://platform.claude.com/docs/pt-BR/build-with-claude/vision#evaluate-image-size)) e passe os limites de borda e de tokens correspondentes. A implementação de referência a seguir calcula o tamanho exato para o qual o Claude redimensiona uma imagem:

<CodeGroup exclude="shell">
  <CodeGroupItem language="cURL">
    Calcule este tamanho em código.
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    Calcule este tamanho em código.
  </CodeGroupItem>

  ```python Python
  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 the standard resolution tier. For high-resolution-tier
      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 pelo maior tamanho que preserva
      # a proporção e 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 "Como o Claude redimensiona e preenche imagens":
  print(resized_size(1075, 1520))  # (924, 1307)

  # Para aplicar o redimensionamento, use sua biblioteca de imagens, por exemplo Pillow:
  # image.resize(resized_size(*image.size))
  ```

  ```typescript TypeScript
  /** Visual tokens consumed by an image: one token per 28x28 pixel patch. */
  function countImageTokens(width: number, height: number): number {
    return Math.ceil(width / 28) * Math.ceil(height / 28);
  }

  /**
   * Round half to even (banker's rounding), matching Python's round(). The
   * live API resolves exact .5 ties toward the even neighbor, so Math.round
   * (which rounds halves up) would compute a different size for some images.
   */
  function roundTiesToEven(value: number): number {
    const floor = Math.floor(value);
    if (value - floor !== 0.5) {
      return Math.round(value);
    }
    return floor % 2 === 0 ? floor : floor + 1;
  }

  /**
   * The size Claude resizes an image to before padding.
   *
   * Defaults are for the standard resolution tier. For high-resolution-tier
   * models, use maxEdge = 2576 and maxTokens = 4784. Returns [width, height].
   * Images that already fit within the limits are returned unchanged.
   */
  function resizedSize(
    width: number,
    height: number,
    maxEdge = 1568,
    maxTokens = 1568
  ): [number, number] {
    const fits = (w: number, h: number): boolean =>
      Math.ceil(w / 28) * 28 <= maxEdge &&
      Math.ceil(h / 28) * 28 <= maxEdge &&
      countImageTokens(w, h) <= maxTokens;

    if (fits(width, height)) {
      return [width, height];
    }
    if (height > width) {
      const [resizedH, resizedW] = resizedSize(height, width, maxEdge, maxTokens);
      return [resizedW, resizedH];
    }

    // Busca binária ao longo da borda maior para o maior tamanho que preserva
    // a proporção e cabe no limite.
    const aspectRatio = width / height;
    let lo = 1; // lo always fits
    let hi = width; // hi never fits
    while (lo + 1 < hi) {
      const mid = Math.floor((lo + hi) / 2);
      if (fits(mid, Math.max(roundTiesToEven(mid / aspectRatio), 1))) {
        lo = mid;
      } else {
        hi = mid;
      }
    }
    return [lo, Math.max(roundTiesToEven(lo / aspectRatio), 1)];
  }

  // O exemplo A4 de "Como o Claude redimensiona e preenche imagens":
  console.log(resizedSize(1075, 1520)); // [ 924, 1307 ]

  // Para aplicar o redimensionamento, use sua biblioteca de imagens, por exemplo sharp:
  // await sharp(input).resize(width, height).toBuffer()
  ```

  ```csharp C#
  // Tokens visuais consumidos por uma imagem: um token por patch de 28x28 pixels.
  static int CountImageTokens(int width, int height)
  {
      return (width + 27) / 28 * ((height + 27) / 28); // ceil(w/28) * ceil(h/28)
  }

  // O tamanho para o qual o Claude redimensiona uma imagem antes do padding. Os padrões
  // são para o nível de resolução padrão; para modelos de alta resolução, passe
  // maxEdge: 2576, maxTokens: 4784. Imagens que já cabem dentro dos limites
  // são retornadas sem alteração.
  static (int Width, int Height) ResizedSize(
      int width, int height, int maxEdge = 1568, int maxTokens = 1568)
  {
      bool Fits(int w, int h) =>
          (w + 27) / 28 * 28 <= maxEdge
          && (h + 27) / 28 * 28 <= maxEdge
          && CountImageTokens(w, h) <= maxTokens;

      if (Fits(width, height))
      {
          return (width, height);
      }
      if (height > width)
      {
          (int resizedH, int resizedW) = ResizedSize(height, width, maxEdge, maxTokens);
          return (resizedW, resizedH);
      }

      // Busca binária ao longo da borda maior pelo maior tamanho que preserva a
      // proporção e cabe. A borda menor arredonda .5 para par, igual à API ao vivo
      // em empates exatos de .5 (MidpointRounding.ToEven, padrão de Math.Round).
      double aspectRatio = (double)width / height;
      int lo = 1; // lo always fits
      int hi = width; // hi never fits
      while (lo + 1 < hi)
      {
          int mid = (lo + hi) / 2;
          if (Fits(mid, ShortEdge(mid)))
          {
              lo = mid;
          }
          else
          {
              hi = mid;
          }
      }
      return (lo, ShortEdge(lo));

      int ShortEdge(int longEdge) =>
          Math.Max((int)Math.Round(longEdge / aspectRatio, MidpointRounding.ToEven), 1);
  }

  // O exemplo A4 de "Como o Claude redimensiona e preenche imagens":
  Console.WriteLine(ResizedSize(1075, 1520)); // (924, 1307)
  ```

  ```go Go
  // countImageTokens é o número de tokens visuais consumidos por uma imagem: um token por
  // patch de 28x28 pixels.
  func countImageTokens(width, height int) int {
  	return ((width + 27) / 28) * ((height + 27) / 28) // ceil(w/28) * ceil(h/28)
  }

  // resizedSize é o tamanho para o qual o Claude redimensiona uma imagem antes do padding, como
  // (width, height). Passe maxEdge 1568 e maxTokens 1568 para o nível de resolução
  // padrão, ou 2576 e 4784 para o nível de alta resolução. Imagens
  // que já cabem dentro dos limites são retornadas sem alteração.
  // O exemplo A4 de "How Claude resizes and pads images":
  // resizedSize(1075, 1520, 1568, 1568) retorna (924, 1307).
  func resizedSize(width, height, maxEdge, maxTokens int) (int, int) {
  	fits := func(w, h int) bool {
  		return ((w+27)/28)*28 <= maxEdge &&
  			((h+27)/28)*28 <= maxEdge &&
  			countImageTokens(w, h) <= maxTokens
  	}

  	if fits(width, height) {
  		return width, height
  	}
  	if height > width {
  		resizedH, resizedW := resizedSize(height, width, maxEdge, maxTokens)
  		return resizedW, resizedH
  	}

  	// Busca binária ao longo da borda maior pelo maior tamanho que preserva a proporção
  	// e que cabe. A borda menor arredonda .5 para par (math.RoundToEven),
  	// correspondendo à API ao vivo em empates exatos de .5; math.Round arredondaria para cima.
  	aspectRatio := float64(width) / float64(height)
  	lo, hi := 1, width // lo always fits; hi never fits
  	for lo+1 < hi {
  		mid := (lo + hi) / 2
  		short := max(int(math.RoundToEven(float64(mid)/aspectRatio)), 1)
  		if fits(mid, short) {
  			lo = mid
  		} else {
  			hi = mid
  		}
  	}
  	return lo, max(int(math.RoundToEven(float64(lo)/aspectRatio)), 1)
  }
  ```

  ```java Java
  /** A resized image size, as returned by resizedSize. */
  record Size(int width, int height) {}

  /** Visual tokens consumed by an image: one token per 28x28 pixel patch. */
  static int countImageTokens(int width, int height) {
      return Math.ceilDiv(width, 28) * Math.ceilDiv(height, 28);
  }

  /**
   * The size Claude resizes an image to before padding.
   *
   * <p>Pass maxEdge 1568 and maxTokens 1568 for the standard resolution tier,
   * or 2576 and 4784 for the high-resolution tier. Images that already fit
   * within the limits are returned unchanged.
   *
   * <p>The A4 example from "How Claude resizes and pads images":
   * resizedSize(1075, 1520, 1568, 1568) returns new Size(924, 1307).
   */
  static Size resizedSize(int width, int height, int maxEdge, int maxTokens) {
      if (fits(width, height, maxEdge, maxTokens)) {
          return new Size(width, height);
      }
      if (height > width) {
          Size rotated = resizedSize(height, width, maxEdge, maxTokens);
          return new Size(rotated.height(), rotated.width());
      }

      // Busca binária ao longo do lado maior para o maior tamanho que preserva a
      // proporção e cabe no limite. O lado menor arredonda .5 para par (Math.rint),
      // igual à API real em empates exatos de .5; Math.round arredondaria para cima.
      double aspectRatio = (double) width / height;
      int lo = 1; // lo always fits
      int hi = width; // hi never fits
      while (lo + 1 < hi) {
          int mid = (lo + hi) / 2;
          if (fits(mid, shortEdge(mid, aspectRatio), maxEdge, maxTokens)) {
              lo = mid;
          } else {
              hi = mid;
          }
      }
      return new Size(lo, shortEdge(lo, aspectRatio));
  }

  private static boolean fits(int width, int height, int maxEdge, int maxTokens) {
      return Math.ceilDiv(width, 28) * 28 <= maxEdge
              && Math.ceilDiv(height, 28) * 28 <= maxEdge
              && countImageTokens(width, height) <= maxTokens;
  }

  private static int shortEdge(int longEdge, double aspectRatio) {
      return Math.max((int) Math.rint(longEdge / aspectRatio), 1);
  }
  ```

  ```php PHP
  // Tokens visuais consumidos por uma imagem: um token por patch de 28x28 pixels.
  function countImageTokens(int $width, int $height): int
  {
      return intdiv($width + 27, 28) * intdiv($height + 27, 28);
  }

  /**
   * The size Claude resizes an image to before padding, as [width, height].
   *
   * Defaults are for the standard resolution tier. For high-resolution-tier
   * models, pass maxEdge: 2576, maxTokens: 4784. Images that already fit
   * within the limits are returned unchanged.
   */
  function resizedSize(int $width, int $height, int $maxEdge = 1568, int $maxTokens = 1568): array
  {
      $fits = fn (int $w, int $h): bool =>
          intdiv($w + 27, 28) * 28 <= $maxEdge
          && intdiv($h + 27, 28) * 28 <= $maxEdge
          && countImageTokens($w, $h) <= $maxTokens;

      if ($fits($width, $height)) {
          return [$width, $height];
      }
      if ($height > $width) {
          [$resizedH, $resizedW] = resizedSize($height, $width, $maxEdge, $maxTokens);
          return [$resizedW, $resizedH];
      }

      // Busca binária ao longo da borda maior para o maior tamanho que preserva a
      // proporção e cabe no limite. A borda menor arredonda metades para par
      // (PHP_ROUND_HALF_EVEN), igual à API ao vivo em empates exatos de .5.
      $aspectRatio = $width / $height;
      $lo = 1; // lo always fits
      $hi = $width; // hi never fits
      while ($lo + 1 < $hi) {
          $mid = intdiv($lo + $hi, 2);
          $short = max((int) round($mid / $aspectRatio, 0, PHP_ROUND_HALF_EVEN), 1);
          if ($fits($mid, $short)) {
              $lo = $mid;
          } else {
              $hi = $mid;
          }
      }

      return [$lo, max((int) round($lo / $aspectRatio, 0, PHP_ROUND_HALF_EVEN), 1)];
  }

  // O exemplo A4 de "How Claude resizes and pads images":
  [$resizedWidth, $resizedHeight] = resizedSize(1075, 1520);
  echo "({$resizedWidth}, {$resizedHeight})\n"; // (924, 1307)
  ```

  ```ruby Ruby
  # Tokens visuais consumidos por uma imagem: um token por patch de 28x28 pixels.
  def count_image_tokens(width, height)
    width.ceildiv(28) * height.ceildiv(28)
  end

  # O tamanho para o qual Claude redimensiona uma imagem antes do padding, como [width, height].
  #
  # Os padrões são para o nível de resolução padrão. Para modelos do nível de alta
  # resolução, passe max_edge: 2576, max_tokens: 4784. Imagens que já cabem
  # dentro dos limites são retornadas sem alteração.
  def resized_size(width, height, max_edge = 1568, max_tokens = 1568)
    fits = lambda do |w, h|
      w.ceildiv(28) * 28 <= max_edge &&
        h.ceildiv(28) * 28 <= max_edge &&
        count_image_tokens(w, h) <= max_tokens
    end

    return [width, height] if fits.call(width, height)

    if height > width
      resized_h, resized_w = resized_size(height, width, max_edge, max_tokens)
      return [resized_w, resized_h]
    end

    # Busca binária ao longo da borda maior pelo maior tamanho que preserva a
    # proporção e cabe. A borda menor arredonda .5 para par (round(half: :even)),
    # correspondendo à API ao vivo em empates exatos de .5.
    aspect_ratio = width.fdiv(height)
    lo = 1      # lo always fits
    hi = width  # hi never fits
    while lo + 1 < hi
      mid = (lo + hi) / 2
      short = [(mid / aspect_ratio).round(half: :even), 1].max
      if fits.call(mid, short)
        lo = mid
      else
        hi = mid
      end
    end

    [lo, [(lo / aspect_ratio).round(half: :even), 1].max]
  end

  # O exemplo A4 de "Como o Claude redimensiona e preenche imagens":
  p resized_size(1075, 1520) # => [924, 1307]
  ```
</CodeGroup>

1. Redimensione a imagem para as dimensões retornadas pelo helper de redimensionamento. Se a imagem já cabe dentro dos limites do modelo, o helper retorna suas dimensões inalteradas e nenhum redimensionamento é necessário.
2. [Envie a imagem redimensionada](https://platform.claude.com/docs/pt-BR/build-with-claude/vision#send-images-to-claude) para a API. Não aplique preenchimento você mesmo. O Claude cuida do preenchimento, e o preenchimento não desloca a origem das coordenadas.
3. No seu prompt, peça explicitamente coordenadas em pixels. Por exemplo: *"Retorne o ponto de clique do botão Submit como `[x, y]` em coordenadas de pixels."*
4. Use as coordenadas retornadas diretamente sobre a 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 nem pelas dimensões com preenchimento.

<Note>
  O endpoint de [Contagem de tokens](https://platform.claude.com/docs/pt-BR/build-with-claude/token-counting) estima o custo em tokens de uma imagem a partir de suas dimensões sem processá-la completamente, portanto uma contagem bem-sucedida não significa que a imagem está dentro dos [limites de requisição](https://platform.claude.com/docs/pt-BR/build-with-claude/vision#request-limits) da Messages API. Uma imagem pode ser contada com sucesso e ainda assim ser rejeitada quando você a envia.
</Note>

## Transforme o redimensionamento em um erro com `transformations`

O pré-redimensionamento só protege suas coordenadas enquanto seu pipeline continua produzindo os tamanhos corretos. Uma nova fonte de imagens ou uma troca para um modelo em um nível de resolução diferente pode reintroduzir silenciosamente o redimensionamento no lado do servidor. Para transformar esse desvio silencioso em um erro visível, defina o campo opcional `transformations` em um bloco de conteúdo de imagem em uma requisição [Messages](https://platform.claude.com/docs/pt-BR/api/messages):

```json
{
  "type": "image",
  "source": { "type": "base64", "media_type": "image/png", "data": "..." },
  "transformations": { "oversized_image": "error" }
}
```

Uma requisição cuja imagem marcada (qualquer bloco que defina `"oversized_image": "error"`) seria redimensionada é rejeitada com um 400 `invalid_request_error` informando as dimensões da imagem e as maiores dimensões que cabem. Se uma imagem aciona a rejeição depende dos [limites de cada modelo que a requisição nomeia](https://platform.claude.com/docs/pt-BR/build-with-claude/vision-coordinates#how-claude-resizes-and-pads-images): o exemplo de 1920×1080 abaixo é rejeitado por um modelo do nível padrão, mas cabe dentro do nível de alta resolução:

```text wrap
messages.0.content.0: image dimensions 1920x1080 exceed the maximum image size of a model named on this request and would be downsized to 1456x819; scale the image to at most 1456x819 or set the image's oversized_image setting to "downsize"
```

Reescale para o alvo informado e reenvie: o alvo é o maior tamanho, na proporção da sua imagem, que todos os modelos nomeados na requisição aceitam. Como imagens marcadas interagem com o [beta de fallback no lado do servidor](https://platform.claude.com/docs/pt-BR/build-with-claude/refusals-and-fallback#server-side-fallback) é descrito junto com esse recurso; em todos os modos, uma imagem marcada nunca é servida redimensionada.

A configuração é por imagem. `"oversized_image": "downsize"` (o padrão quando o campo é omitido) mantém o redimensionamento automático conforme descrito nesta página. Cada bloco de imagem é verificado apenas em relação à sua própria configuração, portanto uma requisição pode misturar imagens cujas dimensões são essenciais (uma captura de tela na qual você vai clicar) com imagens em que o redimensionamento é inofensivo (um logotipo). O que a configuração altera e o que não altera:

* O preenchimento ([que nunca descarta conteúdo](https://platform.claude.com/docs/pt-BR/build-with-claude/vision-coordinates#how-claude-resizes-and-pads-images)), a conversão de formato e a correção de orientação prosseguem normalmente.
* Os limites rígidos (8000 px no lado mais longo e o limite por imagem mais restrito em [requisições com muitas imagens](https://platform.claude.com/docs/pt-BR/build-with-claude/vision#request-limits)) são rejeições separadas; esta configuração nunca permite que uma imagem os ultrapasse.
* Imagens fornecidas por URL ou ID de arquivo são verificadas depois que seus bytes são obtidos; essas rejeições trazem a mesma mensagem sem a posição inicial, portanto não identificam qual imagem falhou; apenas imagens base64 incorporadas são nomeadas por posição no erro.
* [Páginas de PDF](https://platform.claude.com/docs/pt-BR/build-with-claude/pdf-support) são rasterizadas no lado do servidor em dimensões que você não controla; o bloco `document` não aceita o campo (um bloco de imagem aninhado dentro do conteúdo de um documento o aceita como qualquer outro).
* Uma imagem marcada cujas dimensões não podem ser determinadas é rejeitada em vez de ser repassada: essa rejeição informa que as dimensões de origem da imagem não puderam ser determinadas, não a mensagem de redimensionamento citada acima. Nenhuma imagem que define `"error"` chega ao modelo redimensionada.

O endpoint de [Contagem de tokens](https://platform.claude.com/docs/pt-BR/build-with-claude/token-counting) também respeita `transformations`, rejeitando uma imagem incorporada exatamente como a Messages API faria, para que você possa verificar se uma imagem incorporada cabe sem ser redimensionada antes de executar a inferência. A contagem rejeita imagens fornecidas por URL ou ID de arquivo em vez de obtê-las, portanto uma imagem marcada dessas fontes só é verificada no momento da chamada à Messages.

## Reescale coordenadas quando não puder 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 o helper de redimensionamento de [Redimensione sua imagem antes de enviar](https://platform.claude.com/docs/pt-BR/build-with-claude/vision-coordinates#resize-your-image-before-uploading) para recuperar as dimensões que o Claude viu e, em seguida, mapeie as coordenadas que o Claude retorna para coordenadas normalizadas ou de volta para sua imagem original. A menos que uma imagem [opte por um erro em vez disso](https://platform.claude.com/docs/pt-BR/build-with-claude/vision-coordinates#oversized-image-error), o Claude redimensiona imagens grandes demais em vez de rejeitá-las, até os [limites de requisição](https://platform.claude.com/docs/pt-BR/build-with-claude/vision#request-limits) da API. Além desses limites, a requisição falha com um erro de validação. Passe os limites de nível que correspondem ao modelo que você chamou: os limites do nível errado recuperam as dimensões redimensionadas erradas e deslocam silenciosamente todas as coordenadas. Esta abordagem requer conhecer as dimensões em pixels da imagem que você enviou, portanto não se aplica a uploads de PDF.

Capturas de tela e imagens de zoom que você retorna para os conjuntos de ferramentas de [uso de computador](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions) e [uso de navegador](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#targets-and-coordinates) são uma exceção ao redimensionamento automático. A API rejeita uma imagem de `tool_result` que excede os limites do modelo com um erro de validação em vez de redimensioná-la. Redimensione essas imagens na sua aplicação antes de retorná-las e, em seguida, escale as coordenadas que o Claude retorna de volta para as dimensões da sua tela.

<CodeGroup exclude="shell">
  <CodeGroupItem language="cURL">
    Converta as coordenadas em código.
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    Converta as coordenadas em código.
  </CodeGroupItem>

  ```python Python
  # Este helper chama resized_size do exemplo de redimensionamento nesta página.
  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 high-resolution-tier
      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)


  # Um canto de tabela que o Claude retorna em (462, 653.5) na página A4 redimensionada
  # mapeia de volta para o original 1075x1520 assim:
  rel_x, rel_y = to_relative_coordinates(462, 653.5, 1075, 1520)
  print((rel_x * 1075, rel_y * 1520))  # (537.5, 760.0)
  ```

  ```typescript TypeScript
  // Este helper chama resizedSize do exemplo de redimensionamento nesta página.
  /**
   * Map a pixel coordinate returned by Claude to relative coordinates in [0, 1].
   *
   * Pass the dimensions of the image you uploaded. For high-resolution-tier
   * models, use maxEdge = 2576 and maxTokens = 4784.
   */
  function toRelativeCoordinates(
    x: number,
    y: number,
    originalWidth: number,
    originalHeight: number,
    maxEdge = 1568,
    maxTokens = 1568
  ): [number, number] {
    const [resizedW, resizedH] = resizedSize(originalWidth, originalHeight, maxEdge, maxTokens);
    return [x / resizedW, y / resizedH];
  }

  // Um canto de tabela que o Claude retorna em (462, 653.5) na página A4 redimensionada
  // é mapeado de volta para o original 1075x1520 assim:
  const [relX, relY] = toRelativeCoordinates(462, 653.5, 1075, 1520);
  console.log([relX * 1075, relY * 1520]); // [ 537.5, 760 ]
  ```

  ```csharp C#
  // Este helper chama ResizedSize do exemplo de redimensionamento nesta página.
  // Mapeia uma coordenada de pixel retornada pelo Claude para coordenadas relativas
  // em [0, 1]. Passe as dimensões da imagem que você enviou e os mesmos limites
  // de nível usados para ResizedSize.
  static (double X, double Y) ToRelativeCoordinates(
      double x, double y, int originalWidth, int originalHeight,
      int maxEdge = 1568, int maxTokens = 1568)
  {
      (int resizedW, int resizedH) =
          ResizedSize(originalWidth, originalHeight, maxEdge, maxTokens);
      return (x / resizedW, y / resizedH);
  }

  // Um canto de tabela que o Claude retorna em (462, 653.5) na página A4 redimensionada
  // é mapeado de volta para o original de 1075x1520 assim:
  (double relX, double relY) = ToRelativeCoordinates(462, 653.5, 1075, 1520);
  Console.WriteLine((relX * 1075, relY * 1520)); // (537.5, 760)
  ```

  ```go Go
  // Este helper chama resizedSize do exemplo de redimensionamento nesta página.

  // toRelativeCoordinates mapeia uma coordenada de pixel retornada pelo Claude para
  // coordenadas relativas em [0, 1]. Passe as dimensões da imagem que você
  // enviou e os mesmos limites de nível usados para resizedSize.
  func toRelativeCoordinates(
  	x, y float64,
  	originalWidth, originalHeight, maxEdge, maxTokens int,
  ) (float64, float64) {
  	resizedW, resizedH := resizedSize(originalWidth, originalHeight, maxEdge, maxTokens)
  	return x / float64(resizedW), y / float64(resizedH)
  }

  // Para mapear de volta ao espaço de pixels da sua imagem original, multiplique pelas
  // dimensões originais: um canto de tabela retornado em (462, 653.5) na página A4 redimensionada
  // é (relX*1075, relY*1520) = (537.5, 760) no original de 1075x1520.
  ```

  ```java Java
  // Este helper chama resizedSize do exemplo de redimensionamento nesta página.
  /** A coordinate scaled into the [0, 1] range on both axes. */
  record RelativeCoordinate(double x, double y) {}

  /**
   * Map a pixel coordinate returned by Claude to relative coordinates in
   * [0, 1]. Pass the dimensions of the image you uploaded, and the same tier
   * limits used for resizedSize.
   */
  static RelativeCoordinate toRelativeCoordinates(
          double x, double y, int originalWidth, int originalHeight, int maxEdge, int maxTokens) {
      Size resized = resizedSize(originalWidth, originalHeight, maxEdge, maxTokens);
      return new RelativeCoordinate(x / resized.width(), y / resized.height());
  }

  // Para mapear de volta ao espaço de pixels da imagem original, multiplique pelas
  // dimensões originais: um canto de tabela retornado em (462, 653.5) na página A4
  // redimensionada é (relative.x() * 1075, relative.y() * 1520) = (537.5, 760) no
  // original de 1075x1520.
  ```

  ```php PHP
  // Este helper chama resizedSize() do exemplo de redimensionamento nesta página.
  /**
   * Map a pixel coordinate returned by Claude to relative coordinates in
   * [0, 1], as [x, y]. Pass the dimensions of the image you uploaded, and the
   * same tier limits used for resizedSize.
   */
  function toRelativeCoordinates(
      float $x,
      float $y,
      int $originalWidth,
      int $originalHeight,
      int $maxEdge = 1568,
      int $maxTokens = 1568,
  ): array {
      [$resizedW, $resizedH] = resizedSize($originalWidth, $originalHeight, $maxEdge, $maxTokens);

      return [$x / $resizedW, $y / $resizedH];
  }

  // Um canto de tabela que o Claude retorna em (462, 653.5) na página A4 redimensionada
  // é mapeado de volta ao original 1075x1520 assim:
  [$relX, $relY] = toRelativeCoordinates(462, 653.5, 1075, 1520);
  echo '(' . $relX * 1075 . ', ' . $relY * 1520 . ")\n"; // (537.5, 760)
  ```

  ```ruby Ruby
  # Este helper chama resized_size do exemplo de redimensionamento nesta página.
  # Mapeia uma coordenada de pixel retornada pelo Claude para coordenadas relativas
  # em [0, 1], como [x, y]. Passe as dimensões da imagem que você enviou e os
  # mesmos limites de nível usados para resized_size.
  def to_relative_coordinates(
    x, y, original_width, original_height, max_edge = 1568, max_tokens = 1568
  )
    resized_w, resized_h = resized_size(original_width, original_height, max_edge, max_tokens)
    [x.fdiv(resized_w), y.fdiv(resized_h)]
  end

  # Um canto de tabela que o Claude retorna em (462, 653.5) na página A4 redimensionada
  # é mapeado de volta para o original de 1075x1520 assim:
  rel_x, rel_y = to_relative_coordinates(462, 653.5, 1075, 1520)
  p [rel_x * 1075, rel_y * 1520] # => [537.5, 760.0]
  ```
</CodeGroup>

O preenchimento é aplicado apenas às bordas inferior e direita, portanto a origem não se desloca e um reescalonamento linear por eixo é suficiente. Limite as coordenadas retornadas às dimensões redimensionadas antes de reescalar, para que um ponto ligeiramente fora da imagem não possa ser mapeado para fora do seu original.

As coordenadas relativas são multiplicadas pela superfície sobre a qual você atua: a imagem original, uma digitalização em resolução total ou uma tela. Quando você atua sobre uma tela e os pixels da captura de tela diferem das coordenadas lógicas (telas HiDPI), divida também pelo fator de escala da tela. A [orientação de escalonamento da ferramenta de uso de computador](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions) aborda esse padrão.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Agent Skills" icon="stack" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/agent-skills/overview">
    Agent Skills são capacidades modulares que estendem a funcionalidade do Claude. Cada Skill empacota instruções, metadados e recursos opcionais (scripts, templates) que o Claude usa automaticamente quando relevante.
  </Card>

  <Card title="Ferramenta de uso de computador" icon="computer" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool">
    Dê ao Claude controle de captura de tela, mouse e teclado de um ambiente de desktop com a ferramenta de uso de computador.
  </Card>

  <Card title="Suporte a PDF" icon="file" href="https://platform.claude.com/docs/pt-BR/build-with-claude/pdf-support">
    Processe PDFs com o Claude. Extraia texto, analise gráficos e compreenda o conteúdo visual dos seus documentos.
  </Card>

  <Card title="Contagem de tokens" icon="calculator" href="https://platform.claude.com/docs/pt-BR/build-with-claude/token-counting">
    Conte os tokens em uma mensagem antes de enviá-la ao Claude. Use contagens de tokens para gerenciar limites de taxa e custos, tomar decisões de roteamento de modelos e ajustar prompts a um comprimento alvo.
  </Card>
</CardGroup>
