Vision

Ce guide décrit comment travailler avec des images dans Claude, y compris les bonnes pratiques, des exemples de code et les limitations à garder à l'esprit.



Comment utiliser la vision

Utilisez les capacités de vision de Claude via :

• claude.ai. Téléversez une image comme vous le feriez pour un fichier, ou glissez-déposez une image directement dans la fenêtre de conversation.
• Le Workbench de la Console. Un bouton pour ajouter des images apparaît en haut à droite de chaque bloc de message Utilisateur.
• Une requête API. Consultez les exemples de ce guide.

Plusieurs images peuvent être incluses dans une seule requête, que Claude analysera conjointement lors de la formulation de sa réponse. Cela peut être utile pour comparer ou mettre en contraste des images.



Avant de téléverser



Limites générales

Le nombre maximal d'images par message ou par requête est :

• 20 par message sur claude.ai.
• 100 par requête sur l'API, pour les modèles avec une fenêtre de contexte de 200k tokens.
• 600 par requête sur l'API, pour tous les autres modèles.

Les dimensions maximales par image sont de 8000x8000 px.

Si une seule requête API contient plus de 20 images, une limite de dimension par image plus stricte s'applique. Sur Amazon Bedrock et Vertex AI, les blocs de documents tels que les PDF comptent également dans ce seuil. Les images dépassant la limite plus stricte sont rejetées avec une erreur invalid_request_error dont le message fait référence à « many-image requests » et indique la limite actuelle en pixels. Pour rester sous la limite sur toutes les plateformes, redimensionnez chaque image de sorte qu'aucune dimension ne dépasse 2000 px, ou limitez la requête à 20 blocs d'images et de documents ou moins.

La taille maximale par image est :

• 10 Mo (encodée en base64) lors de l'utilisation directe de l'API Claude.
• 5 Mo (encodée en base64) sur Amazon Bedrock et Vertex AI.
• 10 Mo sur claude.ai.



Évaluer la taille de l'image

Claude voit les images sous forme de « patches » (blocs) plutôt que de pixels. Chaque patch est un bloc de 28×28 pixels de l'image, appelé token visuel. Une image coûte donc ⌈largeur / 28⌉ × ⌈hauteur / 28⌉ tokens visuels.

Si Claude reçoit une image trop grande, il la redimensionne. La résolution d'image native maximale est :

• Pour Claude Fable 5 et Claude Mythos 5 : 4784 tokens, et au plus 2576 pixels sur le bord long.
• Pour Claude Opus 4.8 : 4784 tokens, et au plus 2576 pixels sur le bord long.
• Pour Claude Opus 4.7 : 4784 tokens, et au plus 2576 pixels sur le bord long.
• Pour les autres modèles : 1568 tokens, et au plus 1568 pixels sur le bord long.

Pour minimiser la latence et simplifier les flux de travail basés sur les coordonnées, vous devriez privilégier le redimensionnement des images avant de les téléverser.



Calculer les coûts d'image

Chaque image que vous incluez dans une requête à Claude compte dans votre utilisation de tokens. Pour calculer le coût approximatif, multipliez le nombre de tokens visuels de l'image (voir Évaluer la taille de l'image) par le prix par token du modèle que vous utilisez.

Voici des exemples de tokenisation et de coûts approximatifs pour différentes tailles d'images dans les contraintes de taille de l'API, basés sur le prix par token de Claude Sonnet 4.6 de 3 $ par million de tokens d'entrée :

Notez que les trois dernières images dépassent la résolution native et sont réduites avant traitement (à 1456x819 px, 1270x952 px et 1456x819 px respectivement), ce qui plafonne leur coût en tokens. L'image 4K ne coûte pas plus que l'image 1920x1080 car les deux sont réduites à la même taille ; la résolution supplémentaire est ignorée.



Prise en charge des images haute résolution

Claude Opus 4.7 est le premier modèle Claude avec prise en charge des images haute résolution ; Claude Opus 4.8, Claude Fable 5, Claude Mythos 5 et les modèles ultérieurs la prennent également en charge. La résolution d'image maximale est de 2576 pixels sur le bord long, contre 1568 px sur les modèles précédents. Cela débloque des gains de performance sur les charges de travail à forte composante visuelle et est particulièrement précieux pour l'utilisation d'ordinateur, la compréhension de captures d'écran et l'analyse de documents.

La prise en charge haute résolution est automatique sur Claude Opus 4.7 et les modèles ultérieurs et ne nécessite aucun en-tête bêta ni activation côté client.

Les images haute résolution sur Claude Opus 4.7, Claude Opus 4.8, Claude Fable 5 et Claude Mythos 5 peuvent utiliser jusqu'à environ 3x plus de tokens d'image que sur les modèles précédents (4784 contre 1568 tokens par image). Si vous n'avez pas besoin de la fidélité supplémentaire, sous-échantillonnez les images avant de les envoyer pour contrôler les coûts en tokens.

Voici les mêmes tailles d'images tokenisées pour Claude Opus 4.7 et Claude Opus 4.8, basées sur leur prix par token de 5 $ par million de tokens d'entrée :

