본문 바로가기
개발&프로그래밍

[Claude] Claude API Python SDK 사용법 완벽 가이드

by 재아군 2026. 2. 9.
반응형

Claude API를 Python에서 사용하는 가장 간단하고 효과적인 방법은

Anthropic Python SDK를 활용하는 것입니다.

 

이 공식 SDK는 타입 안정성, 자동 재시도, 스트리밍 지원 등 개발자 친화적인 기능을 기본으로 제공합니다.

이번 가이드에서는 Python SDK 설치부터 실전 활용까지,

Claude API를 Python으로 완벽하게 다루는 방법을 단계별로 알아보겠습니다.

 

Python SDK 설치

시스템 요구사항

  • Python 버전: 3.9 이상
  • pip: 최신 버전 권장

설치 명령어

pip install anthropic

설치 후 버전 확인:

python -c "import anthropic; print(anthropic.__version__)"

 

가상환경 사용 (권장)

프로젝트별로 독립된 환경을 유지하려면 가상환경을 사용하세요:

# 가상환경 생성
python -m venv claude-env

# 가상환경 활성화 (Mac/Linux)
source claude-env/bin/activate

# 가상환경 활성화 (Windows)
claude-env\Scripts\activate

# SDK 설치
pip install anthropic

 

 

 

API 키 설정

Claude API를 사용하려면 먼저 API 키가 필요합니다.

1단계: API 키 발급

  1. Claude Console에 로그인
  2. Settings → API Keys 이동
  3. "Create Key" 클릭하여 새 API 키 생성

 

2단계: 환경변수 설정

Mac/Linux:

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

영구 설정하려면 ~/.bashrc 또는 ~/.zshrc에 추가:

echo 'export ANTHROPIC_API_KEY="sk-ant-api03-..."' >> ~/.zshrc
source ~/.zshrc

Windows (PowerShell):

$env:ANTHROPIC_API_KEY='sk-ant-api03-...'

영구 설정:

[System.Environment]::SetEnvironmentVariable('ANTHROPIC_API_KEY', 'sk-ant-api03-...', 'User')

 

3단계: .env 파일 사용 (선택사항)

프로젝트 루트에 .env 파일 생성:

ANTHROPIC_API_KEY=sk-ant-api03-...

Python 코드에서 python-dotenv 사용:

pip install python-dotenv
from dotenv import load_dotenv
load_dotenv()  # .env 파일에서 환경변수 로드

import anthropic
client = anthropic.Anthropic()

 

 

기본 API 호출

가장 간단한 Claude API 호출 방법입니다.

첫 번째 API 호출

import anthropic

# 클라이언트 생성 (환경변수에서 API 키 자동 로드)
client = anthropic.Anthropic()

# 메시지 생성
message = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "안녕하세요, Claude!"}
    ]
)

# 응답 출력
print(message.content[0].text)

출력 예시:

안녕하세요! 무엇을 도와드릴까요?

 

API 키를 직접 전달하는 방법

환경변수 대신 코드에서 직접 API 키를 전달할 수도 있습니다 (보안상 권장하지 않음):

client = anthropic.Anthropic(api_key="sk-ant-api03-...")

 

모델별 호출 예제

2편에서 다룬 각 모델을 Python SDK로 호출하는 방법입니다.

Claude Opus 4.6 - 최고 성능

message = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=2048,
    messages=[
        {
            "role": "user",
            "content": "Python으로 피보나치 수열을 생성하는 재귀 함수를 작성하고, 시간 복잡도를 최적화하는 방법을 설명해주세요."
        }
    ]
)

print(message.content[0].text)

 

Claude Sonnet 4.5 - 균형잡힌 선택

message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "FastAPI로 간단한 REST API를 만드는 예제 코드를 보여주세요."
        }
    ]
)

print(message.content[0].text)

 

Claude Haiku 4.5 - 빠르고 경제적

message = client.messages.create(
    model="claude-haiku-4-5",
    max_tokens=512,
    messages=[
        {
            "role": "user",
            "content": "이 에러 메시지를 간단히 요약해주세요: ImportError: No module named 'requests'"
        }
    ]
)

print(message.content[0].text)

 

스트리밍 응답 처리

긴 응답이나 실시간 피드백이 필요한 경우 스트리밍을 사용하세요.

기본 스트리밍

import anthropic

client = anthropic.Anthropic()

