비전

이 가이드는 Claude에서 이미지를 사용하는 방법을 설명하며, 모범 사례, 코드 예제, 그리고 염두에 두어야 할 제한 사항을 포함합니다.



비전 사용 방법

다음을 통해 Claude의 비전 기능을 사용하세요:

• claude.ai. 파일을 업로드하듯이 이미지를 업로드하거나, 이미지를 채팅 창에 직접 드래그 앤 드롭하세요.
• Console Workbench. 모든 User 메시지 블록의 오른쪽 상단에 이미지를 추가하는 버튼이 나타납니다.
• API 요청. 이 가이드의 예제를 참조하세요.

단일 요청에 여러 이미지를 포함할 수 있으며, Claude는 응답을 작성할 때 이를 함께 분석합니다. 이는 이미지를 비교하거나 대조하는 데 유용할 수 있습니다.



업로드 전 확인 사항



일반 제한 사항

메시지 또는 요청당 최대 이미지 수는 다음과 같습니다:

• claude.ai에서는 메시지당 20개.
• 200k 토큰 컨텍스트 윈도우를 가진 모델의 경우 API에서 요청당 100개.
• 그 외 모든 모델의 경우 API에서 요청당 600개.

이미지당 최대 크기는 8000x8000 px입니다.

단일 API 요청에 20개를 초과하는 이미지가 포함된 경우, 더 엄격한 이미지별 크기 제한이 적용됩니다. Amazon Bedrock 및 Vertex AI에서는 PDF와 같은 문서 블록도 이 임계값에 포함됩니다. 더 엄격한 제한을 초과하는 이미지는 "many-image requests"를 참조하고 현재 픽셀 제한을 명시하는 메시지가 포함된 invalid_request_error와 함께 거부됩니다. 모든 플랫폼에서 제한을 초과하지 않으려면 각 이미지의 어느 쪽 크기도 2000 px를 초과하지 않도록 크기를 조정하거나, 요청을 20개 이하의 이미지 및 문서 블록으로 유지하세요.

이미지당 최대 크기는 다음과 같습니다:

• Claude API를 직접 사용하는 경우 10 MB (base64 인코딩).
• Amazon Bedrock 및 Vertex AI에서는 5 MB (base64 인코딩).
• claude.ai에서는 10 MB.



이미지 크기 평가

Claude는 픽셀 대신 패치 단위로 이미지를 봅니다. 각 패치는 이미지의 28×28 픽셀 블록이며, 이를 "visual token"(비주얼 토큰)이라고 합니다. 따라서 이미지는 ⌈width / 28⌉ × ⌈height / 28⌉ 비주얼 토큰을 소비합니다.

Claude가 너무 큰 이미지를 받으면 크기를 조정합니다. 최대 기본 이미지 해상도는 다음과 같습니다:

• Claude Fable 5 및 Claude Mythos 5의 경우: 4784 토큰, 긴 변 기준 최대 2576 픽셀.
• Claude Opus 4.8의 경우: 4784 토큰, 긴 변 기준 최대 2576 픽셀.
• Claude Opus 4.7의 경우: 4784 토큰, 긴 변 기준 최대 2576 픽셀.
• 기타 모델의 경우: 1568 토큰, 긴 변 기준 최대 1568 픽셀.

"Latency"(지연 시간)를 최소화하고 좌표 기반 워크플로를 단순화하려면 업로드하기 전에 이미지 크기를 조정하는 것이 좋습니다.



이미지 비용 계산

요청에 포함하는 각 이미지는 토큰 사용량에 포함됩니다. 대략적인 비용을 계산하려면 이미지의 비주얼 토큰 수(이미지 크기 평가 참조)에 사용 중인 모델의 토큰당 가격을 곱하세요.

다음은 Claude Sonnet 4.6의 입력 토큰 100만 개당 $3의 토큰당 가격을 기준으로, API의 크기 제약 내에서 다양한 이미지 크기에 대한 토큰화 및 대략적인 비용 예시입니다:

마지막 세 이미지는 기본 해상도를 초과하므로 처리 전에 축소됩니다(각각 1456x819 px, 1270x952 px, 1456x819 px로). 이로 인해 토큰 비용이 제한됩니다. 4K 이미지는 1920x1080 이미지와 동일한 크기로 축소되므로 비용이 더 들지 않으며, 추가 해상도는 버려집니다.



고해상도 이미지 지원

Claude Opus 4.7은 고해상도 이미지를 지원하는 최초의 Claude 모델이며, Claude Opus 4.8, Claude Fable 5, Claude Mythos 5 및 이후 모델도 이를 지원합니다. 최대 이미지 해상도는 긴 변 기준 2576 픽셀로, 이전 모델의 1568 px에서 증가했습니다. 이는 비전 중심 워크로드에서 성능 향상을 가능하게 하며, 특히 컴퓨터 사용, 스크린샷 이해 및 문서 분석에 유용합니다.

