Claude API Python 튜토리얼 2026 — 설치부터 스트리밍까지

Python에서 Claude API를 사용하려면 pip install anthropic 한 줄이면 됩니다. Anthropic Python SDK는 동기/비동기 모두 지원하며, 스트리밍 응답, 도구 사용, 프롬프트 캐싱까지 포함합니다. 이 가이드는 입문부터 프로덕션 패턴까지 커버합니다.

설치 및 기본 설정

pip install anthropic
# 또는
pip install anthropic>=0.25.0

API 키 설정:

export ANTHROPIC_API_KEY="sk-ant-api03-..."

첫 번째 호출

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Python으로 피보나치 수열 함수를 작성해줘"}
    ]
)

print(message.content[0].text)

출력:

def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

모델 선택

# Haiku — 빠름, 저비용 (반복 작업)
model = "claude-haiku-3-5"

# Sonnet — 균형 (대부분의 작업)
model = "claude-sonnet-4-5"

# Opus — 최고 성능 (복잡한 추론)
model = "claude-opus-4-5"

2026년 기준 권장:

• 일반 Q&A, 요약 → claude-haiku-3-5
• 코드 생성, 분석 → claude-sonnet-4-5
• 복잡한 계획, 판단 → claude-opus-4-5

시스템 프롬프트

message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system="당신은 시니어 Python 개발자입니다. 코드는 항상 타입 힌트를 포함하고 PEP 8을 준수합니다.",
    messages=[
        {"role": "user", "content": "사용자 인증 미들웨어를 작성해줘"}
    ]
)

멀티턴 대화

from anthropic import Anthropic

client = Anthropic()
conversation_history = []

def chat(user_message: str) -> str:
    conversation_history.append({
        "role": "user",
        "content": user_message
    })
    
    response = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=1024,
        messages=conversation_history
    )
    
    assistant_message = response.content[0].text
    conversation_history.append({
        "role": "assistant",
        "content": assistant_message
    })
    
    return assistant_message

# 사용 예시
print(chat("FastAPI로 REST API 만드는 방법 알려줘"))
print(chat("방금 말한 것에서 인증 미들웨어 부분만 더 자세히 설명해줘"))

스트리밍 응답

긴 응답을 실시간으로 받아서 출력할 때:

with client.messages.stream(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "머신러닝 입문 가이드를 작성해줘"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

FastAPI + 스트리밍

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import anthropic

app = FastAPI()
client = anthropic.Anthropic()

@app.post("/chat/stream")
async def chat_stream(prompt: str):
    def generate():
        with client.messages.stream(
            model="claude-sonnet-4-5",
            max_tokens=1024,
            messages=[{"role": "user", "content": prompt}]
        ) as stream:
            for text in stream.text_stream:
                yield f"data: {text}\n\n"
        yield "data: [DONE]\n\n"
    
    return StreamingResponse(generate(), media_type="text/event-stream")

비동기 (AsyncIO)

import asyncio
import anthropic

async def main():
    client = anthropic.AsyncAnthropic()
    
    message = await client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "비동기 Python 패턴 설명해줘"}]
    )
    
    print(message.content[0].text)

asyncio.run(main())

병렬 요청 (비용 최적화)

import asyncio
import anthropic

async def analyze_batch(items: list[str]) -> list[str]:
    client = anthropic.AsyncAnthropic()
    
    tasks = [
        client.messages.create(
            model="claude-haiku-3-5",  # 배치는 Haiku로 비용 절약
            max_tokens=512,
            messages=[{"role": "user", "content": f"다음을 한 줄 요약해줘: {item}"}]
        )
        for item in items
    ]
    
    responses = await asyncio.gather(*tasks)
    return [r.content[0].text for r in responses]

# 100개 항목 병렬 처리
results = asyncio.run(analyze_batch(items[:100]))

프롬프트 캐싱 (비용 60% 절감)

시스템 프롬프트가 길거나 반복 호출이 많을 때:

import anthropic

client = anthropic.Anthropic()

# 긴 문서를 캐시
document = open("large_codebase.txt").read()

message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": f"다음 코드베이스를 분석하는 전문가입니다:\n\n{document}",
            "cache_control": {"type": "ephemeral"}  # 캐시 활성화
        }
    ],
    messages=[{"role": "user", "content": "보안 취약점을 찾아줘"}]
)