# 스트리밍으로 메시지 생성
with client.messages.stream(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "AI의 미래에 대해 500자 정도로 설명해주세요."}
    ]
) as stream:
    # 텍스트가 생성되는 대로 실시간 출력
    for text in stream.text_stream:
        print(text, end="", flush=True)

 

출력 예시:

인공지능의 미래는...
(텍스트가 실시간으로 하나씩 출력됨)

 

전체 메시지 받기 (이벤트 처리 없이)

스트리밍을 사용하되 이벤트를 직접 처리하지 않고 최종 메시지만 받고 싶을 때:

with client.messages.stream(
    model="claude-opus-4-6",
    max_tokens=128000,  # 큰 max_tokens 값
    messages=[
        {"role": "user", "content": "대규모 데이터 분석 보고서를 작성해주세요."}
    ]
) as stream:
    # 전체 메시지 수신 (타임아웃 방지)
    message = stream.get_final_message()

print(message.content[0].text)

이 방법은 max_tokens가 큰 경우 HTTP 타임아웃을 방지하면서도 이벤트 처리 코드를 작성할 필요가 없습니다.

사용량(Usage) 정보 확인

message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude!"}
    ]
)

print(f"입력 토큰: {message.usage.input_tokens}")
print(f"출력 토큰: {message.usage.output_tokens}")
print(f"총 비용: ${(message.usage.input_tokens * 3 + message.usage.output_tokens * 15) / 1_000_000:.6f}")

출력 예시:

입력 토큰: 15
출력 토큰: 25
총 비용: $0.000420

 

멀티턴 대화 (Multi-turn Conversations)

Claude와 여러 차례 대화를 이어가는 방법입니다.

import anthropic

client = anthropic.Anthropic()

# 대화 히스토리 유지
conversation = [
    {"role": "user", "content": "Python으로 리스트를 정렬하는 방법을 알려주세요."}
]

# 첫 번째 응답
message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=conversation
)

# 대화에 어시스턴트 응답 추가
conversation.append({
    "role": "assistant",
    "content": message.content[0].text
})

print("Claude:", message.content[0].text)

# 후속 질문
conversation.append({
    "role": "user",
    "content": "그럼 내림차순으로 정렬하려면?"
})

# 두 번째 응답
message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=conversation
)

print("Claude:", message.content[0].text)

이렇게 하면 Claude가 이전 대화 내용을 기억하고 문맥에 맞는 답변을 제공합니다.

 

에러 처리

프로덕션 환경에서는 반드시 에러 처리를 구현해야 합니다.

기본 에러 처리

import anthropic
from anthropic import APIError, RateLimitError, APIConnectionError

client = anthropic.Anthropic()

try:
    message = client.messages.create(
        model="claude-opus-4-6",
        max_tokens=1024,
        messages=[
            {"role": "user", "content": "Hello!"}
        ]
    )
    print(message.content[0].text)

except RateLimitError as e:
    print(f"⚠️ Rate limit 초과: {e}")
    print("잠시 후 다시 시도하세요.")

except APIConnectionError as e:
    print(f"🌐 네트워크 연결 오류: {e}")
    print("인터넷 연결을 확인하세요.")

except APIError as e:
    print(f"❌ API 오류 발생:")
    print(f"  - 타입: {e.type}")
    print(f"  - 메시지: {e.message}")
    print(f"  - Request ID: {e.request_id}")

주요 에러 타입

HTTP 코드 에러 타입 설명 대응 방법
400 invalid_request_error 잘못된 요청 형식 요청 파라미터 확인
401 authentication_error API 키 인증 실패 API 키 재확인
403 permission_error 권한 없음 계정 권한 확인
404 not_found_error 리소스를 찾을 수 없음 모델 ID 확인
429 rate_limit_error Rate limit 초과 요청 속도 조절
500 api_error 서버 내부 오류 재시도
529 overloaded_error API 과부하 지수 백오프로 재시도

 

자동 재시도 (Exponential Backoff)

import time
import anthropic
from anthropic import APIError, RateLimitError

client = anthropic.Anthropic()

def create_message_with_retry(messages, max_retries=3):
    """지수 백오프로 재시도하는 메시지 생성 함수"""
    for attempt in range(max_retries):
        try:
            message = client.messages.create(
                model="claude-sonnet-4-5",
                max_tokens=1024,
                messages=messages
            )
            return message

        except (RateLimitError, APIError) as e:
            if attempt == max_retries - 1:
                raise  # 마지막 시도에서도 실패하면 예외 발생

            # 지수 백오프: 2^attempt 초 대기
            wait_time = 2 ** attempt
            print(f"⏳ 오류 발생. {wait_time}초 후 재시도... (시도 {attempt + 1}/{max_retries})")
            time.sleep(wait_time)