고해상도 지원은 Claude Opus 4.7 및 이후 모델에서 자동으로 적용되며 베타 헤더나 클라이언트 측 옵트인이 필요하지 않습니다.

Claude Opus 4.7, Claude Opus 4.8, Claude Fable 5 및 Claude Mythos 5의 고해상도 이미지는 이전 모델보다 최대 약 3배 더 많은 이미지 토큰을 사용할 수 있습니다(이미지당 4784 대 1568 토큰). 추가 정밀도가 필요하지 않은 경우, 토큰 비용을 제어하기 위해 전송하기 전에 이미지를 다운샘플링하세요.

다음은 Claude Opus 4.7 및 Claude Opus 4.8의 입력 토큰 100만 개당 $5의 토큰당 가격을 기준으로 동일한 이미지 크기를 토큰화한 결과입니다:

마지막 이미지만 더 높은 제한을 초과합니다: 4K 이미지는 처리 전에 2576x1449 px로 축소됩니다. 고해상도 지원은 해상도 제한을 높이지만 제거하지는 않습니다. 긴 변이 2576 px(또는 4784 비주얼 토큰)를 초과하는 이미지는 여전히 축소됩니다.



이미지 품질 확인

Claude에 이미지를 제공할 때 최상의 결과를 얻으려면 다음 사항을 염두에 두세요:

• 이미지 형식: 지원되는 이미지 형식(JPEG, PNG, GIF 또는 WebP)을 사용하세요.
  애니메이션은 지원되지 않으며 첫 번째 프레임만 사용됩니다.
• 이미지 선명도: 이미지가 선명하고 너무 흐릿하거나 픽셀화되지 않았는지 확인하세요.
• 텍스트: 이미지에 중요한 텍스트가 포함된 경우, 읽을 수 있고 너무 작지 않은지 확인하세요. 텍스트를 확대하기 위해 주요 시각적 맥락을 잘라내지 마세요.
• 크기 조정: 이미지가 너무 크면 크기가 조정될 수 있다는 점을 고려하세요(위 참조). 예를 들어 이로 인해 텍스트가 덜 읽기 쉬워질 수 있습니다. 이미지를 미리 크기 조정하거나 자르거나 둘 다 수행하는 것을 고려하세요.
• 이미지 압축: JPEG 또는 WebP(손실 모드)와 같은 손실 형식을 사용하여 이미지를 전송하기 전에 압축하면 요청 크기를 줄여 지연 시간을 줄일 수 있습니다. 그러나 이는 모델 성능에 해로운 아티팩트를 유발할 수 있으며, 특히 여러 번의 압축이 적용될 때 그렇습니다. 예를 들어, 과도한 JPEG 압축은 텍스트를 읽기 어렵게 만들 수 있습니다. API로 전송되는 실제 이미지를 검사하여 압축 설정이 작업에 적합한지 확인하세요.



좌표 및 바운딩 박스 작업

Claude는 이미지의 영역을 찾아 레이블을 지정할 수 있습니다(예: 표, 양식 필드, 차트 요소 또는 UI 구성 요소에 대한 바운딩 박스 반환).

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



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

Claude는 모델의 두 가지 이미지 제한을 모두 충족하는 종횡비를 유지하는 최대 크기를 찾습니다:

1. 가장자리 제한: 어느 쪽도 최대 가장자리 길이를 초과하지 않습니다(대부분의 모델은 1568 px, Claude Opus 4.7 및 이후 모델은 2576 px).
2. 비주얼 토큰 제한: 이미지의 토큰 비용 ⌈width / 28⌉ × ⌈height / 28⌉이 모델의 비주얼 토큰 예산을 초과하지 않습니다(대부분의 모델은 1568 토큰, Claude Opus 4.7 및 이후 모델은 4784).

대부분의 사진과 스크린샷의 경우 가장자리 제한이 크기 조정을 유발합니다. 세로 방향 문서의 경우 일반적으로 비주얼 토큰 제한이 먼저 유발되며, 이를 간과하는 것이 좌표 불일치의 가장 흔한 원인입니다. 예를 들어, 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 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)

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

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



미리 크기 조정할 수 없는 경우 좌표 재조정

미리 크기 조정할 수 없는 경우(예: 수정할 수 없는 업스트림 시스템에서 이미지가 제공되는 경우), 업로드 전 이미지 크기 조정의 resized_size를 사용하여 Claude가 본 크기를 복구한 다음, Claude가 반환하는 좌표를 정규화된 좌표로 매핑하거나 원본 이미지로 다시 매핑하세요. 이 방법은 업로드한 이미지의 픽셀 크기를 알아야 하므로 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)


# 원본 이미지의 픽셀 공간에서 좌표를 표현하려면
# 상대 좌표에 원본 크기를 곱하세요:
# (rel_x * original_width, rel_y * original_height)

