좌표와 바운딩 박스

Claude는 이미지의 영역을 찾아 레이블을 지정할 수 있습니다(예: 표, 양식 필드, 차트 요소 또는 UI 구성 요소에 대한 바운딩 박스 반환). 이 가이드에서는 Claude가 이미지를 처리하기 전에 크기를 조정하는 방식과, 박스와 점이 원본 이미지와 정확히 맞도록 Claude가 반환하는 픽셀 좌표를 다루는 방법을 설명합니다.

이 내용은 OCR 파이프라인, 양식 추출, 차트 파싱, UI 요소 위치 찾기, 그리고 이미지의 특정 영역에 대해 작업을 수행하는 모든 작업에 필요합니다. 이미지 전송, 지원되는 형식, 모델별 해상도 제한에 대해서는 비전을 참조하세요.

좌표는 표준 이미지 규칙을 따릅니다. 원점 (0, 0)은 이미지의 왼쪽 위 모서리이며, x는 오른쪽으로 증가하고 y는 아래쪽으로 증가합니다. Claude가 반환하는 좌표는 Claude가 보는 이미지, 즉 Claude가 모델의 기본 해상도에 맞게 크기를 조정한 후의 이미지에서의 픽셀 위치입니다(Claude가 이미지 크기를 조정하고 패딩하는 방식 참조). 바로 사용할 수 있는 좌표를 얻으려면, 좌표가 보유한 이미지에 일대일로 매핑되도록 이미지를 미리 크기 조정하거나(업로드 전에 이미지 크기 조정 참조), Claude가 반환하는 좌표를 다시 스케일링하세요(미리 크기 조정할 수 없는 경우 좌표 재스케일링 참조).

Claude가 이미지 크기를 조정하고 패딩하는 방식

Claude는 모델의 두 가지 이미지 제한을 모두 충족하면서 종횡비를 유지하는 가장 큰 크기를 찾습니다.

1. 가장자리 제한: 어느 변도 최대 가장자리 길이(표준 티어에서 1568 px, 고해상도 티어에서 2576 px)를 초과하지 않습니다.
2. 시각 토큰 제한: 이미지의 토큰 비용 ⌈width / 28⌉ × ⌈height / 28⌉이 모델의 시각 토큰 예산(표준 티어에서 1568 토큰, 고해상도 티어에서 4784 토큰)을 초과하지 않습니다.

어떤 모델이 어떤 티어에 속하는지는 해상도와 토큰 비용을 참조하세요.

거의 모든 사진과 스크린샷에서 최종 크기를 결정하는 것은 시각 토큰 제한입니다. 가장자리 제한은 파노라마나 세로로 긴 휴대폰 스크린샷과 같이 길쭉한 이미지에서만 적용됩니다. 가장자리 길이에 맞춰 수동으로 스케일링하지 말고 참조 구현으로 크기를 계산하세요. 1920×1080 스크린샷은 1568×882가 아니라 1456×819로 크기가 조정되며, 가장자리 제한을 가정하면 모든 좌표가 눈에 띄게 대상에서 벗어납니다.

토큰 제한은 어느 변도 가장자리 제한을 초과하지 않는 경우에도 크기 조정을 유발할 수 있습니다. 이를 간과하는 것이 좌표 불일치의 가장 흔한 원인입니다. 예를 들어 130 DPI로 스캔한 A4 페이지는 1075×1520 픽셀입니다. 두 변 모두 1568 px 미만이지만 39 × 55 = 2145 시각 토큰이 소요되므로 Claude는 이를 924×1307로 크기 조정합니다.

그런 다음 Claude는 크기 조정 여부와 관계없이 모든 이미지를 아래쪽과 오른쪽 가장자리에서 다음 28픽셀 배수까지 패딩합니다(예시에서 924×1307은 924×1316이 됩니다). 패딩에는 콘텐츠가 없습니다. Claude는 패딩된 이미지를 인식하지만, 페이지 콘텐츠는 항상 패딩되지 않은 크기 조정 영역만 차지합니다. 항상 패딩된 크기가 아닌 크기 조정된 크기로 정규화하거나 재스케일링하세요. 패딩된 크기로 나누면 모든 좌표가 약간씩 스케일링됩니다.

업로드 전에 이미지 크기 조정