# 사용 예시
try:
    message = create_message_with_retry([
        {"role": "user", "content": "Hello, Claude!"}
    ])
    print(message.content[0].text)
except Exception as e:
    print(f"❌ 최종 실패: {e}")

Request ID 추적

에러 발생 시 Request ID를 기록하면 Anthropic 지원팀과 소통할 때 유용합니다:

message = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)

# Request ID 출력 (디버깅 및 지원 요청 시 유용)
print(f"Request ID: {message._request_id}")

 

실전 활용 예제

예제 1: 챗봇 구현

import anthropic

def simple_chatbot():
    client = anthropic.Anthropic()
    conversation = []

    print("🤖 Claude 챗봇입니다. 대화를 시작하세요! (종료: 'quit')")

    while True:
        user_input = input("\n👤 You: ")

        if user_input.lower() in ['quit', 'exit', '종료']:
            print("👋 대화를 종료합니다.")
            break

        conversation.append({"role": "user", "content": user_input})

        try:
            message = client.messages.create(
                model="claude-sonnet-4-5",
                max_tokens=2048,
                messages=conversation
            )

            assistant_message = message.content[0].text
            conversation.append({"role": "assistant", "content": assistant_message})

            print(f"\n🤖 Claude: {assistant_message}")

        except Exception as e:
            print(f"❌ 오류 발생: {e}")

# 실행
simple_chatbot()

 

예제 2: 텍스트 요약기

import anthropic

def summarize_text(text, model="claude-haiku-4-5"):
    """텍스트를 간단히 요약하는 함수"""
    client = anthropic.Anthropic()

    message = client.messages.create(
        model=model,
        max_tokens=512,
        messages=[
            {
                "role": "user",
                "content": f"다음 텍스트를 3-5문장으로 요약해주세요:\n\n{text}"
            }
        ]
    )

    return message.content[0].text

# 사용 예시
long_text = """
인공지능(AI)은 컴퓨터 과학의 한 분야로, 기계가 인간의 지능을 모방하거나
학습할 수 있도록 하는 기술입니다. 최근 몇 년간 딥러닝과 신경망의 발전으로
AI는 이미지 인식, 자연어 처리, 음성 인식 등 다양한 분야에서 놀라운
성과를 거두고 있습니다...
"""

summary = summarize_text(long_text)
print(f"📝 요약:\n{summary}")

 

베스트 프랙티스

1. 환경변수로 API 키 관리

# ✅ 좋은 예: 환경변수 사용
client = anthropic.Anthropic()  # ANTHROPIC_API_KEY 자동 로드

# ❌ 나쁜 예: 코드에 하드코딩
client = anthropic.Anthropic(api_key="sk-ant-...")  # 절대 금지!

2. 적절한 max_tokens 설정

# 짧은 응답 (요약, 분류)
max_tokens=512

# 일반 대화
max_tokens=1024

# 긴 콘텐츠 생성 (에세이, 보고서)
max_tokens=4096

# 매우 긴 콘텐츠 (10,000자 이상)
max_tokens=16000  # 스트리밍 사용 권장

3. 모델 선택 전략

# 프로토타입/테스트 → Haiku (빠르고 저렴)
model = "claude-haiku-4-5"

# 프로덕션 일반 → Sonnet (균형)
model = "claude-sonnet-4-5"

# 고난이도 작업 → Opus (최고 성능)
model = "claude-opus-4-6"

4. 대화 히스토리 관리

# 대화가 길어지면 토큰 비용이 증가하므로 적절히 제한
MAX_HISTORY_LENGTH = 10

if len(conversation) > MAX_HISTORY_LENGTH:
    # 오래된 메시지 제거 (시스템 프롬프트 제외)
    conversation = conversation[:1] + conversation[-(MAX_HISTORY_LENGTH-1):]

5. 타임아웃 설정

# 긴 작업에 대한 타임아웃 설정
client = anthropic.Anthropic(timeout=60.0)  # 60초

# 또는 요청별 타임아웃
message = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
    timeout=30.0
)

 

자주 묻는 질문 (FAQ)

Q1. Anthropic Python SDK는 비동기(async)를 지원하나요?

A: 네! Python SDK는 동기(sync)와 비동기(async) 모두 지원합니다.

