Coordonnées et boîtes englobantes

Claude peut localiser et étiqueter des régions d'une image (par exemple, en renvoyant des « bounding boxes » (boîtes englobantes) pour des tableaux, des champs de formulaire, des éléments de graphique ou des composants d'interface utilisateur). Ce guide explique comment Claude redimensionne les images avant de les traiter et comment travailler avec les coordonnées en pixels qu'il renvoie, afin que les boîtes et les points s'alignent sur votre image d'origine.

Vous en aurez besoin pour les pipelines d'OCR, l'extraction de formulaires, l'analyse de graphiques, la localisation d'éléments d'interface utilisateur et toute tâche où vous agissez sur une région spécifique d'une image. Pour l'envoi d'images, les formats pris en charge et les limites de résolution par modèle, consultez Vision.

Les coordonnées suivent la convention standard des images : l'origine (0, 0) est le coin supérieur gauche de l'image, x augmentant vers la droite et y augmentant vers le bas. Les coordonnées que Claude renvoie sont des positions en pixels dans l'image que Claude voit : votre image après que Claude l'a redimensionnée pour l'adapter à la résolution native du modèle (voir Comment Claude redimensionne et complète les images). Pour obtenir des coordonnées directement utilisables, soit vous pré-redimensionnez votre image afin que les coordonnées correspondent une à une à l'image dont vous disposez (voir Redimensionner votre image avant de la téléverser), soit vous remettez à l'échelle les coordonnées que Claude renvoie (voir Remettre à l'échelle les coordonnées lorsque vous ne pouvez pas pré-redimensionner).

Comment Claude redimensionne et complète les images

Claude détermine la plus grande taille préservant le rapport d'aspect qui satisfait les deux limites d'image du modèle :

1. Limite de bord : aucun côté ne dépasse la longueur de bord maximale (1568 px pour le niveau standard, 2576 px pour le niveau haute résolution).
2. Limite de tokens visuels : le coût en tokens de l'image ⌈width / 28⌉ × ⌈height / 28⌉ ne dépasse pas le budget de tokens visuels du modèle (1568 tokens pour le niveau standard, 4784 pour le niveau haute résolution).

Consultez Résolution et coût en tokens pour savoir quels modèles appartiennent à quel niveau.

Pour presque toutes les photos et captures d'écran, c'est la limite de tokens visuels qui détermine la taille finale. La limite de bord ne prend le dessus que pour les images allongées telles que les panoramas ou les longues captures d'écran de téléphone. Calculez la taille avec l'implémentation de référence plutôt qu'en mettant à l'échelle manuellement selon la longueur de bord : une capture d'écran de 1920×1080 est redimensionnée en 1456×819, et non en 1568×882, et supposer que la limite de bord s'applique décale sensiblement chaque coordonnée de sa cible.

La limite de tokens peut également déclencher un redimensionnement lorsqu'aucun côté ne dépasse la limite de bord. Négliger ce point est la cause la plus fréquente de coordonnées mal alignées. Par exemple, une page A4 numérisée à 130 DPI mesure 1075×1520 pixels : les deux côtés sont inférieurs à 1568 px, mais elle coûte 39 × 55 = 2145 tokens visuels, donc Claude la redimensionne en 924×1307.

Claude complète ensuite chaque image par du « padding » (remplissage), redimensionnée ou non, jusqu'au multiple de 28 pixels suivant sur les bords inférieur et droit (924×1307 devient 924×1316 dans l'exemple). Le remplissage ne contient aucun contenu : Claude perçoit l'image complétée, mais le contenu de la page n'occupe jamais que la région redimensionnée sans remplissage. Normalisez ou remettez toujours à l'échelle selon les dimensions redimensionnées, et non selon les dimensions avec remplissage ; diviser par les dimensions avec remplissage décale légèrement chaque coordonnée.

Redimensionner votre image avant de la téléverser

