비전

이 가이드에서는 Claude에 이미지를 보내는 방법, 적용되는 제한 및 비용, 그리고 좌표 기반 워크플로에 대한 안내를 어디에서 찾을 수 있는지 설명합니다.

Claude에 이미지 보내기

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

• claude.ai. 파일을 업로드하듯이 이미지를 업로드하거나, 이미지를 채팅 창에 직접 드래그 앤 드롭하세요.
• Claude Console의 Playground. 모든 User 메시지 블록에 이미지를 직접 추가하세요.
• API 요청. 다음 예시를 참조하세요.

API에서는 세 가지 소스 유형 중 하나를 사용하여 이미지를 image 콘텐츠 블록으로 Claude에 제공합니다:

1. 요청 본문에 포함된 base64 인코딩 이미지
2. 온라인에 호스팅된 이미지에 대한 URL 참조
3. Files API가 반환한 file_id(한 번 업로드하고 여러 번 참조)

Base64 인코딩 이미지 예시

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

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-5-5",
    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-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://platform.claude.com/docs/images/vision-example.jpg",
                    },
                },
                {"type": "text", "text": "Describe this image."},
            ],
        }
    ],
)
print(message)

Files API 이미지 예시

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

client = anthropic.Anthropic()

# 이미지 파일을 업로드합니다
with open("vision-example.jpg", "rb") as f:
    file_upload = client.files.upload(file=("vision-example.jpg", f, "image/jpeg"))

# 업로드한 파일을 메시지에서 사용합니다
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    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는 이를 함께 분석합니다. 이는 이미지를 비교하거나, 차이점에 대해 질문하거나, 문서의 페이지와 같은 시퀀스를 다룰 때 유용합니다. 여러 이미지를 보낼 때는 각 이미지 앞에 짧은 텍스트 레이블(Image 1:, Image 2: 등)을 붙여 프롬프트와 후속 턴에서 이름으로 참조할 수 있도록 하세요.

image1_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"
image2_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGNgYPgPAAEDAQAIicLsAAAAAElFTkSuQmCC"

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Image 1:"},
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image1_data,
                    },
                },
                {"type": "text", "text": "Image 2:"},
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image2_data,
                    },
                },
                {"type": "text", "text": "How are these images different?"},
            ],
        }
    ],
)
print(message)

멀티턴 대화에서는 이후 user 턴에 같은 방식으로 새 이미지를 추가하세요. Claude는 이전 턴의 모든 이미지에 접근할 수 있으므로, "이것들이 처음 두 개와 비슷한가요?"와 같은 후속 질문은 새 턴의 콘텐츠에 이전 이미지를 다시 포함하지 않아도 작동합니다.

이미지 제한 및 비용

요청 제한

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

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

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

단일 API 요청에 20개를 초과하는 이미지가 포함된 경우, 해당 요청의 모든 이미지에 더 엄격한 이미지당 크기 제한이 적용됩니다. 요청의 모든 image 블록이 이 임계값에 포함되며, 여기에는 다시 전송하는 이전 대화 턴의 이미지와 tool_result 콘텐츠 내에 중첩된 이미지(예: computer use 도구에 반환된 스크린샷)도 포함됩니다. Amazon Bedrock 및 Google Cloud에서는 PDF와 같은 문서 블록도 이 임계값에 포함됩니다. 더 엄격한 제한을 초과하는 이미지는 invalid_request_error로 거부되며, 해당 오류 메시지는 "many-image requests"를 언급하고 현재 제한을 픽셀 단위로 명시합니다. 모든 플랫폼에서 제한을 넘지 않으려면, 각 이미지의 어느 쪽 치수도 2000 px를 초과하지 않도록 크기를 조정하거나, 요청의 이미지 및 문서 블록을 20개 이하로 유지하세요.

이미지당 최대 용량은 다음과 같습니다:

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

지원 형식

Claude는 JPEG, PNG, GIF, WebP 이미지(image/jpeg, image/png, image/gif, image/webp)를 지원합니다. 애니메이션은 지원되지 않으며 첫 번째 프레임만 사용됩니다.

해상도 및 토큰 비용

Claude는 이미지를 픽셀이 아닌 패치 단위로 봅니다. 각 패치는 이미지의 28×28 픽셀 블록이며, 이를 비주얼 토큰이라고 합니다. 따라서 이미지 하나의 비용은 ⌈width / 28⌉ × ⌈height / 28⌉ 비주얼 토큰입니다.