Seule la dernière image dépasse les limites supérieures : l'image 4K est réduite à 2576x1449 px avant traitement. La prise en charge haute résolution augmente les limites de résolution mais ne les supprime pas ; les images de plus de 2576 px sur le bord long (ou 4784 tokens visuels) sont toujours réduites.



Assurer la qualité de l'image

Lorsque vous fournissez des images à Claude, gardez à l'esprit les points suivants pour obtenir les meilleurs résultats :

• Format d'image : Utilisez un format d'image pris en charge : JPEG, PNG, GIF ou WebP.
  Les animations ne sont pas prises en charge, et seule la première image sera utilisée.
• Clarté de l'image : Assurez-vous que les images sont claires et pas trop floues ou pixelisées.
• Texte : Si l'image contient du texte important, assurez-vous qu'il est lisible et pas trop petit. Évitez de rogner le contexte visuel clé uniquement pour agrandir le texte.
• Redimensionnement : Tenez compte du fait que votre image pourrait être redimensionnée si elle est trop grande (voir ci-dessus) ; cela pourrait par exemple rendre le texte moins lisible. Envisagez de pré-redimensionner vos images, de les rogner, ou les deux.
• Compression d'image : Compresser les images avant de les envoyer, en utilisant un format avec perte tel que JPEG ou WebP (mode avec perte), peut réduire la latence en réduisant la taille des requêtes. Cependant, cela peut introduire des artefacts nuisibles aux performances du modèle, en particulier lorsque plusieurs passes de compression sont appliquées. Par exemple, une compression JPEG importante peut rendre le texte difficile à lire. Confirmez que vos paramètres de compression sont appropriés pour la tâche en inspectant les images réellement envoyées à l'API.



Travailler avec des coordonnées et des boîtes englobantes

Claude peut localiser et étiqueter des régions d'une image (par exemple, renvoyer des « bounding boxes » (boîtes englobantes) pour des tableaux, des champs de formulaire, des éléments de graphique ou des composants d'interface utilisateur).

Les coordonnées suivent la convention d'image standard : l'origine (0, 0) est le coin supérieur gauche de l'image, avec x augmentant vers la droite et y augmentant vers le bas. Les coordonnées que Claude renvoie sont des positions de pixels dans l'image que Claude voit : votre image après que Claude l'a redimensionnée pour s'adapter à la résolution native du modèle (voir Comment Claude redimensionne et remplit les images). Pour obtenir des coordonnées que vous pouvez utiliser directement, soit pré-redimensionnez votre image afin que les coordonnées correspondent une à une à l'image que vous avez (voir Redimensionner votre image avant de la téléverser), soit 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 remplit les images

Claude trouve 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 la plupart des modèles, 2576 px pour Claude Opus 4.7 et les modèles ultérieurs).
2. Limite de tokens visuels : le coût en tokens de l'image ⌈largeur / 28⌉ × ⌈hauteur / 28⌉ ne dépasse pas le budget de tokens visuels du modèle (1568 tokens pour la plupart des modèles, 4784 pour Claude Opus 4.7 et les modèles ultérieurs).

Pour la plupart des photos et captures d'écran, c'est la limite de bord qui déclenche un redimensionnement. Pour les documents en portrait, la limite de tokens visuels se déclenche généralement en premier, et l'ignorer est la cause la plus courante de coordonnées mal alignées. Par exemple, une page A4 numérisée à 130 DPI fait 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 à 924×1307.

Claude remplit ensuite chaque image, qu'elle ait été 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 remplie, mais le contenu de la page n'occupe jamais que la région redimensionnée non remplie. Normalisez ou remettez toujours à l'échelle par les dimensions redimensionnées, pas par les dimensions remplies ; diviser par les dimensions remplies décale chaque coordonnée d'une petite quantité.



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 que vous avez soit exactement l'image que Claude voit et que les coordonnées que Claude renvoie ne nécessitent aucune conversion.

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 most models. For Claude Opus 4.7 and later 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 côté long pour la plus grande taille préservant
    # le ratio d'aspect 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 remplit les images » :
print(resized_size(1075, 1520))  # (924, 1307)

1. Redimensionnez l'image aux dimensions renvoyées par resized_size. Si l'image tient déjà dans les limites du modèle, resized_size renvoie ses dimensions inchangées et aucun redimensionnement n'est nécessaire.
2. Envoyez l'image redimensionnée à l'API. Ne la remplissez 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 de pixels. Par exemple : « Renvoie la boîte englobante de chaque tableau sous la forme [x1, y1, x2, y2] en coordonnées de 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, pas par les dimensions de l'image originale ni par les dimensions remplies.



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 resized_size de Redimensionner votre image avant de la téléverser pour récupérer les dimensions que Claude a vues, puis mappez les coordonnées que Claude renvoie en coordonnées normalisées ou sur votre image originale. 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.

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 Claude Opus 4.7 and
    later 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)


# Pour exprimer la coordonnée dans l'espace de pixels de votre image d'origine, multipliez la
# coordonnée relative par vos dimensions d'origine :
# (rel_x * largeur_originale, rel_y * hauteur_originale)

