Claude API 첫 호출을 해 봤다면 다음으로 많이 쓰게 되는 기능이 이미지 입력입니다. 영수증 사진에서 금액을 뽑거나, 대시보드 캡처를 보고 이상한 수치를 찾거나, 오류 화면을 보고 원인을 추정하는 일을 코드로 자동화할 수 있습니다.
이미지를 보내는 두 가지 방법
메시지의 content에 텍스트 블록과 함께 이미지 블록을 넣습니다. 이미지는 base64로 인코딩해 직접 보내거나, 접근 가능한 URL을 지정합니다. 같은 이미지를 여러 요청에서 반복해 쓴다면 Files API로 한 번 올려 두고 참조하는 방법도 있습니다.
파이썬 예제: 영수증에서 항목 뽑기
import base64
import anthropic
client = anthropic.Anthropic()
with open("receipt.jpg", "rb") as f:
data = base64.standard_b64encode(f.read()).decode("utf-8")
response = client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
messages=[{
"role": "user",
"content": [
{"type": "image", "source": {"type": "base64", "media_type": "image/jpeg", "data": data}},
{"type": "text", "text": "이 영수증의 날짜, 상호명, 합계 금액을 JSON으로 알려 줘. 읽을 수 없는 값은 null로."},
],
}],
)
print("".join(b.text for b in response.content if b.type == "text"))
이미지를 텍스트보다 앞에 두는 것이 좋습니다. 무엇을 볼지 먼저 주고, 그다음에 무엇을 할지 묻는 순서입니다. 결과를 프로그램에서 바로 쓸 거라면 구조화 출력으로 JSON 형식을 강제하세요.
업무 활용 예시
| 작업 | 프롬프트 요령 |
|---|---|
| 영수증·청구서 정리 | 필드 목록을 지정하고 "읽을 수 없으면 null" |
| 차트 해석 | "눈금으로 추정한 값은 추정이라고 표시" |
| 오류 화면 분석 | 화면이 나온 상황(어떤 버튼을 눌렀는지)도 함께 |
| 양식 검토 | 필수 항목 목록을 주고 빠진 것만 보고하게 |
이미지 크기와 비용
이미지는 픽셀 크기에 따라 입력 토큰으로 계산됩니다. 4,000픽셀이 넘는 휴대폰 원본 사진을 그대로 보내면 비용만 늘고 정확도는 크게 오르지 않습니다. 긴 변을 1,500픽셀 안팎으로 줄여 보내는 것으로 충분한 경우가 많았습니다. 정확한 크기 제한과 토큰 계산 방식은 공식 비전 문서를 확인하세요.
정확도를 높이는 요령
- 필요한 부분만 자르기: 영수증 전체 사진보다 금액 부분이 잘 보이게 자른 이미지가 정확합니다.
- 기울기 바로잡기: 비스듬히 찍힌 문서는 미리 똑바로 맞추면 숫자 오독이 줄어듭니다.
- "모르면 null": 흐린 글자를 추측해서 채우지 않게 합니다.
- 여러 장은 번호로 구분: "이미지 1은 지난달, 이미지 2는 이번 달 대시보드야"처럼 텍스트로 알려 줍니다.
주의할 점
- 개인정보: 신분증, 카드 번호, 얼굴이 보이는 사진은 보내기 전에 가리거나 제외하세요.
- 검증: 금액·날짜 같은 핵심 값은 샘플을 뽑아 사람이 원본과 대조하는 단계를 둡니다.
- 사람 식별 금지: 사진 속 인물이 누구인지 알아내는 용도로는 쓰지 않습니다.
만들어 보며 느낀 점
비전 기능은 "사람이 눈으로 옮겨 적던 일"을 줄이는 데 효과가 컸습니다. 다만 결과가 너무 그럴듯해서 검증을 건너뛰기 쉽습니다. 저는 자동화를 만들 때 처음 일주일은 결과를 전부 사람이 확인하고, 틀린 유형이 거의 없다는 게 확인된 뒤에 샘플 검증으로 줄이는 방식을 씁니다.
핵심 요약
- 이미지는 base64·URL·Files API로 보내며, 이미지 블록을 텍스트보다 앞에 둡니다.
- 큰 이미지는 줄여서 보내 비용을 아끼고, 필요한 부분만 자르면 정확도가 오릅니다.
- 개인정보는 가리고, 핵심 값은 원본과 대조해 검증하세요.