가장 안정적인 방법은 업로드 전에 이미지를 직접 크기 조정하는 것입니다. 그러면 보유한 이미지가 Claude가 보는 이미지와 정확히 같아지고, Claude가 반환하는 좌표를 변환할 필요가 없습니다.

먼저 모델이 어떤 해상도 티어에 속하는지 확인하고(해상도와 토큰 비용 참조) 해당하는 가장자리 및 토큰 제한을 전달하세요. 다음 참조 구현은 Claude가 이미지를 크기 조정하는 정확한 크기를 계산합니다.

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)

    # 긴 변을 따라 이진 탐색하여 종횡비를 유지하면서 들어맞는
    # 최대 크기를 찾습니다.
    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))


# "Claude가 이미지를 리사이즈하고 패딩하는 방법"의 A4 예제:
print(resized_size(1075, 1520))  # (924, 1307)

# 리사이즈를 적용하려면 Pillow 같은 이미지 라이브러리를 사용하세요:
# image.resize(resized_size(*image.size))

1. 크기 조정 헬퍼가 반환한 크기로 이미지를 크기 조정하세요. 이미지가 이미 모델의 제한 내에 있으면 헬퍼는 크기를 변경하지 않고 반환하며 크기 조정이 필요하지 않습니다.
2. 크기 조정된 이미지를 API로 전송하세요. 직접 패딩하지 마세요. Claude가 패딩을 처리하며, 패딩은 좌표 원점을 이동시키지 않습니다.
3. 프롬프트에서 픽셀 좌표를 명시적으로 요청하세요. 예: "Submit 버튼의 클릭 지점을 픽셀 좌표로 [x, y] 형식으로 반환하세요."
4. 반환된 좌표를 전송한 이미지에 대해 직접 사용하세요. 정규화된 좌표가 필요한 경우, 원본 이미지의 크기나 패딩된 크기가 아닌 전송한 이미지의 크기로 나누세요.

transformations로 크기 조정을 오류로 전환

미리 크기 조정하는 방식은 파이프라인이 계속 올바른 크기를 생성하는 동안에만 좌표를 보호합니다. 새로운 이미지 소스나 다른 해상도 티어의 모델로 전환하면 서버 측 크기 조정이 조용히 다시 발생할 수 있습니다. 이러한 눈에 띄지 않는 변화를 가시적인 오류로 전환하려면 Messages 요청의 이미지 콘텐츠 블록에 선택적 transformations 필드를 설정하세요.

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

표시된 이미지("oversized_image": "error"를 설정한 모든 블록)가 크기 조정될 요청은 이미지의 크기와 맞는 가장 큰 크기를 명시하는 400 invalid_request_error로 거부됩니다. 이미지가 거부를 유발하는지 여부는 요청에 명시된 모든 모델의 제한에 따라 달라집니다. 아래의 1920×1080 예시는 표준 티어 모델에서는 거부되지만 고해상도 티어에는 맞습니다.

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"

보고된 대상 크기로 재스케일링하고 다시 전송하세요. 대상 크기는 이미지의 종횡비에서 요청에 명시된 모든 모델이 허용하는 가장 큰 크기입니다. 표시된 이미지가 서버 측 폴백 베타와 상호작용하는 방식은 해당 기능과 함께 설명되어 있습니다. 모든 모드에서 표시된 이미지는 절대 크기 조정된 상태로 제공되지 않습니다.

이 설정은 이미지별로 적용됩니다. "oversized_image": "downsize"(필드가 생략된 경우의 기본값)는 이 페이지에 설명된 대로 자동 크기 조정을 유지합니다. 각 이미지 블록은 자체 설정에 대해서만 검사되므로, 하나의 요청에서 크기가 중요한 이미지(클릭할 스크린샷)와 크기 조정이 무해한 이미지(로고)를 혼합할 수 있습니다. 이 설정이 변경하는 것과 변경하지 않는 것은 다음과 같습니다.