import asyncio
import anthropic

async def async_example():
    client = anthropic.AsyncAnthropic()

    message = await client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hello"}]
    )

    print(message.content[0].text)

# 실행
asyncio.run(async_example())

비동기는 여러 API 호출을 동시에 처리할 때 유용합니다.

 

Q2. 응답에서 토큰 사용량을 어떻게 확인하나요?

A: 모든 응답 객체에 usage 속성이 포함되어 있습니다.

message = client.messages.create(...)

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

# Sonnet 4.5 기준 비용 계산
input_cost = message.usage.input_tokens * 3 / 1_000_000
output_cost = message.usage.output_tokens * 15 / 1_000_000
total_cost = input_cost + output_cost

print(f"예상 비용: ${total_cost:.6f}")

 

Q3. 스트리밍과 일반 호출 중 어떤 걸 선택해야 하나요?

A: 다음 기준으로 선택하세요:

상황 추천 방법
짧은 응답 (<1000토큰) 일반 호출 (messages.create())
실시간 피드백 필요 스트리밍 (messages.stream())
긴 응답 (>10,000토큰) 스트리밍 (타임아웃 방지)
사용자 경험 중시 스트리밍 (체감 속도 향상)

 

Q4. Rate limit을 초과하면 어떻게 되나요?

A: RateLimitError (HTTP 429)가 발생합니다. 다음과 같이 처리하세요:

from anthropic import RateLimitError
import time

try:
    message = client.messages.create(...)
except RateLimitError as e:
    # 헤더에서 재시도 대기 시간 확인
    retry_after = int(e.response.headers.get('retry-after', 60))
    print(f"{retry_after}초 후 재시도...")
    time.sleep(retry_after)

Rate limit 정보는 Console에서 확인할 수 있습니다.

 

Q5. 시스템 프롬프트는 어떻게 사용하나요?

A: system 파라미터를 사용하여 Claude의 행동을 지시할 수 있습니다.

message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system="당신은 Python 전문가입니다. 코드는 항상 주석과 함께 제공하세요.",
    messages=[
        {"role": "user", "content": "리스트 컴프리헨션 예제를 보여주세요."}
    ]
)

시스템 프롬프트는 한 번만 전송되므로 토큰 효율적입니다.

 

Q6. 이미지를 입력으로 사용할 수 있나요?

A: 네! Claude는 이미지 입력을 지원합니다 (Vision).

import base64

# 이미지 파일을 base64로 인코딩
with open("image.jpg", "rb") as image_file:
    image_data = base64.standard_b64encode(image_file.read()).decode("utf-8")

message = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/jpeg",
                        "data": image_data,
                    },
                },
                {
                    "type": "text",
                    "text": "이 이미지를 설명해주세요."
                }
            ],
        }
    ],
)

 

결론 - Python으로 Claude API 마스터하기

Anthropic Python SDK를 사용하면 몇 줄의 코드만으로 강력한 AI 기능을 애플리케이션에 통합할 수 있습니다.

핵심 요약:

  • ✅ pip install anthropic로 간단 설치
  • ✅ 환경변수로 API 키 안전하게 관리
  • ✅ messages.create() / messages.stream() 두 가지 방식
  • ✅ 에러 처리와 재시도 로직 필수
  • ✅ 모델 선택으로 성능과 비용 최적화

다음 편에서는 "Claude API 요금제 & 비용 절감 팁 (프롬프트 캐싱 활용법)"을 다룰 예정입니다.

프롬프트 캐싱으로 비용을 90% 절감하는 방법을 배워보세요!

📌 관련 글:

🔗 참고 자료:

Sources:

반응형
저작자표시 비영리 변경금지 (새창열림)

'개발&프로그래밍' 카테고리의 다른 글

[Claude] Claude API Tool Use (Function Calling) 구현하기  (0) 2026.02.10
[Claude] Claude API 요금제 & 비용 최적화 전략 (프롬프트 캐싱 활용법)  (0) 2026.02.10
[Claude] Claude API 모델 비교 - Opus vs Sonnet vs Haiku 선택 가이드  (1) 2026.02.09
[Claude] Claude API 시작하기 - API 키 발급부터 첫 호출까지 완벽 가이드 (2026)  (0) 2026.02.09
[AI] 2025년 12월 제미나이 3 vs GPT-5.2, 나에게 맞는 AI는? 완벽 비교  (1) 2025.12.15

관련글

댓글

티스토리툴바