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

작성자:

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

OpenAI API를 쓰면서 저는 긴 문서를 요약할 때 종종 핵심에서 멀어진 답변이 나오는 걸 경험했다. 그럴 때마다 ‘뭔가 이걸로는 한계가 있나’ 하는 생각이 들었는데, 어느 날 팀원이 “Claude는 긴 텍스트 처리 능력이 더 뛰어나다”고 슬쩍 얘기했다. 저는 반신반의한 채로 Anthropic 콘솔을 열었고, 가입하자마자 무료 크레딧이 주어지는 걸 보고 놀랐다. 파이썬 연동도 15분도 안 걸려서 금방 준비를 마쳤다.

실제로 뉴스 기사 50건을 Claude와 GPT-4o-mini에 동시에 요약시켜 비교해봤다. 솔직히 말하면 결과물의 밀도 차이가 꽤 뚜렷했다. Claude 쪽이 더 짜임새 있고 핵심을 잘 뽑아냈는데, 그 과정에서 발생하는 약간의 불편함도 분명 있었다. 이번 글에서는 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 API와 거의 비슷한 구조라 기존 GPT 코드를 Claude용으로 바꾸는 데 10분도 채 걸리지 않았다. 다만 메시지 구조에서 system 역할을 별도 파라미터로 분리하는 점이 독특하다. 이 덕분에 프롬프트를 훨씬 깔끔하게 정리할 수 있지만, 처음에는 이 부분 때문에 약간 헷갈렸다.

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

개발 환경

  • Python 버전: 3.11 이상을 권장한다. 저는 3.11에서 작업했는데, 하위 버전에서는 의존성 문제 발생 가능성이 있다.
  • 편집기: VS Code를 주로 썼고, Cursor AI도 가끔 활용했다. 둘 다 대체로 무난하지만, 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-여기에_발급받은_키_입력

이 부분에서 특히 조심해야 한다. 절대 깃허브에 키를 올리면 안 된다. 저는 한 번 실수로 퍼블릭 레포에 올린 적이 있는데, Anthropic에서 곧바로 키를 비활성화하고 이메일로 알려줬다. 그때 다시 키를 새로 발급받고 .gitignore에 반드시 .env를 추가했다.

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

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

Claude API를 처음 다루면서 제일 먼저 확인한 건 단건 호출이 제대로 되는지 여부였다. GPT와 달리 messages.create() 메서드를 쓰는데, 의외로 system 파라미터에 역할을 지정하는 방식이 핵심 차이다. 이 부분은 문서만 보고 쉽게 이해하기 어려워서 한참 고민했다.

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))

직접 해보니 API 호출 자체는 무난하지만, 출력 결과가 아주 깔끔한 편은 아니었다. 특정 문장에 중요한 포인트가 잘 드러나지 않아 요약이 다소 모호하게 느껴질 때가 있었다. 그래서 단순히 호출하는 것만으로는 실무에서 바로 쓰기 힘들겠다는 생각이 들었다.

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

여러 기사를 한꺼번에 요약해야 할 때는 호출 제한과 오류 관리가 관건이다. 저는 여러 기사 리스트를 돌면서 summarize() 함수를 호출하고, 호출 사이에 1.5초 딜레이를 넣었다. Rate Limit 초과가 뜨면 30초 대기 후 재시도하는 로직도 추가했는데, 이 과정에서 딜레이 조절이 굉장히 까다로웠다.

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 저장됨")

이 코드를 돌리면서 한 가지 불편했던 점은, 간혹 Rate Limit 에러가 나서 재시도 로직에 진입할 때 호출이 지연되는 것이다. 특히 모바일 환경에서는 이런 에러 메시지 출력이 제대로 안 보여서 작업 상태를 파악하기 어려웠다. 그리고 결과를 엑셀로 저장하는 건 편리했지만, 대량 처리에는 시간이 꽤 걸려서 배치 작업으로 돌려야 할 듯하다.

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

에러 ① anthropic.BadRequestError — max_tokens 미설정

Claude API를 처음 다룰 때, OpenAI API와 비슷하다고 생각해 max_tokens 설정을 빼먹었다. 그런데 이 부분에서 확실히 차이가 났다. OpenAI는 이 값을 안 넣어도 기본값으로 넘어가지만, Claude는 꼭 명시하지 않으면 바로 BadRequestError를 던진다. 그 순간 왜 에러가 나는지 파악하는 데 시간이 꽤 걸렸다. 실제로 요약 작업 기준으로 512에서 1024 사이가 적당한데, 긴 문서 번역처럼 출력량이 많을 때는 4096까지 올려야 답이 중간에 잘리지 않는다. 이 부분이 명확하지 않으면 API 호출을 반복하다가 불필요한 시간과 비용을 쓰게 된다.

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

OpenAI API 경험에 익숙한 탓에 응답 데이터 구조를 똑같이 다루려다 또 문제가 생겼다. 보통 OpenAI는 response.choices[0].message.content 식으로 텍스트를 바로 꺼내는데, 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는 빠르고 가벼운 작업에 적합하지만, 중요한 내용을 놓치거나 부수적 정보가 섞이는 경우가 있었다. 그래서 저는 지금 두 모델을 쓰면서 작업 목적에 따라 구분한다. 간단한 요약이나 빠른 체크는 GPT-4o-mini에 맡기고, 깊이 있는 분석이나 긴 문서 요약은 Claude를 선택한다. 이렇게 하면 비용과 품질 모두 어느 정도 균형을 맞출 수 있었다.