Claude API 시작하기: 첫 호출까지 (개발자 입문)

Claude를 코드에서 직접 호출하고 싶다면 API를 씁니다. 이 글은 개발자가 처음 Claude API를 호출해보기까지의 과정을 정리한 입문 가이드입니다. (모델·가격은 변동될 수 있으니 공식 문서에서 최신 정보를 확인하세요.)

API는 채팅(claude.ai)과 무엇이 다른가

claude.ai 채팅과 API는 별개 제품입니다.

• claude.ai / 앱: 사람이 직접 대화하는 인터페이스. Pro/Max 구독으로 사용.
• API: 내 프로그램이 Claude를 호출하는 통로. 콘솔에서 키를 발급받아 토큰 사용량만큼 과금.

중요: Pro/Max 구독과 API 사용료는 별개입니다. 구독했다고 API가 공짜가 되지 않으며, API는 토큰당 비용이 따로 청구됩니다. 무료 티어(지속적인 무료 사용)는 없고, 신규 계정에 소액의 일회성 크레딧이 주어지는 경우가 있습니다.

1단계: 계정과 API 키 발급

1. 개발자 플랫폼(platform.claude.com, 콘솔)에 가입/로그인합니다.
2. 설정의 API Keys에서 새 키를 생성합니다.
3. 생성된 키는 한 번만 전체가 보이므로 안전한 곳에 저장합니다. 키는 비밀번호와 같아, 노출되면 누구나 내 사용량을 쓸 수 있습니다.
4. 키를 코드에 직접 박지 말고 환경변수로 다루는 것이 안전합니다.

export ANTHROPIC_API_KEY='발급받은-키'

2단계: 첫 API 호출 (curl)

Claude API의 기본은 Messages 엔드포인트입니다. 다음은 가장 단순한 호출 예시입니다.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      { "role": "user", "content": "안녕 Claude!" }
    ]
  }'

성공하면 HTTP 200과 함께 JSON 응답이 옵니다. 응답의 content 배열에 Claude의 답변 텍스트가, usage에 입력·출력 토큰 수가 담깁니다.

꼭 알아둘 헤더 3가지

• x-api-key — 인증 키. (OpenAI의 Authorization: Bearer와 다릅니다. Anthropic은 커스텀 헤더를 씁니다.)
• anthropic-version — API 버전. 현재 2023-06-01. 모든 요청에 필수입니다.
• content-type — application/json

공식 SDK(Python·TypeScript 등)를 쓰면 이 헤더들은 자동으로 붙습니다.

모델 문자열 (2026년 9월 기준)

프로덕션에서는 버전이 명시된 전체 모델 문자열을 쓰는 것이 안전합니다(버전 없는 별칭은 시점에 따라 다른 모델로 해석될 수 있음).

• claude-opus-5 — 최대 성능
• claude-sonnet-5 — 균형(대부분의 작업에 권장 기본값)
• claude-haiku-4-5-20251001 — 속도·저비용

대부분의 작업은 Sonnet으로 충분하고, 정말 고난도 추론이 필요할 때만 Opus를 쓰는 것이 비용 효율적입니다.

비용과 한도

API는 입력·출력 토큰 수에 따라 과금됩니다. 모델별 단가가 다르며(Opus가 가장 비싸고 Haiku가 가장 저렴), 정확한 단가는 공식 문서에서 확인하세요. 사용량에 따라 자동으로 올라가는 사용 등급(tier)별 요청·지출 한도(rate/spend limit)가 있고, 콘솔에서 현재 한도를 볼 수 있습니다.

다음 단계

• 멀티턴 대화, 시스템 프롬프트, stop reason 같은 Messages API 기본 패턴 익히기
• 도구 사용(tool use / function calling)으로 Claude가 외부 기능을 호출하게 하기
• 스트리밍 응답, 배치 처리, 프롬프트 캐싱으로 비용·지연 최적화

이 문서는 일반 안내용이며, 모델 문자열·가격·한도·API 버전은 Anthropic 정책에 따라 변경될 수 있습니다. 실제 구현 전 반드시 공식 문서(platform.claude.com/docs)에서 최신 값을 확인하세요. (기준: 2026년 9월, models overview·pricing 문서 재대조)