Le remplissage n'est appliqué qu'aux bords inférieur et droit, donc l'origine ne se décale pas et une remise à l'échelle linéaire par axe est suffisante.



Exemples de prompts

De nombreuses techniques de prompting qui fonctionnent bien pour les interactions textuelles avec Claude peuvent également être appliquées aux prompts basés sur des images.

Ces exemples démontrent les structures de prompts de bonnes pratiques impliquant des images.



À propos des exemples de prompts

Les exemples suivants démontrent comment utiliser les capacités de vision de Claude en utilisant divers langages de programmation et approches. Vous pouvez fournir des images à Claude de trois manières :

1. En tant qu'image encodée en base64 dans des blocs de contenu image
2. En tant que référence URL vers une image hébergée en ligne
3. En utilisant l'API Files (téléversez une fois, utilisez plusieurs fois)

Les exemples de prompts base64 utilisent ces variables :

import base64
import httpx

# Pour les images encodées en base64
image1_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image1_media_type = "image/jpeg"
image1_data = base64.standard_b64encode(httpx.get(image1_url).content).decode("utf-8")

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

# Pour les images basées sur une URL, vous pouvez utiliser les URL directement dans vos requêtes

Voici des exemples de comment inclure des images dans une requête de l'API Messages en utilisant des images encodées en base64 et des références URL :



Exemple d'image encodée en base64

image1_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"
image1_media_type = "image/png"

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image1_media_type,
                        "data": image1_data,
                    },
                },
                {"type": "text", "text": "Describe this image."},
            ],
        }
    ],
)
print(message)



Exemple d'image basée sur URL

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
                    },
                },
                {"type": "text", "text": "Describe this image."},
            ],
        }
    ],
)
print(message)



Exemple d'image avec l'API Files

Pour les images que vous utiliserez de manière répétée ou lorsque vous souhaitez éviter la surcharge d'encodage, utilisez l'API Files. Téléversez l'image une fois, puis référencez le file_id renvoyé dans les messages suivants au lieu de renvoyer les données base64.

client = anthropic.Anthropic()

# Téléverser le fichier image
with open("image.jpg", "rb") as f:
    file_upload = client.beta.files.upload(file=("image.jpg", f, "image/jpeg"))

# Utiliser le fichier téléversé dans un message
message = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    betas=["files-api-2025-04-14"],
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {"type": "file", "file_id": file_upload.id},
                },
                {"type": "text", "text": "Describe this image."},
            ],
        }
    ],
)

print(message.content)

Consultez les exemples de l'API Messages pour plus d'exemples de code et de détails sur les paramètres.



Limitations

Bien que les capacités de compréhension d'images de Claude soient à la pointe de la technologie, il existe certaines limitations à connaître :

• Identification de personnes : Claude ne peut pas être utilisé pour nommer des personnes dans des images et refuse de le faire.
• Précision : Claude peut halluciner ou faire des erreurs lors de l'interprétation d'images de faible qualité, pivotées ou très petites de moins de 200 pixels.
• Raisonnement spatial : Les sorties de coordonnées et de localisation de Claude sont approximatives. Suivez les conseils de Travailler avec des coordonnées et des boîtes englobantes et vérifiez les sorties avant de vous y fier.
• Comptage : Claude peut donner des comptages approximatifs d'objets dans une image mais peut ne pas toujours être précisément exact, en particulier avec un grand nombre de petits objets.
• Images générées par IA : Claude ne sait pas si une image est générée par IA et peut se tromper si on le lui demande. Ne comptez pas sur lui pour détecter des images fausses ou synthétiques.
• Contenu inapproprié : Claude ne traite pas les images inappropriées ou explicites qui violent la Politique d'utilisation acceptable.
• Applications de santé : Bien que Claude puisse analyser des images médicales générales, il n'est pas conçu pour interpréter des examens diagnostiques complexes tels que les scanners ou les IRM. Les sorties de Claude ne doivent pas être considérées comme un substitut à un avis médical professionnel ou à un diagnostic.

Examinez et vérifiez toujours attentivement les interprétations d'images de Claude, en particulier pour les cas d'usage à enjeux élevés. N'utilisez pas Claude pour des tâches nécessitant une précision parfaite ou une analyse d'images sensibles sans supervision humaine.



FAQ



Approfondir la vision

Prêt à commencer à construire avec des images en utilisant Claude ? Voici quelques ressources utiles :

• Cookbook multimodal : Ce cookbook contient des conseils pour démarrer avec les images et des techniques de bonnes pratiques pour garantir les meilleures performances avec les images. Découvrez comment vous pouvez efficacement formuler des prompts à Claude avec des images pour effectuer des tâches telles que l'interprétation et l'analyse de graphiques ou l'extraction de contenu à partir de formulaires.
• Référence API : Documentation pour l'API Messages, y compris des exemples d'appels API impliquant des images.

Si vous avez d'autres questions, contactez l'équipe d'assistance. Vous pouvez également rejoindre la communauté de développeurs pour vous connecter avec d'autres créateurs et obtenir de l'aide des experts Anthropic.