클로드 API 시작하기: 키 발급부터 파이썬 첫 호출까지

대화창에서 클로드를 쓰다 보면 "이 작업을 매일 자동으로 돌릴 수 없을까?"라는 생각이 듭니다. 매일 아침 뉴스 요약, 고객 문의 분류, 대량 문서 번역 같은 일입니다. 이럴 때 필요한 것이 Claude API입니다.

이 글은 API를 한 번도 써 본 적 없는 분을 기준으로, 첫 호출까지 막힘없이 가도록 정리했습니다.

API와 claude.ai 구독은 다릅니다

가장 먼저 짚어야 할 점입니다.

Pro를 구독 중이어도 API 비용은 따로 냅니다.

1단계. 개발자 콘솔 가입과 결제 등록

1. Anthropic의 개발자 콘솔(Claude Console)에 가입합니다.
2. 결제 메뉴에서 크레딧을 충전하거나 결제 수단을 등록합니다. 처음에는 소액(예: 5~10달러)으로 시작해도 테스트하기에 충분합니다.
3. 사용 한도(spend limit)를 설정해 두면 실수로 비용이 크게 나오는 것을 막을 수 있습니다.

2단계. API 키 발급

콘솔의 API Keys 메뉴에서 새 키를 만듭니다. 키는 sk-ant-로 시작하는 긴 문자열이며, 생성 직후 한 번만 전체가 표시되니 바로 안전한 곳에 저장하세요.

키 보관 원칙

• 코드 안에 직접 적지 않습니다.
• 환경 변수나 .env 파일에 저장하고, .env는 반드시 .gitignore에 넣습니다.
• 용도별로 키를 나누면(개발용·운영용) 유출 시 피해 범위를 줄일 수 있습니다.

윈도우 PowerShell에서 현재 세션에 환경 변수를 설정하는 예시입니다.

$env:ANTHROPIC_API_KEY = "여기에_발급받은_키"

3단계. 파이썬 SDK 설치

pip install anthropic

4단계. 첫 호출

hello_claude.py 파일을 만들고 다음 코드를 넣습니다.

import anthropic

# ANTHROPIC_API_KEY 환경 변수를 자동으로 읽는다
client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "직장인이 오전 집중력을 높이는 방법 3가지를 한 줄씩 알려줘."}
    ],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

print(response.usage)  # 입력·출력 토큰 수 확인

실행합니다.

python hello_claude.py

답변과 함께 usage에 입력·출력 토큰 수가 출력되면 성공입니다. 이 토큰 수가 곧 비용 계산의 기준입니다.

코드 살펴보기

모델 ID는 새 모델이 나오면 바뀝니다. 최신 목록은 공식 모델 개요 문서에서 확인하세요.

자주 만나는 오류

SDK는 일시적인 오류(429, 5xx)에 대해 기본적으로 몇 차례 자동 재시도합니다.

💬 키 관리에서 식은땀 흘린 경험

API를 처음 쓸 때 저도 키를 코드에 그대로 적었다가, 깃에 올리기 직전에 발견하고 식은땀을 흘린 적이 있습니다. 그 뒤로는 프로젝트를 만들자마자 .gitignore에 .env부터 넣는 것을 습관으로 삼았습니다. 그리고 콘솔의 사용 한도 설정은 꼭 해 두세요. 반복문 실수 하나로 요청이 수천 번 나가는 일은 생각보다 쉽게 일어납니다.

이 글의 요점

1. API는 claude.ai 구독과 별도이며, 개발자 콘솔에서 결제 등록과 키 발급을 합니다.
2. 키는 환경 변수나 .env에 보관하고 깃에 올리지 않습니다.
3. pip install anthropic 후 messages.create로 첫 호출을 하고, usage로 토큰 수를 확인하세요.

출처

• Claude API 시작하기 (Anthropic 공식 문서)
• Anthropic Python SDK (GitHub)