Anthropic 클로드 API 파이썬 연동 실습 (무료 크레딧으로 요약봇 완성하기)

작성자:

GPT만 쓰다가 Claude를 처음 연동한 날, 뭔가 달랐다

OpenAI API를 쓰면서 한 가지 불만이 있었다. 긴 문서를 요약시키면 가끔 핵심을 빗나간 답이 나왔다. 그러던 중 팀원이 “Claude가 긴 텍스트 처리는 더 낫다”고 슬쩍 던졌다. 반신반의하며 Anthropic 콘솔을 열었다. 가입만 해도 무료 크레딧이 주어졌고, 파이썬 연동까지 15분도 안 걸렸다.

직접 뉴스 기사 50건을 요약시켜 GPT-4o-mini와 나란히 비교했다. 결과물의 밀도가 달랐다. 이 글은 Claude API 키 발급부터 파이썬 요약봇 완성, 그리고 실무에서 체감한 차이점까지 숨김없이 기록한 실전 가이드다.

1. Claude API 개요와 무료 크레딧 조건

Anthropic의 Claude API는 현재 claude-3-5-haiku, claude-3-5-sonnet, claude-3-7-sonnet 세 가지 주요 모델을 제공한다. 이 중 claude-3-5-haiku가 가장 빠르고 저렴해서 요약봇 같은 반복 작업에 적합하다. 신규 가입 시 Anthropic 콘솔에서 소액의 무료 크레딧을 제공하며, 카드 등록 없이 API 호출 테스트가 가능하다.

OpenAI와 구조가 거의 같아서 기존 GPT 코드를 Claude용으로 바꾸는 데 10분도 안 걸린다. 다른 점은 메시지 구조에서 system 역할을 별도 파라미터로 분리한다는 것인데, 이게 오히려 프롬프트를 더 깔끔하게 정리하게 해준다.

2. 개발 환경 준비 및 API 키 발급

개발 환경

  • Python 버전: 3.11 이상
  • 편집기: VS Code 또는 Cursor AI
  • 핵심 패키지: anthropic, python-dotenv
pip install anthropic python-dotenv

API 키 발급 순서

Anthropic 콘솔(console.anthropic.com)에 구글 계정으로 가입한다. 왼쪽 메뉴 [API Keys] → [Create Key]를 클릭하면 sk-ant-로 시작하는 키가 발급된다. 이 키를 프로젝트 폴더의 .env 파일에 저장한다.

ANTHROPIC_API_KEY=sk-ant-여기에_발급받은_키_입력

절대 깃허브에 올리지 말 것. .gitignore에 .env를 반드시 추가해야 한다. 키가 퍼블릭 레포에 노출되면 Anthropic이 자동으로 키를 비활성화하고 이메일 알림을 보낸다 — 실제로 한 번 겪었다.

3. 파이썬 요약봇 전체 코드 단계별 구축

1단계: 단건 요약 기본 호출 확인

먼저 API가 정상 작동하는지 단건 호출로 확인한다. Claude API는 messages.create() 메서드를 쓰며, system 파라미터에 역할을 지정하는 구조가 GPT와 다른 핵심 포인트다.

import os
import anthropic
from dotenv import load_dotenv

load_dotenv()
client = anthropic.Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))

def summarize(text: str) -> str:
    message = client.messages.create(
        model="claude-3-5-haiku-20241022",
        max_tokens=512,
        system="당신은 전문 편집자입니다. 주어진 텍스트를 핵심만 추려 3문장 이내 한국어로 요약하세요.",
        messages=[
            {"role": "user", "content": text}
        ]
    )
    return message.content[0].text

# 테스트
sample = "인공지능 기술의 빠른 발전으로 자연어 처리 분야에서 혁신이 이어지고 있다. 특히 대규모 언어 모델의 등장으로 번역, 요약, 코드 생성 등 다양한 작업에서 인간 수준의 성능을 보이고 있으며, 기업들은 이를 활용한 서비스를 경쟁적으로 출시 중이다."
print(summarize(sample))

2단계: 다건 배치 요약봇 완성 코드

실무에서는 기사 수십 건을 한 번에 처리해야 한다. API 과호출을 막기 위해 호출 사이에 딜레이를 넣고, 실패 시 재시도하는 로직까지 갖춘 완성형 코드다.

import time
import pandas as pd

articles = [
    "AI 반도체 시장이 2026년 급성장하며 엔비디아의 독주가 이어지고 있다...",
    "오픈소스 LLM 모델들이 GPT-4 수준에 근접하며 기업 도입이 늘고 있다...",
    "국내 스타트업들이 AI 에이전트 분야에서 글로벌 시장에 도전장을 내밀고 있다...",
]

results = []
for i, article in enumerate(articles):
    print(f"[{i+1}/{len(articles)}] 요약 중...")
    try:
        summary = summarize(article)
        results.append({"원문": article[:50] + "...", "요약": summary})
        time.sleep(1.5)  # 분당 호출 제한 대응
    except anthropic.RateLimitError:
        print("  Rate Limit 초과 — 30초 대기 후 재시도")
        time.sleep(30)
        summary = summarize(article)
        results.append({"원문": article[:50] + "...", "요약": summary})

df = pd.DataFrame(results)
df.to_excel("claude_summary_result.xlsx", index=False)
print("완료! claude_summary_result.xlsx 저장됨")

4. 직접 부딪힌 에러 2가지와 해결법

에러 ① anthropic.BadRequestError — max_tokens 미설정

처음 코드를 짤 때 max_tokens를 빠뜨렸다. OpenAI는 이 값이 없어도 기본값으로 작동하는데, Claude는 반드시 명시해야 한다. 없으면 즉시 BadRequestError를 뱉는다. 요약 작업 기준으로 512~1024 사이가 적당하다. 긴 문서 번역처럼 출력이 많아야 하면 4096까지 올려야 답이 잘리지 않는다.

에러 ② message.content 접근 방식 혼동

OpenAI 코드 습관으로 response.choices[0].message.content처럼 접근했다가 AttributeError가 떴다. Claude는 구조가 다르다. 응답 객체의 content는 리스트이고, 첫 번째 요소의 .text로 텍스트를 꺼낸다 — message.content[0].text. 이 차이 하나를 모르면 30분을 날린다. 위 코드에 이미 반영해 두었다.

5. GPT-4o-mini와 실제 비교해보니

뉴스 기사 50건을 동일 프롬프트로 두 모델에 돌려보았다. 체감 차이는 명확했다.

비교 항목 claude-3-5-haiku gpt-4o-mini
긴 텍스트 요약 정확도 핵심 논지를 잘 추림, 군더더기 적음 간혹 부수적 내용이 요약에 섞임
응답 속도 평균 1.4초 평균 1.1초 (약간 빠름)
비용 (입력 1M 토큰) $0.80 $0.15 (더 저렴)
한국어 자연스러움 자연스러운 문어체 동등한 수준

비용만 보면 GPT-4o-mini가 압도적으로 유리하다. 단, 논문이나 계약서처럼 맥락을 놓치면 안 되는 긴 문서 요약은 Claude가 더 믿음직했다. 두 가지를 용도에 따라 나눠 쓰는 게 지금 내 방식이다. 가볍고 빠른 작업은 GPT-4o-mini, 밀도 있는 분석이 필요한 문서는 Claude — 이 조합이 비용과 품질 두 마리 토끼를 동시에 잡는다.