L'approche la plus fiable consiste à redimensionner vous-même votre image avant de la téléverser, de sorte que l'image dont vous disposez soit exactement celle que Claude voit et que les coordonnées renvoyées par Claude ne nécessitent aucune conversion.

Vérifiez d'abord à quel niveau de résolution appartient votre modèle (voir Résolution et coût en tokens) et passez les limites de bord et de tokens correspondantes. L'implémentation de référence suivante calcule la taille exacte à laquelle Claude redimensionne une image :

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)

    # Recherche binaire sur le grand côté pour trouver la plus grande taille
    # préservant le ratio qui tient.
    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'exemple A4 de « Comment Claude redimensionne et complète les images » :
print(resized_size(1075, 1520))  # (924, 1307)

# Pour appliquer le redimensionnement, utilisez votre bibliothèque d'images, par ex. Pillow :
# image.resize(resized_size(*image.size))

1. Redimensionnez l'image aux dimensions renvoyées par la fonction utilitaire de redimensionnement. Si l'image respecte déjà les limites du modèle, la fonction renvoie ses dimensions inchangées et aucun redimensionnement n'est nécessaire.
2. Envoyez l'image redimensionnée à l'API. Ne la complétez pas vous-même. Claude gère le remplissage, et le remplissage ne décale pas l'origine des coordonnées.
3. Dans votre prompt, demandez explicitement des coordonnées en pixels. Par exemple : « Renvoie le point de clic du bouton Submit sous la forme [x, y] en coordonnées en pixels. »
4. Utilisez les coordonnées renvoyées directement sur l'image que vous avez envoyée. Si vous avez besoin de coordonnées normalisées, divisez par les dimensions de l'image que vous avez envoyée, et non par les dimensions de l'image d'origine ni par les dimensions avec remplissage.

Transformer le redimensionnement en erreur avec transformations

Le pré-redimensionnement ne protège vos coordonnées que tant que votre pipeline continue de produire les bonnes tailles. Une nouvelle source d'images ou le passage à un modèle d'un niveau de résolution différent peut réintroduire discrètement le redimensionnement côté serveur. Pour transformer cette dérive silencieuse en erreur visible, définissez le champ facultatif transformations sur un bloc de contenu image dans une requête Messages :

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

Une requête dont une image marquée (tout bloc qui définit "oversized_image": "error") serait redimensionnée est rejetée avec une erreur 400 invalid_request_error indiquant les dimensions de l'image et les plus grandes dimensions acceptables. Le fait qu'une image déclenche ou non le rejet dépend des limites de chaque modèle nommé dans la requête : l'exemple de 1920×1080 ci-dessous est rejeté par un modèle du niveau standard mais respecte le niveau haute résolution :

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"

Remettez à l'échelle selon la cible indiquée et renvoyez la requête : la cible est la plus grande taille, au rapport d'aspect de votre image, que chaque modèle nommé dans la requête accepte. La manière dont les images marquées interagissent avec la bêta de repli côté serveur est décrite avec cette fonctionnalité ; dans tous les modes, une image marquée n'est jamais servie redimensionnée.

Le paramètre s'applique par image. "oversized_image": "downsize" (la valeur par défaut lorsque le champ est omis) conserve le redimensionnement automatique tel que décrit sur cette page. Chaque bloc image n'est vérifié que par rapport à son propre paramètre, de sorte qu'une même requête peut mélanger des images dont les dimensions sont déterminantes (une capture d'écran sur laquelle vous allez cliquer) et des images pour lesquelles le redimensionnement est sans conséquence (un logo). Ce que le paramètre change et ne change pas :

