---
title: Coordinate e bounding box
url: https://platform.claude.com/docs/it/build-with-claude/vision-coordinates
description: Come Claude ridimensiona le immagini e come lavorare con le coordinate in pixel che restituisce per bounding box, punti ed elementi dell'interfaccia utente.
---

Claude può individuare ed etichettare regioni di un'immagine (ad esempio, restituendo "bounding box" (riquadri di delimitazione) per tabelle, campi di moduli, elementi di grafici o componenti dell'interfaccia utente). Questa guida spiega come Claude ridimensiona le immagini prima di elaborarle e come lavorare con le coordinate in pixel che restituisce, in modo che riquadri e punti si allineino con la tua immagine originale.

Ne avrai bisogno per pipeline OCR, estrazione di moduli, analisi di grafici, localizzazione di elementi dell'interfaccia utente e qualsiasi attività in cui agisci su una regione specifica di un'immagine. Per l'invio di immagini, i formati supportati e i limiti di risoluzione per modello, consulta [Visione](https://platform.claude.com/docs/it/build-with-claude/vision).

<Note>
  **Claude funziona meglio con coordinate in pixel assolute.** Richiedile esplicitamente nel tuo prompt. Ad esempio: *"Restituisci il bounding box di ogni tabella come `[x1, y1, x2, y2]` (angoli in alto a sinistra e in basso a destra) in coordinate in pixel."* Claude non funziona bene quando chiedi coordinate normalizzate, ad esempio: *"Restituisci le coordinate del bounding box tra `0` e `1000`."* Chiedi sempre coordinate in pixel e normalizza nel tuo codice se necessario. Per ottenere le coordinate come JSON leggibile da una macchina invece che in prosa, definisci uno schema con gli [output strutturati](https://platform.claude.com/docs/it/build-with-claude/structured-outputs), ad esempio un oggetto con un array `[x1, y1, x2, y2]` per ogni elemento rilevato.
</Note>

Le coordinate seguono la convenzione standard delle immagini: l'origine `(0, 0)` è l'angolo in alto a sinistra dell'immagine, con x che aumenta verso destra e y che aumenta verso il basso. Le coordinate che Claude restituisce sono posizioni in pixel nell'immagine che Claude vede: la tua immagine dopo che Claude l'ha ridimensionata per adattarla alla risoluzione nativa del modello (vedi [Come Claude ridimensiona e aggiunge padding alle immagini](https://platform.claude.com/docs/it/build-with-claude/vision-coordinates#how-claude-resizes-and-pads-images)). Per ottenere coordinate che puoi usare direttamente, pre-ridimensiona la tua immagine in modo che le coordinate corrispondano uno a uno all'immagine che hai (vedi [Ridimensiona la tua immagine prima del caricamento](https://platform.claude.com/docs/it/build-with-claude/vision-coordinates#resize-your-image-before-uploading)), oppure riscala le coordinate che Claude restituisce (vedi [Riscala le coordinate quando non puoi pre-ridimensionare](https://platform.claude.com/docs/it/build-with-claude/vision-coordinates#rescale-coordinates-when-you-cannot-pre-resize)).

<Note>
  Il ragionamento spaziale di Claude ha dei limiti (vedi [Limitazioni](https://platform.claude.com/docs/it/build-with-claude/vision#limitations)). La precisione delle coordinate è migliore quando indichi il formato di coordinate atteso nel tuo prompt e verifichi visivamente i risultati a campione prima di elaborare su larga scala. Gli elementi piccoli perdono precisione quando un'immagine viene ridotta: per obiettivi di piccole dimensioni, ritaglia la regione di interesse e invia il ritaglio (trasla le coordinate restituite dell'origine del ritaglio), oppure usa un modello del livello ad alta risoluzione. Per il [supporto PDF](https://platform.claude.com/docs/it/build-with-claude/pdf-support), le pagine vengono rasterizzate in immagini lato server a dimensioni che non controlli, quindi le coordinate restituite non possono essere mappate in modo affidabile sulla pagina. Per lavorare con le coordinate sul contenuto PDF, rasterizza tu stesso le pagine in immagini e usa l'approccio del pre-ridimensionamento.
</Note>

## Come Claude ridimensiona e aggiunge padding alle immagini

Claude trova la dimensione più grande che preserva le proporzioni e soddisfa entrambi i limiti di immagine del modello:

1. **Limite del lato:** nessun lato supera la lunghezza massima del lato (1568 px nel livello standard, 2576 px nel livello ad alta risoluzione).
2. **Limite di token visivi:** il costo in token dell'immagine `⌈width / 28⌉ × ⌈height / 28⌉` non supera il budget di token visivi del modello (1568 token nel livello standard, 4784 nel livello ad alta risoluzione).

Consulta [Risoluzione e costo in token](https://platform.claude.com/docs/it/build-with-claude/vision#evaluate-image-size) per sapere quali modelli appartengono a quale livello.

Per quasi tutte le foto e gli screenshot, è il limite di token visivi a determinare la dimensione finale. Il limite del lato prevale solo per immagini allungate come panorami o screenshot alti di telefoni. Calcola la dimensione con l'[implementazione di riferimento](https://platform.claude.com/docs/it/build-with-claude/vision-coordinates#resize-your-image-before-uploading) invece di scalare manualmente alla lunghezza del lato: uno screenshot 1920×1080 viene ridimensionato a 1456×819, non a 1568×882, e presumere il limite del lato sposta ogni coordinata sensibilmente fuori bersaglio.

Il limite di token può anche attivare un ridimensionamento quando nessun lato supera il limite del lato. Trascurare questo aspetto è la causa più comune di coordinate disallineate. Ad esempio, una pagina A4 scansionata a 130 DPI è di 1075×1520 pixel: entrambi i lati sono sotto i 1568 px, ma costa `39 × 55 = 2145` token visivi, quindi Claude la ridimensiona a 924×1307.

<Note>
  Questo esempio presuppone un modello del livello di risoluzione standard. Un modello del livello ad alta risoluzione non ridimensiona la stessa scansione: 2145 token rientrano nel suo budget di 4784 token, quindi le coordinate che restituisce corrispondono direttamente all'originale 1075×1520. I livelli dei modelli sono elencati in [Risoluzione e costo in token](https://platform.claude.com/docs/it/build-with-claude/vision#evaluate-image-size).
</Note>

Claude aggiunge poi "padding" (riempimento) a ogni immagine, ridimensionata o meno, fino al successivo multiplo di 28 pixel sui bordi inferiore e destro (924×1307 diventa 924×1316 nell'esempio). Il padding non contiene alcun contenuto: Claude percepisce l'immagine con padding, ma il contenuto della pagina occupa sempre e solo la regione ridimensionata senza padding. **Normalizza o riscala sempre in base alle dimensioni ridimensionate, non alle dimensioni con padding**; dividere per le dimensioni con padding scala ogni coordinata di una piccola quantità.

## Ridimensiona la tua immagine prima del caricamento

L'approccio più affidabile è ridimensionare tu stesso l'immagine prima del caricamento, in modo che l'immagine che hai sia esattamente l'immagine che Claude vede e le coordinate che Claude restituisce non richiedano alcuna conversione.

Per prima cosa verifica a quale livello di risoluzione appartiene il tuo modello (vedi [Risoluzione e costo in token](https://platform.claude.com/docs/it/build-with-claude/vision#evaluate-image-size)) e passa i limiti di lato e di token corrispondenti. La seguente implementazione di riferimento calcola la dimensione esatta a cui Claude ridimensiona un'immagine:

<CodeGroup exclude="shell">
  <CodeGroupItem language="cURL">
    Calcola questa dimensione nel codice.
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    Calcola questa dimensione nel codice.
  </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)

      # Ricerca binaria lungo il lato maggiore per la dimensione massima che preserva
      # le proporzioni e rientra nei limiti.
      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))


  # L'esempio A4 da "How Claude resizes and pads images":
  print(resized_size(1075, 1520))  # (924, 1307)

  # Per applicare il ridimensionamento, usa la tua libreria di immagini, ad esempio 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];
    }

    // Ricerca binaria lungo il lato lungo per la dimensione massima che preserva
    // le proporzioni e rientra nei limiti.
    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)];
  }

  // L'esempio A4 da "How Claude resizes and pads images":
  console.log(resizedSize(1075, 1520)); // [ 924, 1307 ]

  // Per applicare il ridimensionamento, usa la tua libreria di immagini, ad es. sharp:
  // await sharp(input).resize(width, height).toBuffer()
  ```

  ```csharp C#
  // Token visivi consumati da un'immagine: un token per ogni patch di 28x28 pixel.
  static int CountImageTokens(int width, int height)
  {
      return (width + 27) / 28 * ((height + 27) / 28); // ceil(w/28) * ceil(h/28)
  }

  // Dimensione a cui Claude ridimensiona un'immagine prima del padding. I default sono per
  // il livello a risoluzione standard; per i modelli del livello ad alta risoluzione, passa
  // maxEdge: 2576, maxTokens: 4784. Le immagini che rientrano già nei limiti
  // vengono restituite invariate.
  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);
      }

      // Ricerca binaria lungo il lato lungo per la dimensione massima che preserva
      // le proporzioni e rientra nei limiti. Il lato corto arrotonda .5 al pari, come
      // l'API live sui .5 esatti (MidpointRounding.ToEven, default di 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);
  }

  // L'esempio A4 da "How Claude resizes and pads images":
  Console.WriteLine(ResizedSize(1075, 1520)); // (924, 1307)
  ```

  ```go Go
  // countImageTokens è il numero di token visivi consumati da un'immagine: un token per
  // ogni patch di 28x28 pixel.
  func countImageTokens(width, height int) int {
  	return ((width + 27) / 28) * ((height + 27) / 28) // ceil(w/28) * ceil(h/28)
  }

  // resizedSize è la dimensione a cui Claude ridimensiona un'immagine prima del padding, come
  // (width, height). Passa maxEdge 1568 e maxTokens 1568 per il livello di risoluzione
  // standard, oppure 2576 e 4784 per il livello ad alta risoluzione. Le immagini
  // che rientrano già nei limiti vengono restituite invariate.
  // L'esempio A4 da "How Claude resizes and pads images":
  // resizedSize(1075, 1520, 1568, 1568) restituisce (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
  	}

  	// Ricerca binaria lungo il lato lungo per la dimensione massima che preserva
  	// le proporzioni e rientra nei limiti. Il lato corto arrotonda .5 al pari (math.RoundToEven),
  	// in linea con l'API live sui tie esatti a .5; math.Round li arrotonderebbe per eccesso.
  	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());
      }

      // Ricerca binaria sul lato lungo per la dimensione massima che preserva
      // l'aspect ratio e rientra nei limiti. Il lato corto arrotonda .5 al pari
      // (Math.rint), come l'API live sui .5 esatti; Math.round arrotonderebbe in su.
      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
  // Token visivi consumati da un'immagine: un token per ogni patch di 28x28 pixel.
  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];
      }

      // Ricerca binaria lungo il lato lungo per la dimensione massima che preserva
      // le proporzioni e rientra nel limite. Il lato corto arrotonda .5 al pari
      // (PHP_ROUND_HALF_EVEN), in linea con l'API live nei casi di .5 esatto.
      $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)];
  }

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

  ```ruby Ruby
  # Token visivi consumati da un'immagine: un token per ogni patch di 28x28 pixel.
  def count_image_tokens(width, height)
    width.ceildiv(28) * height.ceildiv(28)
  end

  # Dimensione a cui Claude ridimensiona un'immagine prima del padding, come [width, height].
  #
  # I valori predefiniti sono per il livello a risoluzione standard. Per i modelli del livello
  # ad alta risoluzione, passa max_edge: 2576, max_tokens: 4784. Le immagini che già
  # rientrano nei limiti vengono restituite invariate.
  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

    # Ricerca binaria lungo il lato lungo per trovare la dimensione massima che preserva
    # le proporzioni e rientra nei limiti. Il lato corto arrotonda .5 al pari (round(half: :even)),
    # in linea con l'API live nei casi di parità esatta a .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

  # L'esempio A4 da "How Claude resizes and pads images":
  p resized_size(1075, 1520) # => [924, 1307]
  ```
