비전 (Vision)
비전 (Vision)
출처: Anthropic 공식 문서 — Vision 원문(영문)을 한국어로 번역·재해석한 문서예요. 기술 용어는 원문 표기를 보존했어요.
Claude의 비전(vision) 능력은 이미지를 이해하고 분석할 수 있게 해줘서, 멀티모달 상호작용의 흥미로운 가능성을 열어요.
이 가이드에서는 이미지를 Claude에 보내는 방법, 적용되는 한도와 비용, 그리고 좌표 기반 워크플로를 위한 가이드라인을 찾을 수 있는 곳을 설명할게요.
Claude에 이미지 보내기
Claude의 비전 능력은 이런 곳에서 활용할 수 있어요.
- claude.ai: 파일을 올리듯 이미지를 업로드하거나, 이미지를 채팅 창에 직접 끌어다 놓으면 돼요.
- Claude Console의 Playground: 모든 User 메시지 블록에 이미지를 직접 추가할 수 있어요.
- API 요청: 아래 예시를 참고하면 돼요.
API에서는 이미지를 세 가지 소스 유형 중 하나로 이미지 콘텐츠 블록으로 제공해요.
- 요청 본문에 포함된 base64로 인코딩된 이미지
- 온라인에 호스팅된 이미지의 URL 참조
- Files API가 반환하는
file_id(한 번 업로드하고 여러 번 참조)
참고: Amazon Bedrock과 Google Cloud에서는 현재 base64로 인코딩된 소스만 사용할 수 있어요.
텍스트 프롬프트에서 긴 문서를 쿼리보다 앞에 두면 결과가 좋아지는 것처럼, Claude도 이미지가 텍스트보다 앞에 올 때 가장 잘 동작해요. 이미지 뒤에 텍스트가 오거나 텍스트 사이에 끼어도 잘 동작하지만, 가능하다면 이미지-다음-텍스트 구조를 선호하는 게 좋아요.
base64 인코딩 이미지 예시
image1_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"
image1_media_type = "image/png"
client = anthropic.Anthropic()
message = client.messages.create(
model="claude-opus-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",
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를 사용하면 돼요. 이미지를 한 번 업로드하고, 이후 메시지에서는 반환된 file_id를 참조하면 base64 데이터를 다시 보낼 필요가 없어요.
참고: 멀티턴 대화와 에이전틱 워크플로에서는 각 요청이 전체 대화 기록을 다시 보내요. 이미지가 base64로 인코딩되어 있으면 대화가 길어질수록 매 턴마다 이미지 전체 바이트가 페이로드에 포함되어 요청 크기와 지연 시간이 크게 늘어날 수 있어요. 이미지를 Files API에 업로드하고
file_id로 참조하면 대화 기록에 이미지가 얼마나 쌓여도 요청 페이로드를 작게 유지할 수 있어요.
client = anthropic.Anthropic()
# Upload the image file
with open("vision-example.jpg", "rb") as f:
file_upload = client.files.upload(file=("vision-example.jpg", f, "image/jpeg"))
# Use the uploaded file in a message
message = client.messages.create(
model="claude-opus-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",
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 토큰 컨텍스트 윈도우 모델): 요청당 100개
- API (그 외 모든 모델): 요청당 600개
이미지당 최대 크기는 8000x8000 px예요.
단일 API 요청에 20개를 넘는 이미지가 있으면, 그 요청의 모든 이미지에 더 엄격한 이미지당 크기 한도가 적용돼요. 요청의 모든 이미지 블록이 이 기준에 포함되는데, 이전 대화 턴에서 다시 보내는 이미지와 tool_result 콘텐츠에 중첩된 이미지(예: computer use 도구에 반환되는 스크린샷)도 포함돼요. Amazon Bedrock과 Google Cloud에서는 PDF 같은 문서 블록도 이 기준에 포함돼요. 기준을 넘는 이미지는 invalid_request_error로 거부되는데, 이 오류 메시지는 "many-image requests"를 언급하고 현재 한도를 픽셀로 알려줘요. 모든 플랫폼에서 한도 아래로 유지하려면 각 이미지를 한 변이 2000px를 넘지 않도록 리사이즈하거나, 요청의 이미지·문서 블록을 20개 이하로 유지하면 돼요.
이미지당 최대 크기는 이렇게 돼요.
- Claude API 직접 사용: 10 MB (base64 인코딩)
- Amazon Bedrock과 Google Cloud: 5 MB (base64 인코딩)
- claude.ai: 10 MB
참고: API가 요청당 최대 600개 이미지를 지원해도, 요청 크기 한도(표준 엔드포인트는 32 MB, Amazon Bedrock과 Google Cloud 같은 파트너 운영 플랫폼에서는 더 낮음)에 먼저 도달할 수 있어요. 이미지가 많으면 Files API로 업로드하고
file_id로 참조해 요청 페이로드를 작게 유지하는 걸 고려해보세요.
Files API를 사용해도 이미지가 많고 큰 요청은 600개 이미지 수에 도달하기 전에 실패할 수 있어요. 업로드 전에 이미지 크기나 파일 크기를 줄이세요(예: 다운샘플링). 자세한 내용은 아래 "해상도와 토큰 비용"을 참고해요.
지원 형식
Claude는 JPEG, PNG, GIF, WebP 이미지(image/jpeg, image/png, image/gif, image/webp)를 지원해요. 애니메이션은 지원하지 않고, 첫 프레임만 사용해요.
해상도와 토큰 비용
Claude는 이미지를 픽셀이 아니라 패치(patch) 단위로 보요. 각 패치는 이미지의 28×28 픽셀 블록이고, 이를 비주얼 토큰(visual token) 이라고 불러요. 따라서 이미지의 비용은 ⌈width / 28⌉ × ⌈height / 28⌉ 비주얼 토큰이에요.
각 모델은 최대 네이티브 이미지 해상도를 가지는데, 긴 변(장축) 한도와 비주얼 토큰 한도로 표현돼요. 두 한도 중 하나라도 넘는 이미지는 처리 전에 다운스케일돼요(정확한 규칙은 "Claude가 이미지를 리사이즈하고 패딩하는 방법" 참고). 예외는 computer use와 browser use 도구셋에 반환하는 스크린샷·줌 이미지인데, API는 모델 한도를 넘는 tool_result 이미지를 다운스케일하지 않고 검증 오류로 거부해요. 그래서 그런 이미지는 애플리케이션에서 반환 전에 리사이즈해야 해요. 다른 초과 크기 이미지도 다운스케일 대신 오류로 거부되게 하려면 이미지 블록의 transformations 필드를 설정하면 돼요.
| 해상도 티어 | 모델 | 최대 긴 변 | 최대 비주얼 토큰 |
|---|---|---|---|
| 고해상도 (High-resolution) | Claude 4.7 이상 모델 | 2576 px | 4784 |
| 표준 (Standard) | 그 외 모든 모델 | 1568 px | 1568 |
고해상도 지원은 해당 모델에서는 자동이며, beta 헤더나 클라이언트 측 옵트인이 필요 없어요.
아래 표는 각 티어에서 여러 이미지 크기의 다운사이즈 해상도와 비주얼 토큰 비용을 보여줘요.
| 이미지 크기 | 표준 티어: 다운사이즈 | 표준 티어: 토큰 | 고해상도 티어: 다운사이즈 | 고해상도 티어: 토큰 |
|---|---|---|---|---|
| 200x200 px (0.04 메가픽셀) | 리사이즈 안 함 | 64 | 리사이즈 안 함 | 64 |
| 1000x1000 px (1 메가픽셀) | 리사이즈 안 함 | 1296 | 리사이즈 안 함 | 1296 |
| 1092x1092 px (1.19 메가픽셀) | 리사이즈 안 함 | 1521 | 리사이즈 안 함 | 1521 |
| 1920x1080 px (2.07 메가픽셀) | 1456x819 px | 1560 | 리사이즈 안 함 | 2691 |
| 2000x1500 px (3 메가픽셀) | 1269x952 px | 1564 | 리사이즈 안 함 | 3888 |
| 3840x2160 px (8.29 메가픽셀) | 1456x819 px | 1560 | 2576x1449 px | 4784 |
이미지가 다운사이즈될 때 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예요.
고해상도 이미지는 같은 이미지의 표준 티어보다 최대 약 3배 많은 비주얼 토큰을 쓸 수 있어요. computer use, 스크린샷 이해, 문서가 빽빽한 작업에서 고해상도의 추가 정밀도가 필요하지 않다면, 토큰 비용을 통제하기 위해 보내기 전에 다운샘플링하세요. 지연 시간을 줄이고 좌표 기반 워크플로를 단순화하려면 업로드 전에 이미지를 리사이즈하는 걸 선호해요.
이미지 품질 가이드라인
Claude에 이미지를 제공할 때 좋은 결과를 얻으려면 다음을 기억하세요.
- 이미지 선명도: 이미지가 선명하고 너무 흐리거나 픽셀화되지 않도록 해요.
- 텍스트: 이미지에 중요한 텍스트가 있으면 읽을 수 있게 하고 너무 작지 않게 해요. 텍스트를 키우려고 주요 시각적 맥락을 잘라내는 건 피하세요.
- 리사이징: 이미지가 너무 크면 리사이즈될 수 있음을 고려하세요(위 "해상도와 토큰 비용" 참고). 예를 들어 리사이즈로 텍스트가 덜 읽히게 될 수 있어요. 이미지를 사전 리사이즈하거나 크롭하거나 둘 다 하는 걸 고려해보세요. 초과 크기 이미지를 리사이즈 대신 오류로 거부되게 하려면(좌표 워크플로에서 중요), 이미지 블록을
"oversized_image": "error"로 표시하세요. - 이미지 압축: 보내기 전에 JPEG나 WebP(로스 모드) 같은 손실(lossy) 형식으로 이미지를 압축하면 요청 크기를 줄여 지연 시간을 낮출 수 있어요. 다만 이는 모델 성능에 해로운 아티팩트를 만들 수 있는데, 특히 압축 패스를 여러 번 적용하면 그렇죠. 예를 들어 과한 JPEG 압축은 텍스트를 읽기 어렵게 만들 수 있어요. API로 실제 전송되는 이미지를 검사해 압축 설정이 작업에 적합한지 확인하세요.
좌표와 경계 상자
경계 상자(bounding box), 점, 픽셀 좌표에 대해서는 Coordinates and bounding boxes 문서를 참고하세요. Claude는 리사이즈 후 보는 이미지 기준의 절대 픽셀 좌표를 반환해요. 그 가이드는 Claude가 이미지를 어떻게 리사이즈하고 패딩하는지, 원본 이미지에 좌표가 맞도록 사전 리사이즈하거나 다시 스케일하는 방법을 다뤄요.
한계 (Limitations)
Claude의 이미지 이해 능력은 최첨단이지만, 알아둬야 할 한계가 몇 가지 있어요.
- 사람 식별: Claude는 이미지에서 사람을 특정 이름으로 지목할 수 없고 그렇게 하기를 거부해요.
- 정확성: Claude는 200픽셀 미만의 저품질, 회전, 또는 아주 작은 이미지를 해석할 때 환각을 일으키거나 실수할 수 있어요.
- 공간 추론: Claude의 좌표와 위치 출력은 근사치예요. "Coordinates and bounding boxes"의 가이드를 따르고, 의존하기 전에 출력을 검증하세요.
- 세기 (Counting): Claude는 이미지 내 객체의 대략적인 개수를 줄 수 있지만, 특히 작은 객체가 많을 때는 항상 정확하지 않을 수 있어요.
- AI 생성 이미지: Claude는 이미지가 AI 생성인지 판별할 수 없고, 물어보면 틀릴 수 있어요. 가짜나 합성 이미지를 감지하는 데 의존하지 마세요.
- 부적절한 콘텐츠: Claude는 Acceptable Use Policy를 위반하는 부적절하거나 노골적인 이미지를 처리하지 않아요.
- 헬스케어 응용: Claude는 일반 의료 이미지를 분석할 수 있지만, CT나 MRI 같은 복잡한 진단 스캔을 해석하도록 설계되진 않았어요. Claude의 출력은 전문 의료 조언이나 진단의 대체물로 간주해서는 안 돼요.
항상 Claude의 이미지 해석을 신중히 검토하고 검증하세요. 특히 고위험 사용 사례에서는 더 그렇죠. 완벽한 정밀도가 필요하거나 민감한 이미지 분석이 필요한 작업에 사람의 감독 없이 Claude를 사용하지 마세요.
FAQ
- Claude는 어떤 이미지 파일 형식을 지원하나요?
- Claude가 이미지 URL을 읽을 수 있나요?
- 업로드할 수 있는 이미지 파일 크기 제한이 있나요?
- 한 요청에 몇 개의 이미지를 포함할 수 있나요?
- Claude가 이미지 메타데이터를 읽나요?
- 업로드한 이미지를 삭제할 수 있나요?
- 이미지 업로드의 데이터 프라이버시 세부 사항은 어디서 찾을 수 있나요?
- Claude의 이미지 해석이 틀린 것 같으면 어떻게 하나요?
- Claude가 이미지를 생성하거나 편집할 수 있나요?
각 질문의 답은 원문 문서의 해당 FAQ 항목을 참고해요.
다음 단계
- 멀티모달 쿡북: 차트 해석, 폼에서 콘텐츠 추출 같은 작업을 위한 팁과 모범 사례를 확인할 수 있어요.
- API 참조: 이미지가 포함된 API 호출 예시를 포함한 Messages API 문서를 보세요.