• Le remplissage (qui ne supprime jamais de contenu), la conversion de format et la correction d'orientation se déroulent comme d'habitude.
• Les limites strictes (8000 px sur le côté le plus long, et la limite par image plus stricte pour les requêtes comportant de nombreuses images) constituent des rejets distincts ; ce paramètre ne permet jamais à une image de les franchir.
• Les images fournies par URL ou par ID de fichier sont vérifiées une fois leurs octets récupérés ; ces rejets portent le même message sans la position en tête, de sorte qu'ils n'identifient pas quelle image a échoué ; seules les images base64 intégrées sont désignées par leur position dans l'erreur.
• Les pages PDF sont rastérisées côté serveur à des dimensions que vous ne contrôlez pas ; le bloc document n'accepte pas ce champ (un bloc image imbriqué dans le contenu d'un document l'accepte comme n'importe quel autre).
• Une image marquée dont les dimensions ne peuvent pas être déterminées est rejetée plutôt que transmise : ce rejet indique que les dimensions source de l'image n'ont pas pu être déterminées, et non le message de redimensionnement cité ci-dessus. Aucune image définissant "error" n'atteint le modèle redimensionnée.

Le point de terminaison de comptage des tokens prend également en compte transformations, en rejetant une image intégrée exactement comme le ferait l'API Messages ; vous pouvez ainsi vérifier si une image intégrée est acceptée sans redimensionnement, avant d'exécuter l'inférence. Le comptage rejette les images fournies par URL ou par identifiant de fichier au lieu de les récupérer ; une image marquée provenant de ces sources n'est donc vérifiée qu'au moment de l'appel à Messages.

Remettre à l'échelle les coordonnées lorsque vous ne pouvez pas pré-redimensionner

Si vous ne pouvez pas pré-redimensionner (par exemple, lorsque l'image provient d'un système en amont que vous ne pouvez pas modifier), utilisez la fonction utilitaire de redimensionnement de Redimensionner votre image avant de la téléverser pour retrouver les dimensions que Claude a vues, puis convertissez les coordonnées renvoyées par Claude en coordonnées normalisées ou reportez-les sur votre image d'origine. À moins qu'une image n'opte pour une erreur à la place, Claude redimensionne les images trop grandes plutôt que de les rejeter, jusqu'aux limites de requête de l'API. Au-delà de ces limites, la requête échoue avec une erreur de validation. Passez les limites de niveau correspondant au modèle que vous avez appelé : les limites du mauvais niveau retrouvent de mauvaises dimensions redimensionnées et décalent silencieusement chaque coordonnée. Cette approche nécessite de connaître les dimensions en pixels de l'image que vous avez téléversée, elle ne s'applique donc pas aux téléversements de PDF.

Les captures d'écran et les images de zoom que vous renvoyez aux ensembles d'outils d'utilisation de l'ordinateur et d'utilisation du navigateur constituent une exception au redimensionnement automatique. L'API rejette une image tool_result qui dépasse les limites du modèle avec une erreur de validation au lieu de la redimensionner. Redimensionnez ces images dans votre application avant de les renvoyer, puis remettez à l'échelle les coordonnées renvoyées par Claude selon les dimensions de votre écran.

# Cet utilitaire appelle resized_size de l'exemple de redimensionnement sur cette page.
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 coin de tableau que Claude renvoie en (462, 653.5) sur la page A4 redimensionnée
# se reporte sur l'original 1075x1520 comme suit :
rel_x, rel_y = to_relative_coordinates(462, 653.5, 1075, 1520)
print((rel_x * 1075, rel_y * 1520))  # (537.5, 760.0)

Le remplissage n'est appliqué que sur les bords inférieur et droit, de sorte que l'origine ne se décale pas et qu'une remise à l'échelle linéaire par axe suffit. Bornez les coordonnées renvoyées aux dimensions redimensionnées avant de les remettre à l'échelle, afin qu'un point légèrement en dehors de l'image ne puisse pas être reporté en dehors de votre original.

Les coordonnées relatives se multiplient par la surface sur laquelle vous agissez, quelle qu'elle soit : l'image d'origine, une numérisation en pleine résolution ou un écran. Lorsque vous agissez sur un écran et que les pixels de la capture d'écran diffèrent des coordonnées logiques (écrans HiDPI), divisez également par le facteur d'échelle de l'affichage. Les recommandations de mise à l'échelle de l'outil d'utilisation de l'ordinateur couvrent ce cas.

Étapes suivantes