Claude는 텍스트뿐 아니라 이미지도 직접 입력으로 받아 분석할 수 있습니다. 이 기능을 공식적으로 '비전(Vision) 기능'이라고 부릅니다. 제품 사진 설명, 문서 스캔 해석, 차트 분석 등 다양한 용도로 활용할 수 있으며, API를 통해 세 가지 방식으로 이미지를 전달할 수 있습니다. 이 글에서는 각 방식이 어떻게 다른지, 언제 어떤 방식을 선택하면 좋은지 순서대로 살펴봅니다.
시작 전 준비물
- Anthropic API 키 — Claude API를 사용하려면 API 키가 필요합니다. 공식 플랫폼(
platform.claude.com)에서 발급받을 수 있습니다. - Python 또는 선호하는 언어 환경 — 이 글의 예시는 Python 기준입니다.
- anthropic Python 패키지 설치 — 터미널에서
pip install anthropic를 실행하면 됩니다.
용어 빠른 풀이
- 비전(Vision) — 이미지를 입력으로 받아 내용을 이해하는 AI 기능. 눈으로 보듯 사진을 분석합니다.
- Base64 — 이미지 파일처럼 이진(binary) 데이터를 텍스트 문자열로 변환하는 인코딩 방식. 이메일에 첨부 파일을 텍스트로 실어 보내는 것과 비슷합니다.
- 멀티모달(Multimodal) — 텍스트·이미지 등 여러 형태의 입력을 함께 처리하는 방식.
- 페이로드(Payload) — API 요청 시 실제로 전송되는 데이터 묶음. 이미지가 포함되면 크기가 커질 수 있습니다.
- file_id — Files API로 파일을 한 번 업로드하면 발급받는 고유 식별자. 이후에는 이 ID만 사용해 같은 파일을 다시 참조합니다.
- 콘텐츠 블록(content block) — API 메시지 안에서 텍스트·이미지 등 각 입력 요소를 담는 단위. 배열 형태로 여러 블록을 함께 전달할 수 있습니다.
이미지 입력의 기본 원칙
공식 문서에 따르면, Claude에 이미지와 텍스트를 함께 보낼 때는 이미지를 텍스트 앞에 배치하는 것이 권장됩니다. 텍스트 뒤나 사이에 이미지를 넣어도 동작하지만, 이미지를 먼저 제시하면 더 나은 결과를 얻을 수 있습니다. 긴 문서를 질문 앞에 배치하는 것과 같은 이치입니다.
또한 Amazon Bedrock·Google Cloud 환경에서는 현재 Base64 인코딩 방식만 사용할 수 있습니다. URL 참조나 Files API 방식은 Anthropic API 직접 호출 시에만 지원됩니다.
방법 1: Base64 인코딩으로 이미지 전달
이미지 파일을 Base64 문자열로 변환해 요청 본문에 직접 포함하는 방식입니다. 별도 서버나 외부 URL 없이도 이미지를 전달할 수 있어, 소량의 이미지를 일회성으로 처리할 때 편리합니다.
import anthropic
import base64
# 이미지 파일을 Base64 문자열로 읽기
with open("my_image.jpg", "rb") as f:
image_data = base64.standard_b64encode(f.read()).decode("utf-8")
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": "image/jpeg", # 실제 파일 형식에 맞게 수정
"data": image_data,
},
},
{
"type": "text",
"text": "이 이미지를 설명해 주세요."
}
],
}
],
)
print(message.content)이렇게 보이면 성공
터미널에 Claude가 이미지를 묘사한 텍스트 응답이 출력됩니다. ContentBlock 객체 안에 type='text'와 실제 설명 문장이 담겨 있으면 정상입니다.
지원 이미지 형식
- JPEG —
image/jpeg - PNG —
image/png - GIF —
image/gif - WebP —
image/webp
media_type 값을 실제 파일 형식에 맞게 지정해야 합니다. 형식이 맞지 않으면 오류가 발생하거나 분석 결과가 올바르지 않을 수 있습니다.
방법 2: URL로 이미지 참조
이미 웹에 공개된 이미지가 있다면, 이미지 주소(URL)를 직접 전달하는 방식이 가장 간단합니다. 이미지를 변환하거나 업로드할 필요가 없습니다.
import anthropic
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": "이 이미지를 설명해 주세요."
}
],
}
],
)
print(message.content)주의사항
- URL은 외부에서 접근 가능한 공개 주소여야 합니다. 로컬 파일 경로나 로그인이 필요한 URL은 사용할 수 없습니다.
- 이미지가 나중에 삭제되거나 주소가 바뀌면 동일한 요청이 실패할 수 있습니다.
방법 3: Files API로 이미지 업로드 후 재사용
같은 이미지를 여러 번 쓰거나, 대화가 여러 턴으로 이어지는 경우에는 Files API 방식이 가장 효율적입니다. 이미지를 한 번만 업로드하고 발급받은 file_id를 이후 요청에서 참조하면 됩니다.
멀티턴(multi-turn) 대화 — 여러 차례 주고받는 대화 — 에서는 매 요청마다 전체 대화 이력을 다시 전송합니다. 이미지가 Base64로 포함되어 있으면 대화가 길어질수록 전송 데이터 크기가 크게 늘어납니다. Files API를 사용하면 이미지 본체 대신 짧은 ID만 전달하므로 페이로드를 가볍게 유지할 수 있습니다.
import anthropic
client = anthropic.Anthropic()
# 1단계: 이미지를 한 번만 업로드
with open("image.jpg", "rb") as f:
file_upload = client.beta.files.upload(
file=("image.jpg", f, "image/jpeg")
)
file_id = file_upload.id # 예: "file_abc123..."
print(f"업로드 완료. file_id: {file_id}")
# 2단계: file_id로 이미지 참조
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_id,
},
},
{
"type": "text",
"text": "이 이미지를 설명해 주세요."
}
],
}
],
)
print(message.content)이렇게 보이면 성공
'업로드 완료. file_id: file_…'로 시작하는 줄이 출력된 뒤, Claude의 이미지 설명이 이어서 출력되면 정상입니다.
이 file_id는 저장해두면 이후 요청에서 이미지를 다시 업로드하지 않고 재사용할 수 있습니다.
자주 막히는 지점 & 해결
-
오류:
invalid_request_error— media_type 불일치
원인:media_type에 지정한 형식과 실제 파일 형식이 다릅니다.
조치: 파일 확장자를 확인하고image/jpeg,image/png,image/gif,image/webp중 맞는 값으로 수정합니다. -
URL 방식에서 이미지를 읽지 못하는 경우
원인: URL이 외부에서 접근 불가한 주소이거나, 로그인·인증이 필요한 경우입니다.
조치: 브라우저 시크릿 창에서 해당 URL을 열어 이미지가 표시되는지 확인합니다. 표시되지 않으면 Base64 또는 Files API 방식을 사용합니다. -
Files API 사용 시
betas파라미터 누락 오류
원인: Files API는 베타 기능으로,betas=["files-api-2025-04-14"]를 반드시 포함해야 합니다.
조치: 위 코드 예시처럼client.beta.messages.create와betas파라미터를 함께 사용합니다. -
Amazon Bedrock·Google Cloud에서 URL 방식이 작동하지 않음
원인: 공식 문서에 따르면 Bedrock·Google Cloud 환경에서는 Base64 방식만 지원됩니다.
조치: 해당 플랫폼에서는 Base64 인코딩 방식을 사용합니다.
세 가지 방식 비교 요약
- Base64 인코딩 — 준비가 간단하고 외부 서버 불필요. 단, 이미지가 크거나 대화가 길면 요청 크기가 커집니다.
- URL 참조 — 이미 공개된 이미지라면 코드가 가장 짧습니다. 비공개 이미지에는 사용할 수 없습니다.
- Files API — 반복 사용이나 긴 대화에 가장 적합합니다. 업로드를 한 번 더 거쳐야 하지만 이후에는 ID만으로 참조합니다.
응용 및 다음 단계
이미지 분석 기능에 익숙해졌다면 다음을 시도해보세요.
- 여러 이미지 동시 전달 — 콘텐츠 배열에 이미지 블록을 여러 개 넣으면 한 번의 요청으로 복수의 이미지를 분석할 수 있습니다.
- 이미지 + 텍스트 문서 혼합 — 이미지 블록과 텍스트 블록을 함께 구성해 복합적인 분석을 요청할 수 있습니다.
- 좌표 및 바운딩 박스 — 공식 문서의 '좌표 및 바운딩 박스(Coordinates and bounding boxes)' 항목에서 이미지 내 특정 위치를 지정하는 고급 활용법을 확인할 수 있습니다.
- PDF 입력 — Claude API는 PDF 파일도 입력으로 지원합니다. Files API와 함께 사용하면 긴 문서를 효율적으로 처리할 수 있습니다.