이 콘텐츠는 Anthropic이 공식적으로 제공하는 학습 코스인 「Claude with the Anthropic API」(Anthropic Courses)를 기반으로 하고 있습니다. 코스의 내용을 일본어로 해설하면서, 실제 코드와 함께 학습할 수 있도록 구성했습니다.

Claude API를 사용하여 AI 앱을 구축하는 방법을 핸즈온(Hands-on)으로 배우는 시리즈의 제2탄입니다.

시리즈 전체의 개요·대상 독자·Claude API를 배우는 이점 등에 대해서는 기초 편을 참조해 주세요.

• Claude API를 사용한 AI 프로덕트 개발 - 기초 편의 내용을 이해하고 있을 것

• 확장 사고 모드 (Extended Thinking Mode) — Claude가 추론 과정을 공개하게 하여 복잡한 문제에 대한 대응력을 높임

• 이미지 지원 (Image Support) — 이미지를 직접 전송하여 내용을 분석하게 함

• PDF 지원 (PDF Support) — PDF 내용 이해 및 인용 생성 구현

• 프롬프트 캐싱 (Prompt Caching) — 반복해서 전송하는 컨텍스트를 캐싱하여 비용과 레이턴시(Latency)를 절감

• 파일 API와 코드 실행 (File API & Code Execution) — 파일을 사전에 업로드하고, Claude에게 코드를 작성하게 하여 분석 및 시각화까지 실행

아래의 노트북에는 이 기사와 동일한 내용이 기재되어 있어, 즉시 Python 코드를 실행할 수 있습니다.

직접 코드를 실행해 보는 것만으로도 동작을 이해하기 쉬우므로, 꼭 활용해 보세요!

여기서 지정하고 있는 모델이나 파라미터 등은 향후 변경될 가능성이 있습니다.

통상적인 Claude API 호출에서는 Claude가 즉시 최종 답변을 생성하여 반환합니다.

하지만 「어려운 수학 문제를 풀기」, 「여러 선택지 중 최적해를 선택하기」, 「코드의 버그 원인을 논리적으로 추적하기」와 같은 복잡한 태스크에서는, 갑자기 답을 내놓는 것보다 한 번 차분히 생각한 뒤에 답변하는 것이 정밀도가 높아집니다.

확장 사고는 Claude가 최종 답변을 생성하기 전에 내부적인 추론 프로세스(Reasoning Process)를 실행하는 기능입니다.

이 추론 내용은 thinking 블록으로서 응답(Response)에 포함되어, 「왜 그런 답변이 되었는지」를 확인할 수 있습니다.

다음과 같은 태스크에 적합하지만, 비용 증가, 응답 속도 저하 등의 단점이 있습니다.

• 수학·논리 퍼즐의 해법
• 여러 단계가 필요한 코드 설계
• 데이터 분석·패턴 인식

확장 사고를 활성화하면, 통상적인 TextBlock에 더해 ThinkingBlock이 응답의 content에 포함됩니다.