</CodeGroup>

1. Ridimensiona l'immagine alle dimensioni restituite dall'helper di ridimensionamento. Se l'immagine rientra già nei limiti del modello, l'helper restituisce le sue dimensioni invariate e non è necessario alcun ridimensionamento.
2. [Invia l'immagine ridimensionata](https://platform.claude.com/docs/it/build-with-claude/vision#send-images-to-claude) all'API. Non aggiungere padding tu stesso. Claude gestisce il padding, e il padding non sposta l'origine delle coordinate.
3. Nel tuo prompt, chiedi esplicitamente coordinate in pixel. Ad esempio: *"Restituisci il punto di clic per il pulsante Submit come `[x, y]` in coordinate in pixel."*
4. Usa le coordinate restituite direttamente sull'immagine che hai inviato. Se hai bisogno di coordinate normalizzate, dividi per le dimensioni dell'immagine che hai inviato, non per le dimensioni dell'immagine originale e non per le dimensioni con padding.

<Note>
  L'endpoint di [Conteggio dei token](https://platform.claude.com/docs/it/build-with-claude/token-counting) stima il costo in token di un'immagine dalle sue dimensioni senza elaborarla completamente, quindi un conteggio riuscito non significa che l'immagine rientri nei [limiti delle richieste](https://platform.claude.com/docs/it/build-with-claude/vision#request-limits) della Messages API. Un'immagine può essere conteggiata con successo ed essere comunque rifiutata quando la invii.
</Note>

## Trasforma il ridimensionamento in un errore con `transformations`

Il pre-ridimensionamento protegge le tue coordinate solo finché la tua pipeline continua a produrre le dimensioni corrette. Una nuova sorgente di immagini o il passaggio a un modello di un livello di risoluzione diverso può reintrodurre silenziosamente il ridimensionamento lato server. Per trasformare questa deriva silenziosa in un errore visibile, imposta il campo opzionale `transformations` su un blocco di contenuto immagine in una richiesta [Messages](https://platform.claude.com/docs/it/api/messages):

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

Una richiesta la cui immagine contrassegnata (qualsiasi blocco che imposta `"oversized_image": "error"`) verrebbe ridimensionata viene rifiutata con un errore 400 `invalid_request_error` che indica le dimensioni dell'immagine e le dimensioni massime che rientrano nei limiti. Se un'immagine attiva il rifiuto dipende dai [limiti di ogni modello indicato nella richiesta](https://platform.claude.com/docs/it/build-with-claude/vision-coordinates#how-claude-resizes-and-pads-images): l'esempio 1920×1080 qui sotto viene rifiutato da un modello del livello standard ma rientra nel livello ad alta risoluzione:

```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"
```

Riscala alla dimensione di destinazione indicata e invia di nuovo: la destinazione è la dimensione più grande, con le proporzioni della tua immagine, che ogni modello indicato nella richiesta accetta. Il modo in cui le immagini contrassegnate interagiscono con la [beta del fallback lato server](https://platform.claude.com/docs/it/build-with-claude/refusals-and-fallback#server-side-fallback) è descritto insieme a quella funzionalità; in ogni modalità, un'immagine contrassegnata non viene mai servita ridimensionata.

L'impostazione è per singola immagine. `"oversized_image": "downsize"` (il valore predefinito quando il campo è omesso) mantiene il ridimensionamento automatico come descritto in questa pagina. Ogni blocco immagine viene verificato solo rispetto alla propria impostazione, quindi una singola richiesta può combinare immagini le cui dimensioni sono determinanti (uno screenshot su cui farai clic) con immagini per cui il ridimensionamento è innocuo (un logo). Cosa cambia e cosa non cambia con questa impostazione:

* Il padding ([che non scarta mai contenuto](https://platform.claude.com/docs/it/build-with-claude/vision-coordinates#how-claude-resizes-and-pads-images)), la conversione di formato e la correzione dell'orientamento procedono come di consueto.
* I limiti rigidi (8000 px sul lato più lungo e il limite per immagine più restrittivo nelle [richieste con molte immagini](https://platform.claude.com/docs/it/build-with-claude/vision#request-limits)) sono rifiuti separati; questa impostazione non permette mai a un'immagine di superarli.
* Le immagini fornite tramite URL o ID file vengono verificate una volta recuperati i loro byte; questi rifiuti riportano lo stesso messaggio senza la posizione iniziale, quindi non identificano quale immagine ha fallito; solo le immagini base64 incorporate vengono indicate per posizione nell'errore.
* Le [pagine PDF](https://platform.claude.com/docs/it/build-with-claude/pdf-support) vengono rasterizzate lato server a dimensioni che non controlli; il blocco `document` non accetta il campo (un blocco immagine annidato nel contenuto di un documento lo accetta come qualsiasi altro).
* Un'immagine contrassegnata le cui dimensioni non possono essere determinate viene rifiutata anziché lasciata passare: quel rifiuto segnala che le dimensioni di origine dell'immagine non hanno potuto essere determinate, non il messaggio di ridimensionamento citato sopra. Nessuna immagine che imposta `"error"` raggiunge il modello ridimensionata.

Anche l'endpoint di [conteggio dei token](https://platform.claude.com/docs/it/build-with-claude/token-counting) rispetta `transformations`, rifiutando un'immagine incorporata esattamente come farebbe la Messages API, così puoi verificare se un'immagine incorporata rientra nei limiti senza essere ridimensionata, prima di eseguire l'inferenza. Il conteggio rifiuta le immagini fornite tramite URL o ID file anziché recuperarle, quindi un'immagine contrassegnata proveniente da queste sorgenti viene verificata solo al momento della chiamata Messages.

## Riscala le coordinate quando non puoi pre-ridimensionare

Se non puoi pre-ridimensionare (ad esempio, quando l'immagine proviene da un sistema a monte che non puoi modificare), usa l'helper di ridimensionamento di [Ridimensiona la tua immagine prima del caricamento](https://platform.claude.com/docs/it/build-with-claude/vision-coordinates#resize-your-image-before-uploading) per recuperare le dimensioni che Claude ha visto, quindi mappa le coordinate che Claude restituisce in coordinate normalizzate o di nuovo sulla tua immagine originale. A meno che un'immagine non [scelga invece un errore](https://platform.claude.com/docs/it/build-with-claude/vision-coordinates#oversized-image-error), Claude ridimensiona le immagini troppo grandi anziché rifiutarle, fino ai [limiti delle richieste](https://platform.claude.com/docs/it/build-with-claude/vision#request-limits) dell'API. Oltre questi limiti la richiesta fallisce invece con un errore di validazione. Passa i limiti del livello corrispondenti al modello che hai chiamato: i limiti del livello sbagliato recuperano le dimensioni ridimensionate sbagliate e spostano silenziosamente ogni coordinata. Questo approccio richiede di conoscere le dimensioni in pixel dell'immagine che hai caricato, quindi non si applica ai caricamenti di PDF.

Gli screenshot e le immagini di zoom che restituisci ai set di strumenti di [computer use](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions) e [browser use](https://platform.claude.com/docs/it/agents-and-tools/tool-use/browser-use-tool#targets-and-coordinates) sono un'eccezione al ridimensionamento automatico. L'API rifiuta un'immagine `tool_result` che supera i limiti del modello con un errore di validazione invece di ridimensionarla. Ridimensiona queste immagini nella tua applicazione prima di restituirle, quindi riscala le coordinate che Claude restituisce alle dimensioni del tuo schermo.

<CodeGroup exclude="shell">
  <CodeGroupItem language="cURL">
    Converti le coordinate nel codice.
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    Converti le coordinate nel codice.
  </CodeGroupItem>

  ```python Python
  # Questo helper chiama resized_size dall'esempio di ridimensionamento in questa pagina.
  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)


  # Un angolo di tabella che Claude restituisce a (462, 653.5) sulla pagina A4 ridimensionata
  # si mappa sull'originale 1075x1520 così:
  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
  // Questo helper chiama resizedSize dall'esempio di ridimensionamento in questa pagina.
  /**
   * 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];
  }

  // Un angolo di tabella che Claude restituisce a (462, 653.5) sulla pagina A4 ridimensionata
  // si mappa sull'originale 1075x1520 così:
  const [relX, relY] = toRelativeCoordinates(462, 653.5, 1075, 1520);
  console.log([relX * 1075, relY * 1520]); // [ 537.5, 760 ]
  ```

  ```csharp C#
  // Questo helper chiama ResizedSize dall'esempio di ridimensionamento in questa pagina.
  // Mappa una coordinata in pixel restituita da Claude a coordinate relative in
  // [0, 1]. Passa le dimensioni dell'immagine caricata e gli stessi limiti di
  // livello usati per 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);
  }

  // Un angolo di tabella che Claude restituisce a (462, 653.5) sulla pagina A4 ridimensionata
  // si rimappa sull'originale 1075x1520 così:
  (double relX, double relY) = ToRelativeCoordinates(462, 653.5, 1075, 1520);
  Console.WriteLine((relX * 1075, relY * 1520)); // (537.5, 760)
  ```

  ```go Go
  // Questo helper chiama resizedSize dall'esempio di ridimensionamento in questa pagina.

  // toRelativeCoordinates mappa una coordinata in pixel restituita da Claude a
  // coordinate relative in [0, 1]. Passa le dimensioni dell'immagine che hai
  // caricato e gli stessi limiti di livello usati per 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)
  }

  // Per tornare allo spazio pixel dell'immagine originale, moltiplica per le dimensioni
  // originali: un angolo di tabella restituito a (462, 653.5) sulla pagina A4 ridimensionata
  // è (relX*1075, relY*1520) = (537.5, 760) sull'originale 1075x1520.
  ```

  ```java Java
  // Questo helper chiama resizedSize dall'esempio di ridimensionamento in questa pagina.
  /** 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());
  }

  // Per riportare le coordinate nello spazio pixel dell'immagine originale, moltiplica
  // per le dimensioni originali: un angolo di tabella restituito a (462, 653.5) sulla
  // pagina A4 ridimensionata è (relative.x() * 1075, relative.y() * 1520) = (537.5, 760)
  // sull'originale 1075x1520.
  ```

  ```php PHP
  // Questo helper chiama resizedSize() dall'esempio di ridimensionamento in questa pagina.
  /**
   * 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];
  }

  // Un angolo di tabella che Claude restituisce a (462, 653.5) sulla pagina A4 ridimensionata
  // si mappa sull'originale 1075x1520 così:
  [$relX, $relY] = toRelativeCoordinates(462, 653.5, 1075, 1520);
  echo '(' . $relX * 1075 . ', ' . $relY * 1520 . ")\n"; // (537.5, 760)
  ```

  ```ruby Ruby
  # Questo helper chiama resized_size dall'esempio di ridimensionamento in questa pagina.
  # Mappa una coordinata in pixel restituita da Claude a coordinate relative in
  # [0, 1], come [x, y]. Passa le dimensioni dell'immagine caricata e gli
  # stessi limiti di livello usati per 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

  # Un angolo di tabella che Claude restituisce a (462, 653.5) sulla pagina A4 ridimensionata
  # si mappa sull'originale 1075x1520 così:
  rel_x, rel_y = to_relative_coordinates(462, 653.5, 1075, 1520)
  p [rel_x * 1075, rel_y * 1520] # => [537.5, 760.0]
  ```
</CodeGroup>

Il padding viene applicato solo ai bordi inferiore e destro, quindi l'origine non si sposta ed è sufficiente una riscalatura lineare per asse. Limita le coordinate restituite alle dimensioni ridimensionate prima di riscalare, in modo che un punto leggermente fuori dall'immagine non possa essere mappato fuori dal tuo originale.

Le coordinate relative si moltiplicano per qualsiasi superficie su cui agisci: l'immagine originale, una scansione a piena risoluzione o uno schermo. Quando agisci su uno schermo e i pixel dello screenshot differiscono dalle coordinate logiche (display HiDPI), dividi anche per il fattore di scala del display. Le [indicazioni sulla scalatura dello strumento Computer use](https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions) trattano questo schema.

## Prossimi passi

<CardGroup cols={2}>
  <Card title="Agent Skills" icon="stack" href="https://platform.claude.com/docs/it/agents-and-tools/agent-skills/overview">
    Le Agent Skills sono capacità modulari che estendono le funzionalità di Claude. Ogni Skill raggruppa istruzioni, metadati e risorse opzionali (script, template) che Claude usa automaticamente quando pertinenti.
  </Card>

  <Card title="Strumento Computer use" icon="computer" href="https://platform.claude.com/docs/it/agents-and-tools/tool-use/computer-use-tool">
    Dai a Claude il controllo di screenshot, mouse e tastiera di un ambiente desktop con lo strumento computer use.
  </Card>

  <Card title="Supporto PDF" icon="file" href="https://platform.claude.com/docs/it/build-with-claude/pdf-support">
    Elabora PDF con Claude. Estrai testo, analizza grafici e comprendi il contenuto visivo dei tuoi documenti.
  </Card>

  <Card title="Conteggio dei token" icon="calculator" href="https://platform.claude.com/docs/it/build-with-claude/token-counting">
    Conta i token in un messaggio prima di inviarlo a Claude. Usa i conteggi dei token per gestire limiti di velocità e costi, prendere decisioni di instradamento dei modelli e adattare i prompt a una lunghezza target.
  </Card>
</CardGroup>
