Koordinaten und Bounding Boxes

Claude kann Bereiche eines Bildes lokalisieren und beschriften (zum Beispiel „bounding boxes“ (Begrenzungsrahmen) für Tabellen, Formularfelder, Diagrammelemente oder UI-Komponenten zurückgeben). Dieser Leitfaden behandelt, wie Claude Bilder vor der Verarbeitung skaliert und wie du mit den zurückgegebenen Pixelkoordinaten arbeitest, damit Boxen und Punkte mit deinem Originalbild übereinstimmen.

Du brauchst das für OCR-Pipelines, Formularextraktion, Diagramm-Parsing, die Lokalisierung von UI-Elementen und jede Aufgabe, bei der du auf einen bestimmten Bereich eines Bildes einwirkst. Informationen zum Senden von Bildern, zu unterstützten Formaten und zu modellspezifischen Auflösungsgrenzen findest du unter Vision.

Koordinaten folgen der üblichen Bildkonvention: Der Ursprung (0, 0) ist die obere linke Ecke des Bildes, wobei x nach rechts und y nach unten zunimmt. Die Koordinaten, die Claude zurückgibt, sind Pixelpositionen in dem Bild, das Claude sieht: dein Bild, nachdem Claude es auf die native Auflösung des Modells skaliert hat (siehe Wie Claude Bilder skaliert und auffüllt). Um Koordinaten zu erhalten, die du direkt verwenden kannst, skaliere dein Bild entweder vorab, sodass die Koordinaten eins zu eins auf das Bild abgebildet werden, das du hast (siehe Skaliere dein Bild vor dem Hochladen), oder skaliere die von Claude zurückgegebenen Koordinaten um (siehe Koordinaten umskalieren, wenn du nicht vorab skalieren kannst).

Wie Claude Bilder skaliert und auffüllt

Claude ermittelt die größte seitenverhältniserhaltende Größe, die beide Bildgrenzen des Modells erfüllt:

1. Kantengrenze: Keine Seite überschreitet die maximale Kantenlänge (1568 px auf der Standardstufe, 2576 px auf der hochauflösenden Stufe).
2. Grenze für visuelle Token: Die Token-Kosten des Bildes ⌈width / 28⌉ × ⌈height / 28⌉ überschreiten nicht das Budget des Modells für visuelle Token (1568 Token auf der Standardstufe, 4784 auf der hochauflösenden Stufe).

Unter Auflösung und Token-Kosten findest du, welche Modelle zu welcher Stufe gehören.

Bei fast allen Fotos und Screenshots bestimmt die Grenze für visuelle Token die endgültige Größe. Die Kantengrenze greift nur bei langgestreckten Bildern wie Panoramen oder hohen Smartphone-Screenshots. Berechne die Größe mit der Referenzimplementierung, statt von Hand auf die Kantenlänge zu skalieren: Ein 1920×1080-Screenshot wird auf 1456×819 skaliert, nicht auf 1568×882, und die Annahme der Kantengrenze verschiebt jede Koordinate merklich vom Ziel.

Die Token-Grenze kann auch dann eine Skalierung auslösen, wenn keine Seite die Kantengrenze überschreitet. Dies zu übersehen ist die häufigste Ursache für falsch ausgerichtete Koordinaten. Eine mit 130 DPI gescannte A4-Seite ist zum Beispiel 1075×1520 Pixel groß: Beide Seiten liegen unter 1568 px, aber sie kostet 39 × 55 = 2145 visuelle Token, sodass Claude sie auf 924×1307 skaliert.

Claude füllt dann jedes Bild, ob skaliert oder nicht, an der unteren und rechten Kante bis zum nächsten Vielfachen von 28 Pixeln auf („padding“ (Auffüllung); 924×1307 wird im Beispiel zu 924×1316). Das Padding enthält keinen Inhalt: Claude nimmt das aufgefüllte Bild wahr, aber der Seiteninhalt belegt immer nur den nicht aufgefüllten, skalierten Bereich. Normalisiere oder skaliere immer anhand der skalierten Abmessungen, nicht der aufgefüllten Abmessungen; das Teilen durch die aufgefüllten Abmessungen verschiebt jede Koordinate um einen kleinen Betrag.

Skaliere dein Bild vor dem Hochladen