# 통상적인 응답
content = [
TextBlock(type="text", text="답은 42입니다.")
...

확장 사고의 활성화는 thinking 파라미터를 설정하는 것만으로 가능합니다.

response = client.messages.create(
model=model,
max_tokens=16000, # thinking 분량을 포함한 충분한 값이 필요
...

구현 시 주의점은 다음과 같습니다.

• max_tokens는 budget_tokens보다 커야 합니다. 사고 토큰(Thinking Token) + 최종 답변 토큰의 합계가 들어갈 수 있는 값을 설정해 주세요.
• 멀티턴 대화(Multi-turn Conversation)에서 대화 이력으로 되돌릴 때는, thinking 블록을 포함하여 response.content를 그대로 전달합니다. messages.append({"role": "assistant", "content": response.content})
• Anthropic 측에서 블록의 정당성을 검증하고 있으므로, 서명(Signature)은 반드시 그대로 유지해 주세요. ThinkingBlock의 signature를 개변하면 에러가 발생합니다.

그럼 실제 코드를 실행해 봅시다!

from rich import print as rprint
from dotenv import load_dotenv
load_dotenv()
...

출력 결과:

채팅을 시작합니다. 종료하려면 'quit'을 입력하세요.
[사용자] 1-100 사이의 소수를 알려주세요.
[사고 프로세스]
...

ThinkingBlock(사고 프로세스)과 TextBlock(최종 답변) 두 가지가 반환되고 있음을 알 수 있습니다. Claude가 답을 내기 전에 내부에서 소수를 하나씩 확인하고, 그 추론 내용이 thinking에 담겨 있습니다.

필드에 포함되어 있습니다.

Claude는 이미지를 직접 수신하여 내용을 이해하고 분석할 수 있습니다.

텍스트 전용 대화와 동일한 API로 동작하며, 이미지 블록(image block)과 텍스트 블록(text block)을 조합하여 사용자 메시지에 포함합니다.

이미지를 전달하는 방법에는 주로 두 가지가 있습니다. 용도에 따라 선택하세요.

base64로 전송하기

로컬 파일을 보낼 때의 기본 형태입니다. 본 장의 샘플에서는 이 방식을 사용합니다.

import base64
with open("image.png", "rb") as f:
    image_bytes = base64.standard_b64encode(f.read()).decode("utf-8")
...

URL로 전송하기

이미지를 공개 URL로 가져올 수 있다면, base64 인코딩(encoding)이 필요 없어 가장 간결하게 작성할 수 있습니다.

{
"type": "image",
"source": {
...

이미지 크기가 클수록 토큰(token) 소비가 늘어나 비용이 상승하므로, 불필요하게 고해상도인 이미지는 보내지 않도록 주의하세요.

제한 사항에 대한 최신의 정확한 값은 공식 정보를 참조하시기 바랍니다.

그럼 실제 코드를 실행해 봅시다!

아래 이미지에 대해 설명을 요청하겠습니다.

import base64
from dotenv import load_dotenv
load_dotenv()
...

출력 결과:

이 이미지는 Claude API를 기반으로, Claude Agent SDK를 통해 Claude Code와 Claude Cowork가 동작하며, 또한 Claude.ai가 직접 API에 접속하는 Claude의 기술 스택 구조를 나타낸 도표입니다.

base64로 인코딩한 이미지를 메시지에 포함하는 것만으로, Claude가 이미지 내용을 읽고 일본어로 설명해 주었습니다.

Claude는 PDF 파일을 직접 수신하여 내용을 이해하고 분석할 수 있습니다.

단순한 텍스트 추출에 그치지 않고, 임베디드 이미지, 차트, 테이블, 헤더 등의 문서 구조도 함께 이해할 수 있는 것이 특징입니다.

이미지 지원과 매우 유사한 구조로 구현할 수 있으며, **type: "document"**를 지정하기만 하면 됩니다.

PDF 처리 코드는 이미지 처리와 거의 동일합니다. 바뀌는 점은 세 가지뿐입니다.

또한, 이미지와는 제한 내용이 다릅니다. 주요 제한 사항은 다음과 같습니다.

PDF는 페이지 수나 크기가 클수록 토큰 소비가 늘어나 비용이 상승하므로, 불필요하게 큰 파일은 보내지 않도록 주의하세요.

제한 사항에 대한 최신의 정확한 값은 공식 정보를 참조하시기 바랍니다.

그럼 실제 코드를 실행해 봅시다!

아래의 Anthropic 공식 문서를 다운로드한 것을 이용합니다.

import base64
from dotenv import load_dotenv
load_dotenv()
...

출력 결과:

Anthropic은 AI 해석 가능성(interpretability), 정렬 과학(alignment science), 사회적 영향이라는 세 가지 연구 팀을 통해, 현재 및 미래의 AI 모델의 안전성, 신뢰성, 제어 가능성을 확보하기 위한 최첨단 연구를 수행하고 있는 AI 안전 연구 기업입니다.

이미지와 거의 동일한 코드에서, type을 "document"로, media_type을 "application/pdf"로 바꾸는 것만으로 PDF 내용을 요약할 수 있었습니다.

Claude가 반환한 정보가 어느 문서의 어느 부분에서 왔는지를 명시하는 기능입니다.

"답변은 돌아왔지만, 정말 그 PDF에 적혀 있는 내용인가?"라는 의문을 해소하고, 투명성 있는 답변을 구현합니다.

인용(Citations)을 활성화하면, content 내의 TextBlock 내 citations 필드에 인용 정보가 포함됩니다.

# 인용이 포함된 응답
content = [
TextBlock(
...

인용 활성화는 문서 블록(Document block)에 title과 citations 필드를 추가하는 것만으로 가능합니다.

PDF와 일반 텍스트(Plain text) 모두 동일하게 사용할 수 있습니다.

PDF에서 이용하기

{
"type": "document",
"source": {
...

PDF의 경우, 인용 위치는 start_page_number / end_page_number (페이지 번호)로 표시됩니다.

일반 텍스트에서 이용하기

인용은 PDF뿐만 아니라 일반 텍스트에도 사용할 수 있습니다.

{
"type": "document",
"source": {
...

일반 텍스트의 경우, 페이지 번호 대신 start_char_index / end_char_index (문자 위치)로 인용 위치가 표시됩니다.

그럼 실제 코드를 실행해 봅시다!

from rich import print as rprint
import base64
from dotenv import load_dotenv
...

출력 결과:

---------------
TextBlock(
citations=[
...

TextBlock 안에 인용 원본 정보가 포함되어 있는 것을 확인할 수 있습니다!

참고로, 인용을 활성화하면 답변은 문장(Sentence) 단위로 여러 개의 TextBlock으로 분할되며, 문장과 문장 사이에는 줄바꿈만 포함된 TextBlock (text='\n\n')이 삽입될 수 있습니다.

프롬프트 캐시(Prompt Cache)를 이해하기 위해, 먼저 Claude가 요청을 받은 후 답변을 반환하기까지 무엇을 하는지 파악해 보겠습니다.

Claude API에 요청을 보내면, Claude는 내부적으로 대략 다음과 같은 처리를 수행합니다.

• 토큰화 (Tokenization) — 텍스트를 토큰(모델이 다루는 최소 단위)으로 분할합니다.
• 임베딩 (Embedding / Vectorization) — 각 토큰을 수치 벡터로 변환합니다.
• 컨텍스트 부여 (Contextualization) — 주변 토큰과의 관계를 고려하여 각 토큰에 의미적인 문맥을 부여합니다.
• 출력 생성 (Generation) — 지금까지의 결과를 바탕으로 답변 텍스트를 1토큰씩 생성합니다.

핵심은, 동일한 입력을 전달하면 1~3의 결과는 매번 동일하다는 점입니다. 동일한 입력에 대해 1~3을 반복해서 실행하는 것은 토큰 소비 증가와 응답 속도 저하만 초래할 뿐, 얻을 수 있는 이득이 없습니다.

여기서 등장하는 것이 바로 프롬프트 캐시 (Prompt Cache) 입니다.

프롬프트 캐시를 사용하면 "입력"과 "1~3의 처리 결과" 쌍을 캐시에 저장해 둘 수 있습니다.

다음 요청 시 동일한 입력이 들어오면, 1~3을 재실행하지 않고 캐시에서 처리 결과를 가져와 바로 4(출력 생성) 단계로 진행할 수 있습니다.

이를 통해 다음과 같은 두 가지 이점을 얻을 수 있습니다.

• 토큰 비용 절감 (캐시 히트(Cache hit) 부분의 토큰 단가가 일반 입력의 0.1배까지 낮아집니다.)
• 응답 속도 향상 (1~3 단계를 건너뛸 수 있기 때문입니다.)

단, 캐시를 작성할 때는 토큰 단가가 일반 입력의 1.25배가 됩니다. 동일한 입력이 재사용될 가능성이 낮다면 오히려 비용이 증가할 수 있다는 점에 주의해야 합니다.

위의 배율은 기사 작성 시점 기준입니다. 최신 모델에서는 변경되었을 가능성이 있으므로, 최신 정보는 Anthropic 공식 문서를 참조하십시오.

프롬프트 캐시 구현

구현은 간단합니다. content를 배열로 만든 후, 캐시하고 싶은 블록의 끝에 "cache_control": {"type": "ephemeral"}를 추가하기만 하면 됩니다. cache_control 이전의 입력이 해당 입력과 1~3의 처리 결과 쌍으로서 캐시에 저장됩니다.

message = client.messages.create(
model=model,
max_tokens=1000,
...

Claude API는 요청에 포함된 각 블록을 다음 순서로 연결하여, 하나의 입력으로서 1~3의 처리를 수행합니다.

도구 정의 (Tool Definition) → 시스템 프롬프트 (System Prompt) → messages (user 1 → assistant 1 → user 2 → ...)

여기서 대화형 애플리케이션의 동작을 생각해 봅시다. 도구 정의와 시스템 프롬프트는 매 턴 거의 동일한 내용이며, 대화 이력의 전반부 역시 2번째 턴부터는 이전까지의 내용과 동일합니다. 그럼에도 불구하고 Claude는 매 요청마다 모든 입력에 대해 1~3의 처리를 실행하고 있습니다.

그렇기 때문에 대화가 진행될수록 소비되는 토큰은 쌓여가며, 비용과 응답 시간(Latency)이 계속해서 증가하게 됩니다.

이러한 낭비를 해결하려면 사용자 메시지의 끝에 "cache_control": {"type": "ephemeral"}를 추가하면 됩니다. 그러면 cache_control 이전의 입력(도구 정의, 시스템 프롬프트, 그동안의 메시지)에 대해 1~3의 처리 결과가 한꺼번에 캐시에 저장되며, 다음 요청부터는 해당 범위를 다시 계산할 필요가 없어집니다.

위의 그림은 대화가 진행됨에 따라 캐시가 어떻게 쌓여가는지를 보여줍니다.

이와 같이 매 턴 "직전까지의 캐시 히트(Hit) + 이번 턴의 차분(Delta)만 신규 쓰기"를 반복함으로써, 대화가 길어지더라도 입력 부분의 비용을 계속해서 억제할 수 있습니다.

단, 프롬프트 캐시(Prompt Cache)는 캐시 대상의 총 토큰 수가 최소 토큰 수에 도달하기 전까지는 쓰기 작업도 수행되지 않습니다. 최소 토큰 수는 모델마다 다릅니다.

• 1024 tokens: Claude Opus, Sonnet (3.5/3.7/4 계열)
• 2048 tokens: Claude Haiku 3.5

대화 초반처럼 입력이 짧은 동안에는 cache_control을 붙여도 캐시가 유효하게 작동하지 않는다는 점에 주의하십시오.

Anthropic API에서는 1회 요청당 cache_control을 설정할 수 있는 브레이크포인트(Breakpoint)가 최대 4개까지라는 제약이 있으므로, 긴 대화를 운용할 경우에는 최근 2개로 압축하도록 합니다. 최근 2개를 남겨두는 이유는 "이전 턴에 부여한 브레이크포인트에 의한 캐시 읽기"와 "이번 턴에 신규로 부여하는 브레이크포인트에 의한 캐시 쓰기"라는 두 가지 작업이 필요하기 때문입니다.

그럼 실제 코드를 실행해 봅시다!

from rich import print as rprint
from dotenv import load_dotenv
load_dotenv()
...

출력 결과:

채팅을 시작합니다. 종료하려면 'quit'을 입력하세요.
[사용자]
양자 컴퓨터에 대해 한 문장으로 설명해 주세요
...

양자 컴퓨터에 대해 3회의 Claude API 호출을 수행했습니다. 각 턴의 usage를 살펴보겠습니다.

각 턴에 공통적으로 input_tokens=3이 나타나는데, 이는 캐시 쓰기나 읽기 어디에도 해당하지 않는 아주 작은 비캐시(Non-cache) 입력분입니다. Claude 측에서 자동으로 부여되는 토큰 등이 계상될 수 있으며, 전체 비용에 미치는 영향은 거의 없으므로, 본 기사에서는 이를 "Claude의 사양에 따른 소량의 고정값"으로 간주하고 이후에는 다루지 않겠습니다.

1회차

• cache_creation_input_tokens=1223 — 긴 시스템 프롬프트와 1번째 사용자 메시지가 한꺼번에 캐시에 기록되었습니다. 이번에는 시스템 프롬프트만으로도 Opus / Sonnet의 최소 토큰 수(1024)를 초과했기 때문에 첫 회부터 쓰기가 발생했습니다.
• cache_read_input_tokens=0 — 아직 캐시가 존재하지 않으므로 읽기는 발생하지 않았습니다.

2회차

• cache_read_input_tokens=1223 — 1회차에 기록한 "시스템 프롬프트 + user1"을 그대로 읽어옵니다. 캐시 히트(Cache Hit)에 성공했습니다.
• cache_creation_input_tokens=101

— 이번 턴의 차분(assistant1 + user2)이 새롭게 캐시(Cache)에 추가되었습니다.

3회차

cache_read_input_tokens=1324

— 2회차까지 쌓인 캐시(1223 + 101 = 1324 토큰)를 그대로 읽어오고 있습니다. -
cache_creation_input_tokens=110

— 이번 턴의 차분(assistant2 + user3)이 새롭게 캐시에 추가되었습니다.

3회차에서는 그때까지의 대화 이력 1324 토큰 분량의 재계산을 모두 스킵할 수 있었습니다.

대화가 길어질수록 캐시가 쌓이며, **매 턴 「직전까지의 캐시 히트(Cache Hit) + 이번 턴의 차분만 신규 쓰기」**를 반복하는 형태로 비용과 응답 속도를 계속해서 개선할 수 있습니다.

cache_control은 사용자 메시지뿐만 아니라, 도구 정의(Tool Definition)나 시스템 프롬프트(System Prompt)의 끝부분에도 설정할 수 있습니다.

도구 정의에 cache_control 설정하기

여러 개의 도구를 정의하는 경우, 마지막 도구 정의의 끝에 cache_control을 붙이면 그때까지의 모든 도구 정의가 캐시 대상이 됩니다.

response = client.messages.create(
model=model,
max_tokens=1000,
...

시스템 프롬프트에 cache_control 설정하기

시스템 프롬프트를 배열(Array) 형식으로 전달하고, 마지막 블록에 cache_control을 붙입니다. 긴 시스템 프롬프트를 매번 전송해야 하는 케이스에서 특히 효과적입니다.

response = client.messages.create(
model=model,
max_tokens=1000,
...

지금까지는 이미지나 PDF를 base64로 인코딩하여 메시지에 직접 포함해 왔습니다.

여기서부터 소개할 **파일 API (File API)**와 **코드 실행 도구 (Code Execution Tool)**는 각각 단독으로도 편리하지만, 조합함으로써 「Claude에게 데이터를 전달하고, 코드를 작성하여 분석하게 한 뒤, 결과 그래프를 받는」 강력한 워크플로우를 구축할 수 있게 됩니다.

파일 API는 메시지와는 별도의 API 호출로 사전에 파일을 업로드해 두고, 이후의 메시지에서는 파일 ID(file_id)로 참조하는 방식입니다.

기존의 base64 방식과 비교하면 다음과 같은 차이가 있습니다.

동일한 파일을 여러 메시지에서 참조하고 싶을 때나, 큰 파일을 다룰 때 특히 적합합니다.

파일 API 이용 단계는 3단계입니다.

• 파일을 (이미지, PDF, 텍스트 등) client.beta.files.upload()로 업로드한다
• 응답으로 돌아오는 FileMetadata에서 file_id를 추출한다
• 이후의 메시지에서는 블록의 source에 type: "file"과 file_id를 지정하여 참조한다

# 1. 업로드
uploaded = client.beta.files.upload(file=open("image.png", "rb"))
file_id = uploaded.id # 예: "file_011CRd..."
...

그럼 실제 코드를 실행해 보겠습니다!

from dotenv import load_dotenv
load_dotenv()
from anthropic import Anthropic
...

출력 결과:

file_011CbQREoYwMaJ7PF5UwXVuc

업로드하여 얻은 file_id를 사용하여, 이미지에 대해 Claude에게 질문해 보겠습니다.

메시지 내의 블록은 type: "file"

• file_id

만으로 충분하기 때문에, base64 인코딩 (base64 encoding) 코드가 필요하지 않게 됩니다.

message = client.beta.messages.create(
model=model,
max_tokens=1000,
...

출력 결과:

# 이미지 설명
이 이미지는 Claude가 사용자 메시지를 받은 후, ① 토큰화 (tokenize), ② 임베딩 (embedding, 벡터화), ③ 컨텍스트 부여 (context attachment), ④ 출력 텍스트 생성이라는 4단계 입력 처리를 거쳐 어시스턴트 메시지(요약 결과)를 반환하기까지의 처리 흐름을 나타낸 도식입니다.

base64 인코딩을 작성하지 않고 file_id를 전달하는 것만으로, 이미 업로드된 이미지를 Claude가 분석하도록 할 수 있었습니다.

기초 편에서 배웠던 "도구 사용 (tool use)"에서는 도구 구현을 이쪽(사용자 측)에서 직접 준비해야 했습니다.

반면, 코드 실행 도구 (code execution tool) 는 Anthropic 측 서버에 구현이 준비되어 있는 내장 도구 (server tool) 로서, 도구 스키마 (tool schema) 를 tools에 지정하기만 하면 Claude가 필요에 따라 Python 코드를 작성하고, Anthropic 측 서버 위에서 실행해 줍니다.

tools=[{"type": "code_execution_20250825", "name": "code_execution"}]

그럼 실제 코드를 실행해 보겠습니다!

from rich import print as rprint
from dotenv import load_dotenv
load_dotenv()
...

출력 결과:

[텍스트]
TextBlock(citations=None, text='1부터 10까지의 정수의 평균과 표준 편차를 계산합니다.', type='text')
[실행 명령]
...

출력 결과의 ServerToolUseBlock (실행 명령)에 Python 코드가 있으며, 그것을 Bash를 통해 실행하고 있는 것을 확인할 수 있습니다. 이처럼 코드 실행 도구를 tools에 추가하는 것만으로, Claude는 스스로 Python 코드를 작성하여 서버 측에서 실행하고, 그 결과를 바탕으로 답변을 구성해 줍니다.

앞으로는 파일 API와 코드 실행 도구를 조합하여, 다음과 같은 워크플로우 (workflow)를 실행해 보겠습니다!

• 파일 API로 CSV 등의 데이터 파일을 업로드한다.
• 메시지에 container_upload 블록 (file_id 지정)을 포함하여 분석 요청을 보낸다.
• Claude가 pandas 등을 사용하여 Python 코드를 작성하고, 컨테이너 내부에서 실행한다.
• Claude가 실행 결과 (집계값, 통계값 등)를 읽어 들여 답변 텍스트로 정리한다.
• 응답의 text 블록에서 Claude의 분석 결과와 고찰을 추출한다.

이미지/PDF용 image / document 블록과 달리, 코드 실행 컨테이너로 전달할 파일은 container_upload 블록을 사용합니다.

{"type": "container_upload", "file_id": file_metadata.id}

이 블록이 메시지에 포함되어 있으면, 지정한 파일이 컨테이너 내의 파일 시스템에 배치되어 Claude가 Python에서 읽을 수 있게 됩니다.

그럼 실제 코드를 실행해 보겠습니다!

샘플로 일별 매출 데이터인 CSV (sample_sales.csv)를 사용합니다.

컬럼은 date / product / quantity / unit_price 4개이며, Claude가 Pandas를 사용하여 집계하도록 하여 매출 순위, 평균 단가, 총 매출 등의 분석 결과를 텍스트로 받겠습니다.

date,product,quantity,unit_price
2026-05-01,커피 원두,10,1800
2026-05-01,녹차,5,1200
...

from dotenv import load_dotenv
load_dotenv()
from anthropic import Anthropic
...

출력 결과:

[업로드 완료] file_011CbSkw42Any26o9wPJanEU
[텍스트]
CSV 파일을 읽어 지정된 분석을 실행하겠습니다.
...

CSV를 업로드하여 분석을 요청하는 것만으로, Claude가 스스로 Pandas 코드를 작성하여 집계하고, 순위·평균 단가·총매출을 정리한 뒤 일본어 고찰(考察)까지 답변해 주었습니다.

확장 기능 편에서는 Claude API를 더욱 실용적으로 활용하기 위한 5가지 기능을 배웠습니다.