• 패딩(콘텐츠를 절대 버리지 않음), 형식 변환, 방향 보정은 평소대로 진행됩니다.
• 하드 제한(가장 긴 변 8000 px, 그리고 다중 이미지 요청에 대한 더 엄격한 이미지별 제한)은 별도의 거부 사유이며, 이 설정은 이미지가 이를 통과하도록 허용하지 않습니다.
• URL 또는 파일 ID로 제공된 이미지는 바이트를 가져온 후에 검사됩니다. 이러한 거부는 앞부분의 위치 정보 없이 동일한 메시지를 전달하므로 어떤 이미지가 실패했는지 식별하지 않습니다. 임베드된 base64 이미지만 오류에서 위치로 명시됩니다.
• PDF 페이지는 서버 측에서 사용자가 제어할 수 없는 크기로 래스터화됩니다. document 블록은 이 필드를 허용하지 않습니다(문서 콘텐츠 내에 중첩된 이미지 블록은 다른 이미지 블록과 마찬가지로 허용합니다).
• 크기를 확인할 수 없는 표시된 이미지는 통과되지 않고 거부됩니다. 해당 거부는 위에 인용된 크기 조정 메시지가 아니라 이미지의 소스 크기를 확인할 수 없다고 보고합니다. "error"를 설정한 이미지는 크기 조정된 상태로 모델에 도달하지 않습니다.

토큰 카운팅 엔드포인트도 transformations를 준수하여 Messages API와 정확히 동일하게 임베드된 이미지를 거부하므로, 추론을 실행하기 전에 임베드된 이미지가 크기 조정 없이 맞는지 확인할 수 있습니다. 카운팅은 URL 또는 파일 ID로 제공된 이미지를 가져오지 않고 거부하므로, 이러한 소스의 표시된 이미지는 Messages 요청 시점에만 검사됩니다.

미리 크기 조정할 수 없는 경우 좌표 재스케일링

미리 크기 조정할 수 없는 경우(예: 수정할 수 없는 업스트림 시스템에서 이미지가 오는 경우), 업로드 전에 이미지 크기 조정의 크기 조정 헬퍼를 사용하여 Claude가 본 크기를 복원한 다음, Claude가 반환하는 좌표를 정규화된 좌표로 매핑하거나 원본 이미지로 다시 매핑하세요. 이미지가 대신 오류를 선택하지 않는 한, Claude는 API의 요청 제한까지는 크기가 큰 이미지를 거부하지 않고 크기 조정합니다. 해당 제한을 넘으면 요청은 대신 유효성 검사 오류로 실패합니다. 호출한 모델에 맞는 티어 제한을 전달하세요. 잘못된 티어의 제한은 잘못된 크기 조정 크기를 복원하여 모든 좌표를 조용히 이동시킵니다. 이 방식은 업로드한 이미지의 픽셀 크기를 알아야 하므로 PDF 업로드에는 적용되지 않습니다.

컴퓨터 사용 및 브라우저 사용 도구 세트에 반환하는 스크린샷과 확대 이미지는 자동 크기 조정의 예외입니다. API는 모델의 제한을 초과하는 tool_result 이미지를 크기 조정하는 대신 유효성 검사 오류로 거부합니다. 해당 이미지를 반환하기 전에 애플리케이션에서 크기 조정한 다음, Claude가 반환하는 좌표를 화면 크기로 다시 스케일링하세요.

# 이 헬퍼는 이 페이지의 리사이즈 예제에 있는 resized_size를 호출합니다.
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)


# 리사이즈된 A4 페이지에서 Claude가 (462, 653.5)로 반환한 테이블 모서리는
# 1075x1520 원본으로 다음과 같이 매핑됩니다:
rel_x, rel_y = to_relative_coordinates(462, 653.5, 1075, 1520)
print((rel_x * 1075, rel_y * 1520))  # (537.5, 760.0)

패딩은 아래쪽과 오른쪽 가장자리에만 적용되므로 원점이 이동하지 않으며, 축별 선형 재스케일링으로 충분합니다. 재스케일링 전에 반환된 좌표를 크기 조정된 크기로 클램핑하여, 이미지를 약간 벗어난 점이 원본 바깥으로 매핑되지 않도록 하세요.

상대 좌표는 작업 대상이 되는 어떤 표면에든 곱할 수 있습니다. 원본 이미지, 전체 해상도 스캔 또는 화면이 될 수 있습니다. 화면에서 작업하고 스크린샷 픽셀이 논리 좌표와 다른 경우(HiDPI 디스플레이), 디스플레이 스케일 팩터로도 나누세요. 컴퓨터 사용 도구의 스케일링 가이드에서 해당 패턴을 다룹니다.

다음 단계