각 모델에는 긴 변 제한과 비주얼 토큰 제한으로 표현되는 최대 네이티브 이미지 해상도가 있습니다. 어느 한 제한이라도 초과하는 이미지는 처리 전에 축소됩니다. 정확한 규칙은 Claude가 이미지 크기를 조정하고 패딩하는 방법을 참조하세요. 예외는 computer use 및 browser use 도구 세트에 반환하는 스크린샷과 확대 이미지입니다. API는 모델의 제한을 초과하는 tool_result 이미지를 축소하는 대신 유효성 검사 오류로 거부하므로, 해당 이미지는 반환하기 전에 애플리케이션에서 크기를 조정하세요. 그 외의 크기 초과 이미지를 축소하는 대신 오류로 거부되도록 하려면 이미지 블록의 transformations 필드를 설정하세요.

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

다음 표는 각 등급에서 여러 이미지 크기에 대한 축소 해상도와 비주얼 토큰 비용을 보여줍니다:

이미지가 축소될 때 Claude는 종횡비를 유지하면서 해당 등급의 제한에 맞는 가장 큰 크기로 조정합니다. 이로써 토큰 비용에 상한이 생깁니다. 정확한 규칙과 참조 구현은 Claude가 이미지 크기를 조정하고 패딩하는 방법을 참조하세요.

비용을 추정하려면 토큰 수에 사용 중인 모델의 토큰당 가격을 곱하세요. 예를 들어, Claude Haiku 4.5의 입력 토큰 백만 개당 $1 USD(표준 등급) 기준으로 1000×1000 이미지는 이미지 천 장당 약 $1.30 USD입니다. Claude Opus 5의 백만 개당 $5 USD(고해상도 등급) 기준으로는 같은 이미지가 천 장당 약 $6.48 USD이고, 4K 이미지는 천 장당 약 $23.92 USD입니다.

고해상도 이미지는 표준 등급 모델에서의 동일한 이미지보다 최대 약 세 배 더 많은 비주얼 토큰을 사용할 수 있습니다. computer use, 스크린샷 이해, 밀도 높은 문서에 고해상도가 제공하는 추가적인 정밀도가 필요하지 않다면, 토큰 비용을 제어하기 위해 전송 전에 이미지를 다운샘플링하세요. latency를 최소화하고 좌표 기반 워크플로를 단순화하려면 업로드하기 전에 이미지 크기를 조정하는 것을 선호하세요.

이미지 품질 안내

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

• 이미지 선명도: 이미지가 선명하고 너무 흐리거나 픽셀화되지 않았는지 확인하세요.
• 텍스트: 이미지에 중요한 텍스트가 포함되어 있다면 읽을 수 있고 너무 작지 않은지 확인하세요. 단지 텍스트를 확대하기 위해 핵심 시각적 맥락을 잘라내지 마세요.
• 크기 조정: 이미지가 너무 크면 크기가 조정될 수 있다는 점을 고려하세요(해상도 및 토큰 비용 참조). 예를 들어 이로 인해 텍스트의 가독성이 떨어질 수 있습니다. 이미지를 미리 크기 조정하거나, 자르거나, 둘 다 하는 것을 고려하세요. 크기 초과 이미지를 크기 조정하는 대신 오류로 거부되도록 하려면(좌표 워크플로에서 중요), 이미지 블록에 "oversized_image": "error"를 표시하세요.
• 이미지 압축: JPEG 또는 WebP(손실 모드)와 같은 손실 형식을 사용하여 전송 전에 이미지를 압축하면 요청 크기를 줄여 latency를 줄일 수 있습니다. 그러나 이는 특히 여러 번의 압축 과정이 적용될 때 모델 성능에 해로운 아티팩트를 유발할 수 있습니다. 예를 들어, 과도한 JPEG 압축은 텍스트를 읽기 어렵게 만들 수 있습니다. API로 전송되는 실제 이미지를 검사하여 압축 설정이 작업에 적합한지 확인하세요.

좌표 및 바운딩 박스

바운딩 박스, 점, 픽셀 좌표에 대해서는 좌표 및 바운딩 박스를 참조하세요. Claude는 크기 조정 후 자신이 보는 이미지를 기준으로 절대 픽셀 좌표를 반환합니다. 해당 가이드에서는 Claude가 이미지 크기를 조정하고 패딩하는 방법과, 좌표가 원본 이미지와 일치하도록 미리 크기를 조정하거나 다시 스케일링하는 방법을 다룹니다.

제한 사항

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

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

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

FAQ

다음 단계