Der zuverlässigste Ansatz ist, dein Bild vor dem Hochladen selbst zu skalieren, sodass das Bild, das du hast, genau das Bild ist, das Claude sieht, und die von Claude zurückgegebenen Koordinaten keine Umrechnung benötigen.

Prüfe zuerst, auf welcher Auflösungsstufe sich dein Modell befindet (siehe Auflösung und Token-Kosten), und übergib die passenden Kanten- und Token-Grenzen. Die folgende Referenzimplementierung berechnet die genaue Größe, auf die Claude ein Bild skaliert:

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)

    # Binärsuche entlang der langen Kante nach der größten seitenverhältnis-
    # treuen Größe, die passt.
    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))


# Das A4-Beispiel aus „How Claude resizes and pads images“:
print(resized_size(1075, 1520))  # (924, 1307)

# Für das Resize nutze deine Bildbibliothek, z. B. Pillow:
# image.resize(resized_size(*image.size))

1. Skaliere das Bild auf die vom Resize-Helper zurückgegebenen Abmessungen. Wenn das Bild bereits in die Grenzen des Modells passt, gibt der Helper seine Abmessungen unverändert zurück und es ist keine Skalierung nötig.
2. Sende das skalierte Bild an die API. Fülle es nicht selbst auf. Claude übernimmt das Padding, und Padding verschiebt den Koordinatenursprung nicht.
3. Frage in deinem Prompt ausdrücklich nach Pixelkoordinaten. Zum Beispiel: „Gib den Klickpunkt für die Schaltfläche Submit als [x, y] in Pixelkoordinaten zurück."
4. Verwende die zurückgegebenen Koordinaten direkt auf dem Bild, das du gesendet hast. Wenn du normalisierte Koordinaten brauchst, teile durch die Abmessungen des gesendeten Bildes, nicht durch die Abmessungen des Originalbildes und nicht durch die aufgefüllten Abmessungen.

Skalierung mit transformations in einen Fehler verwandeln

Die Vorab-Skalierung schützt deine Koordinaten nur, solange deine Pipeline weiterhin die richtigen Größen erzeugt. Eine neue Bildquelle oder der Wechsel zu einem Modell auf einer anderen Auflösungsstufe kann die serverseitige Skalierung unbemerkt wieder einführen. Um diese stille Abweichung in einen sichtbaren Fehler zu verwandeln, setze das optionale Feld transformations auf einem Bild-Content-Block in einer Messages-Anfrage:

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

Eine Anfrage, deren markiertes Bild (jeder Block, der "oversized_image": "error" setzt) skaliert werden würde, wird mit einem 400 invalid_request_error abgelehnt, der die Abmessungen des Bildes und die größten passenden Abmessungen nennt. Ob ein Bild die Ablehnung auslöst, hängt von den Grenzen jedes in der Anfrage genannten Modells ab: Das 1920×1080-Beispiel unten wird von einem Modell der Standardstufe abgelehnt, passt aber in die hochauflösende Stufe:

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"

Skaliere auf das gemeldete Ziel und sende erneut: Das Ziel ist die größte Größe im Seitenverhältnis deines Bildes, die jedes in der Anfrage genannte Modell akzeptiert. Wie markierte Bilder mit der Beta für serverseitiges Fallback zusammenwirken, ist bei dieser Funktion beschrieben; in jedem Modus wird ein markiertes Bild niemals skaliert ausgeliefert.

Die Einstellung gilt pro Bild. "oversized_image": "downsize" (der Standard, wenn das Feld weggelassen wird) behält die automatische Skalierung wie auf dieser Seite beschrieben bei. Jeder Bildblock wird nur gegen seine eigene Einstellung geprüft, sodass eine Anfrage Bilder mischen kann, deren Abmessungen tragend sind (ein Screenshot, auf den du klicken wirst), mit Bildern, bei denen eine Skalierung harmlos ist (ein Logo). Was die Einstellung ändert und was nicht:

• Padding (das niemals Inhalt verwirft), Formatkonvertierung und Ausrichtungskorrektur laufen wie gewohnt ab.
• Die harten Grenzen (8000 px an der längsten Seite und die strengere Grenze pro Bild bei Anfragen mit vielen Bildern) sind separate Ablehnungen; diese Einstellung lässt ein Bild niemals an ihnen vorbei.
• Per URL oder Datei-ID bereitgestellte Bilder werden geprüft, sobald ihre Bytes abgerufen wurden; diese Ablehnungen tragen dieselbe Meldung ohne die führende Position, sodass sie nicht angeben, welches Bild fehlgeschlagen ist; nur eingebettete Base64-Bilder werden im Fehler nach Position benannt.
• PDF-Seiten werden serverseitig mit Abmessungen gerastert, die du nicht kontrollierst; der document-Block akzeptiert das Feld nicht (ein im Inhalt eines Dokuments verschachtelter Bildblock akzeptiert es wie jeder andere).
• Ein markiertes Bild, dessen Abmessungen nicht ermittelt werden können, wird abgelehnt statt durchgereicht: Diese Ablehnung meldet, dass die Quellabmessungen des Bildes nicht ermittelt werden konnten, nicht die oben zitierte Skalierungsmeldung. Kein Bild, das "error" setzt, erreicht das Modell skaliert.

Der Endpunkt für die Token-Zählung berücksichtigt transformations ebenfalls und lehnt ein eingebettetes Bild genau so ab, wie es die Messages API tun würde. So kannst du vor der Inferenz prüfen, ob ein eingebettetes Bild ohne Skalierung passt. Die Zählung lehnt per URL oder Datei-ID bereitgestellte Bilder ab, anstatt sie abzurufen, sodass ein markiertes Bild aus diesen Quellen erst beim Messages-Aufruf geprüft wird.

Koordinaten umskalieren, wenn du nicht vorab skalieren kannst

Wenn du nicht vorab skalieren kannst (zum Beispiel, wenn das Bild aus einem vorgelagerten System stammt, das du nicht ändern kannst), verwende den Resize-Helper aus Skaliere dein Bild vor dem Hochladen, um die Abmessungen zu ermitteln, die Claude gesehen hat, und bilde dann die von Claude zurückgegebenen Koordinaten auf normalisierte Koordinaten oder zurück auf dein Originalbild ab. Sofern ein Bild nicht stattdessen einen Fehler wählt, skaliert Claude übergroße Bilder, statt sie abzulehnen, bis zu den Anfragegrenzen der API. Jenseits dieser Grenzen schlägt die Anfrage stattdessen mit einem Validierungsfehler fehl. Übergib die Stufengrenzen, die zu dem aufgerufenen Modell passen: Die Grenzen der falschen Stufe ermitteln die falschen skalierten Abmessungen und verschieben unbemerkt jede Koordinate. Dieser Ansatz setzt voraus, dass du die Pixelabmessungen des hochgeladenen Bildes kennst, und gilt daher nicht für PDF-Uploads.

Screenshots und Zoom-Bilder, die du an die Toolsets für Computer Use und Browser Use zurückgibst, sind eine Ausnahme von der automatischen Skalierung. Die API lehnt ein tool_result-Bild, das die Grenzen des Modells überschreitet, mit einem Validierungsfehler ab, statt es zu skalieren. Skaliere diese Bilder in deiner Anwendung, bevor du sie zurückgibst, und skaliere dann die von Claude zurückgegebenen Koordinaten zurück auf die Abmessungen deines Bildschirms.

# Dieser Helper ruft resized_size aus dem Resize-Beispiel dieser Seite auf.
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)


# Eine Tabellenecke, die Claude bei (462, 653.5) auf der skalierten A4-Seite
# liefert, wird so auf das 1075x1520-Original zurückgerechnet:
rel_x, rel_y = to_relative_coordinates(462, 653.5, 1075, 1520)
print((rel_x * 1075, rel_y * 1520))  # (537.5, 760.0)

Padding wird nur an der unteren und rechten Kante angewendet, sodass sich der Ursprung nicht verschiebt und eine lineare Umskalierung pro Achse ausreicht. Begrenze die zurückgegebenen Koordinaten vor dem Umskalieren auf die skalierten Abmessungen, damit ein Punkt leicht außerhalb des Bildes nicht außerhalb deines Originals abgebildet werden kann.

Die relativen Koordinaten werden mit der Fläche multipliziert, auf der du agierst: dem Originalbild, einem Scan in voller Auflösung oder einem Bildschirm. Wenn du auf einem Bildschirm agierst und sich Screenshot-Pixel von logischen Koordinaten unterscheiden (HiDPI-Displays), teile zusätzlich durch den Skalierungsfaktor des Displays. Die Skalierungshinweise des Computer-Use-Tools behandeln dieses Muster.

Nächste Schritte