Python으로 Claude API 사용 방법: 완전 초보자 가이드 (2026)

Source: Dev.to

Anthropic Python SDK는 Claude를 애플리케이션에 쉽게 통합할 수 있게 해줍니다. 이 가이드에서는 설치, 첫 번째 API 호출, 스트리밍, 다중 턴 대화 및 오류 처리 등을 다루며 10분 이내에 작동하는 챗봇을 만들 수 있도록 안내합니다.

사전 요구 사항

• Python 3.8+
• Anthropic API 키 (console.anthropic.com)
• 기본 Python 지식

---

1단계: SDK 설치

pip install anthropic

필요한 의존성은 이것뿐입니다. SDK에는 클라이언트, 스트리밍 지원, 타입 힌트 등 모든 것이 포함되어 있습니다.

---

단계 2: API 키 설정

키를 환경 변수로 저장하세요 — 소스 파일에 하드코딩하지 마세요:

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

또는 프로젝트 루트에 .env 파일을 생성하세요:

ANTHROPIC_API_KEY=sk-ant-...

python-dotenv 로 로드하세요:

pip install python-dotenv

---

단계 3: 첫 번째 API 호출

main.py 파일을 만들고 다음을 추가합니다:

import anthropic

client = anthropic.Anthropic()  # env에서 ANTHROPIC_API_KEY를 읽음

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explain what an API is in 2 sentences."}
    ]
)

print(message.content[0].text)

실행합니다:

python main.py

Claude로부터 깔끔하고 간결한 응답을 받을 수 있습니다. message.content[0].text에 텍스트 출력이 들어 있습니다.

단계 4: 시스템 프롬프트 추가

시스템 프롬프트는 Claude의 컨텍스트와 성격을 설정합니다 — 사용자 메시지 전에 Claude가 가장 먼저 읽는 내용입니다:

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="You are a senior Python developer. Answer concisely with code examples.",
    messages=[
        {"role": "user", "content": "How do I read a JSON file in Python?"}
    ]
)

print(message.content[0].text)

---

단계 5: 스트리밍 응답

더 나은 사용자 경험을 위해 — 특히 긴 출력의 경우 — 스트리밍을 사용하여 텍스트가 단어 단위로 표시되도록 합니다:

import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Write a Python function to parse CSV files"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

print()  # newline at the end

---

단계 6: 다중 턴 대화

메시지 기록을 추적하여 간단한 챗봇을 구축합니다:

import anthropic

client = anthropic.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-6",
        max_tokens=1024,
        system="You are a helpful AI assistant.",
        messages=conversation_history,
    )

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

    return assistant_message

# Example conversation
print(chat("What is Python?"))
print(chat("What are its main use cases?"))
print(chat("Which one is best for AI development?"))

각 호출은 전체 기록을 전달하므로 Claude가 대화 초기에 말한 내용을 기억합니다.

---

단계 7: 오류 처리

프로덕션 코드에서는 항상 API 호출을 try/except로 감싸세요:

import anthropic

client = anthropic.Anthropic()

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

except anthropic.APIConnectionError as e:
    print(f"Connection error: {e}")
except anthropic.RateLimitError as e:
    print(f"Rate limit hit — slow down: {e}")
except anthropic.APIStatusError as e:
    print(f"API error {e.status_code}: {e.message}")

사용 가능한 모델

사용 사례에 맞는 Claude 모델을 선택하세요:

• claude‑opus‑4‑7 — 가장 강력하며 복잡한 추론 및 분석에 최적
• claude‑sonnet‑4‑6 — 속도와 지능의 최적 균형 (대부분의 앱에 권장)
• claude‑haiku‑4‑5‑20251001 — 가장 빠르고 비용 효율적이며 간단한 작업에 적합

주요 매개변수

messages.create()에서 가장 중요한 매개변수:

message = client.messages.create(
    model="claude-sonnet-4-6",   # 사용할 Claude 모델
    max_tokens=1024,            # 응답의 최대 토큰 수
    temperature=0.7,            # 0 = 결정적, 1 = 창의적
    system="...",               # 시스템 프롬프트 (선택 사항)
    messages=[...]              # 대화 기록
)

💡 팁: 코드 생성 및 사실 기반 작업에는 temperature=0을 사용하세요. 창의적인 글쓰기에는 높은 값(0.7–1.0)을 사용하세요.

전체 예제: 간단한 CLI 챗봇

import anthropic

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

    print("Welcome to the Claude CLI chatbot! Type 'exit' to quit.")
    while True:
        user_input = input("\nYou: ")
        if user_input.lower() in {"exit", "quit"}:
            break

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

        response = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=1024,
            system="You are a helpful AI assistant.",
            messages=conversation,
        )

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

        print(f"\nClaude: {assistant_reply}")

if __name__ == "__main__":
    main()

스크립트를 실행하고 터미널에서 바로 Claude와 대화해 보세요!

def main():
    history = []
    print("Claude Chatbot — type 'quit' to exit\n")

    while True:
        user_input = input("You: ").strip()
        if user_input.lower() in ("quit", "exit"):
            break
        if not user_input:
            continue

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

        with client.messages.stream(
            model="claude-sonnet-4-6",
            max_tokens=2048,
            system="You are a helpful assistant.",
            messages=history
        ) as stream:
            print("Claude: ", end="", flush=True)
            response_text = ""
            for text in stream.text_stream:
                print(text, end="", flush=True)
                response_text += text
            print()

        history.append({"role": "assistant", "content": response_text})


if __name__ == "__main__":
    main()

---

다음은?

기본을 작동시켰으니, 다음에 탐색할 내용은 다음과 같습니다:

• 도구 사용 – Claude가 코드에서 함수와 API를 호출하도록 허용
• 비전 – 이미지를 Claude에 보내 분석
• 프롬프트 캐싱 – 반복 컨텍스트 비용을 절감 (최대 90 % 절감)
• 배치 API – 비동기적으로 수천 개 요청을 처리, 50 % 할인

💡 리소스:

• Anthropic Docs
• Python SDK on GitHub

원본은 kalyna.pro에 게시되었습니다.