패딩은 하단 및 오른쪽 가장자리에만 적용되므로 원점이 이동하지 않으며 축별 선형 재조정으로 충분합니다.



프롬프트 예제

Claude와의 텍스트 기반 상호작용에 효과적인 많은 프롬프팅 기법을 이미지 기반 프롬프트에도 적용할 수 있습니다.

이 예제들은 이미지를 포함하는 모범 사례 프롬프트 구조를 보여줍니다.



프롬프트 예제 소개

다음 예제는 다양한 프로그래밍 언어와 접근 방식을 사용하여 Claude의 비전 기능을 사용하는 방법을 보여줍니다. 세 가지 방법으로 Claude에 이미지를 제공할 수 있습니다:

1. image 콘텐츠 블록에 base64 인코딩된 이미지로
2. 온라인에 호스팅된 이미지에 대한 URL 참조로
3. Files API 사용(한 번 업로드하고 여러 번 사용)

base64 예제 프롬프트는 다음 변수를 사용합니다:

import base64
import httpx

# 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")

# URL 기반 이미지의 경우, 요청에서 URL을 직접 사용할 수 있습니다

다음은 base64 인코딩된 이미지와 URL 참조를 사용하여 Messages API 요청에 이미지를 포함하는 방법의 예입니다:



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)



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)



Files API 이미지 예제

반복적으로 사용할 이미지나 인코딩 오버헤드를 피하고 싶은 경우 Files API를 사용하세요. 이미지를 한 번 업로드한 다음, base64 데이터를 다시 전송하는 대신 후속 메시지에서 반환된 file_id를 참조하세요.

client = anthropic.Anthropic()

# 이미지 파일 업로드
with open("image.jpg", "rb") as f:
    file_upload = client.beta.files.upload(file=("image.jpg", f, "image/jpeg"))

# 업로드한 파일을 메시지에서 사용
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)

더 많은 예제 코드와 매개변수 세부 정보는 Messages API 예제를 참조하세요.



제한 사항

Claude의 이미지 이해 기능은 최첨단이지만, 알아두어야 할 몇 가지 제한 사항이 있습니다:

• 사람 식별: Claude는 이미지에서 사람의 이름을 식별하는 데 사용할 수 없으며 이를 거부합니다.
• 정확도: Claude는 저품질, 회전된, 또는 200 픽셀 미만의 매우 작은 이미지를 해석할 때 환각을 일으키거나 실수를 할 수 있습니다.
• 공간 추론: Claude의 좌표 및 위치 출력은 근사치입니다. 좌표 및 바운딩 박스 작업의 지침을 따르고 의존하기 전에 출력을 확인하세요.
• 개수 세기: Claude는 이미지의 객체 수를 대략적으로 셀 수 있지만, 특히 작은 객체가 많은 경우 항상 정확하지 않을 수 있습니다.
• AI 생성 이미지: Claude는 이미지가 AI로 생성되었는지 알지 못하며 질문을 받으면 틀릴 수 있습니다. 가짜 또는 합성 이미지를 감지하는 데 의존하지 마세요.
• 부적절한 콘텐츠: Claude는 사용 제한 정책을 위반하는 부적절하거나 노골적인 이미지를 처리하지 않습니다.
• 의료 애플리케이션: Claude는 일반적인 의료 이미지를 분석할 수 있지만, CT나 MRI와 같은 복잡한 진단 스캔을 해석하도록 설계되지 않았습니다. Claude의 출력은 전문적인 의료 조언이나 진단을 대체하는 것으로 간주되어서는 안 됩니다.

특히 중요한 사용 사례의 경우 Claude의 이미지 해석을 항상 신중하게 검토하고 확인하세요. 사람의 감독 없이 완벽한 정밀도나 민감한 이미지 분석이 필요한 작업에 Claude를 사용하지 마세요.



FAQ



비전에 대해 더 깊이 알아보기

Claude를 사용하여 이미지로 빌드를 시작할 준비가 되셨나요? 다음은 몇 가지 유용한 리소스입니다:

• 멀티모달 쿡북: 이 쿡북에는 이미지 시작하기에 대한 팁과 이미지로 최고 품질의 성능을 보장하기 위한 모범 사례 기법이 있습니다. 차트 해석 및 분석 또는 양식에서 콘텐츠 추출과 같은 작업을 수행하기 위해 이미지로 Claude에게 효과적으로 프롬프트하는 방법을 확인하세요.
• API 레퍼런스: 이미지를 포함하는 API 호출 예제를 포함한 Messages API 문서입니다.

다른 질문이 있으시면 지원 팀에 문의하세요. 개발자 커뮤니티에 참여하여 다른 크리에이터와 연결하고 Anthropic 전문가의 도움을 받을 수도 있습니다.