비용 절감 실전 팁

1. Prompt Caching (캐싱)

같은 시스템 프롬프트나 긴 컨텍스트(예: 문서 분석)를 반복 사용한다면 prompt caching이 핵심입니다. 최대 90% 비용 절감 가능합니다.

messages = client.messages.create(
    model="claude-sonnet-5",
    system=[
        {
            "type": "text",
            "text": "긴 시스템 프롬프트 또는 문서...",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[{"role": "user", "content": "..."}],
)

캐시는 5분간 유지되며, 자주 호출되는 워크플로면 비용이 크게 줄어듭니다.

2. Batch API (배치)

실시간 응답이 필요 없는 작업(예: 야간 대량 처리, 데이터셋 분석)은 batch API를 쓰면 50% 할인됩니다. 24시간 내 처리되며 단가가 절반입니다.

3. 적절한 모델 선택

• RAG 검색·분류·간단한 요약: Haiku 4.5 (가장 저렴)
• 일반 코딩·분석: Sonnet 5
• 복잡한 추론·에이전트: Opus 5

모든 작업에 Opus를 쓰는 건 가장 흔한 비용 낭비입니다.

자주 하는 실수

1. API 키 노출

가장 흔하고 위험한 실수입니다.

• 코드에 키를 하드코딩하지 마세요 — 항상 환경 변수 또는 secret 매니저로
• Git에 .env 파일 커밋 금지 — .gitignore에 추가
• 프론트엔드(브라우저) 코드에 API 키 절대 금지 — 백엔드 프록시 필요
• 키가 노출됐다면 즉시 Anthropic Console에서 폐기 후 새 키 발급

2. max_tokens 부족

응답이 중간에 잘리는 가장 흔한 원인입니다. max_tokens를 너무 작게 잡지 마세요. Opus 5은 최대 128K까지 가능합니다.

3. 에러 핸들링 누락

실서비스에서 무시하면 안 되는 에러들:

• 429 (Rate Limit): 재시도 시 지수 백오프 적용
• 529 (Overloaded): 서비스 부하. 일정 시간 후 재시도
• 400 (Invalid Request): 프롬프트 또는 파라미터 문제. 재시도 무의미
• 401 (Auth): API 키 문제. 재시도 무의미

4. 컨텍스트 누적 무시

긴 응답을 실시간으로 받고 싶다면 API 스트리밍(SSE)으로 응답을 조각조각 받아 바로 표시할 수 있습니다.

프로덕션에서 한도(429)·서버 과부하(529)를 안정적으로 다루려면 에러와 레이트리밋 다루기의 재시도 전략을 참고하세요.

복잡한 추론이 필요한 작업이라면 확장 사고로 답 품질을 높일 수 있습니다.

긴 대화에서 매번 전체 messages 배열을 다 보내야 합니다. 이게 누적되면 토큰이 폭증합니다.

• 일정 길이 넘으면 오래된 메시지 요약 후 압축
• 또는 server-side compaction(beta) 활용

유용한 SDK 외 도구

• Anthropic Console (console.anthropic.com): 웹 UI로 프롬프트 테스트, 토큰 카운트, 사용량 모니터링
• Workbench: 콘솔 내 도구. 모델·파라미터 바꿔가며 빠르게 비교
• Anthropic Cookbook (GitHub): 공식 예제 코드 모음
• LangChain, LlamaIndex: Claude 통합 지원 프레임워크 (선택)

다음 단계

• MCP 이해하기 — 외부 도구 연결 표준
• CLAUDE.md 작성 — 컨텍스트 효율화
• API vs 구독 비교 — 손익분기 분석

더 보기: Claude API 에러 처리·재시도 가이드

텍스트 호출에 익숙해졌다면 이미지를 함께 보내는 것도 어렵지 않습니다. Claude API 비전 — 이미지·PDF 입력 처리 방법에서 이어서 확인해 보세요.

관련 글

• Claude API 무료로 쓸 수 있을까? — 크레딧·대안
• 클로드 API 결제가 안 될 때 — 원인과 해결
• Claude API 키 발급·요금·사용법 완전정리
• 클로드 코드 API 키 발급 방법: 콘솔에서 만들고 연결하기