# 두 번째 호출부터 캐시 히트 → 입력 토큰 비용 90% 절감
message2 = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": f"다음 코드베이스를 분석하는 전문가입니다:\n\n{document}",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[{"role": "user", "content": "성능 병목 지점을 찾아줘"}]
)

# 캐시 히트 확인
print(message2.usage.cache_read_input_tokens)  # > 0이면 캐시 히트

에러 처리

import anthropic
from anthropic import APIConnectionError, RateLimitError, APIStatusError

client = anthropic.Anthropic()

def safe_call(prompt: str, max_retries: int = 3) -> str | None:
    for attempt in range(max_retries):
        try:
            message = client.messages.create(
                model="claude-sonnet-4-5",
                max_tokens=1024,
                messages=[{"role": "user", "content": prompt}]
            )
            return message.content[0].text
            
        except RateLimitError:
            wait = 2 ** attempt  # 지수 백오프
            print(f"Rate limit. {wait}초 후 재시도...")
            time.sleep(wait)
            
        except APIConnectionError:
            print(f"연결 오류. 시도 {attempt + 1}/{max_retries}")
            
        except APIStatusError as e:
            print(f"API 오류 {e.status_code}: {e.message}")
            if e.status_code >= 500:
                time.sleep(1)
            else:
                raise  # 4xx는 재시도 불필요
    
    return None

토큰 사용량 추적

message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "간단한 설명"}]
)

print(f"입력 토큰: {message.usage.input_tokens}")
print(f"출력 토큰: {message.usage.output_tokens}")

# 비용 계산 (Sonnet 기준)
input_cost = message.usage.input_tokens / 1_000_000 * 3.0   # $3/1M
output_cost = message.usage.output_tokens / 1_000_000 * 15.0  # $15/1M
total = input_cost + output_cost
print(f"이 호출 비용: ${total:.6f}")

실전 패턴: 코드 리뷰 봇

import anthropic
import subprocess

client = anthropic.Anthropic()

def review_pr_diff(diff: str) -> str:
    return client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=2048,
        system="""시니어 개발자로서 코드 리뷰를 수행합니다.
다음 관점에서 검토하세요:
1. 보안 취약점
2. 성능 이슈
3. 코드 스멜
4. 테스트 누락
각 이슈는 심각도(Critical/Warning/Info)와 함께 구체적 수정 방법을 제시하세요.""",
        messages=[{
            "role": "user",
            "content": f"다음 diff를 리뷰해줘:\n\n```diff\n{diff}\n```"
        }]
    ).content[0].text

# Git diff 가져와서 리뷰
diff = subprocess.run(
    ["git", "diff", "main..HEAD"],
    capture_output=True, text=True
).stdout

review = review_pr_diff(diff)
print(review)

Frequently Asked Questions

Python 버전은 몇 이상이 필요한가요?

Python 3.8 이상. 비동기 기능은 Python 3.10 이상을 권장합니다.

anthropic 패키지와 openai 패키지를 같이 사용할 수 있나요?

네, 독립적으로 동작합니다. 두 패키지를 함께 설치해도 충돌 없습니다.

API 키를 코드에 하드코딩하면 안 되나요?

절대 안 됩니다. 환경변수(os.environ["ANTHROPIC_API_KEY"]) 또는 .env 파일 + python-dotenv 패키지를 사용하세요. .env는 반드시 .gitignore에 추가해야 합니다.

스트리밍과 일반 호출 중 뭐가 더 빠른가요?

첫 토큰까지의 시간(TTFT)은 동일합니다. 스트리밍은 전체 응답 완료를 기다리지 않고 UI에 바로 표시할 수 있어 사용자 경험이 좋습니다.

배치 처리로 비용을 절약할 수 있나요?

네, Anthropic Batch API를 사용하면 같은 작업을 50% 할인된 가격에 처리할 수 있습니다. 실시간성이 필요 없는 분석, 분류 작업에 적합합니다.

관련 가이드: Claude API 비용 계산 한국어 · Claude API FastAPI 한국어 · Claude 프롬프트 캐싱 한국어

P2 Claude Agent SDK Cookbook — Python으로 만드는 프로덕션 에이전트 15개 레시피. Pydantic 스키마, 재시도 미들웨어, 비용 가드레일 포함. 지금 확인 →