내 서비스 안에 클로드를 직접 넣고 싶다면 Claude API가 출발점입니다. 이 글은 Claude API 사용법을 첫 호출부터 도구 호출(tool use)까지 예제로 정리합니다. 채팅앱·Claude Code와 달리, API는 내가 만든 코드에서 클로드를 부르는 방식이에요. (세 방식의 차이는 클로드로 코딩 시작하기를 참고하세요.)
1. API 키 발급 & 첫 호출
먼저 Claude 콘솔에서 API 키를 발급받습니다. 키는 코드에 직접 박지 말고 환경변수(ANTHROPIC_API_KEY)로 두세요. 파이썬이 가장 간단합니다.
pip install anthropicimport anthropic
client = anthropic.Anthropic() # ANTHROPIC_API_KEY 환경변수를 자동으로 읽음
msg = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
messages=[{"role": "user", "content": "파이썬으로 1부터 10까지 합 구하는 코드 줘"}],
)
print(msg.content[0].text)messages.create()가 핵심 호출이고, 응답 텍스트는 msg.content[0].text에 들어옵니다.
2. 메시지 & 시스템 프롬프트
대화는 messages 배열에 user/assistant 역할로 쌓입니다. 클로드의 역할·말투·규칙은 system으로 지정합니다.
msg = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
system="너는 간결하게 답하는 한국어 코딩 비서야. 코드에는 짧은 주석을 단다.",
messages=[
{"role": "user", "content": "리스트에서 중복 제거하는 법"},
{"role": "assistant", "content": "set()을 쓰면 됩니다."},
{"role": "user", "content": "순서를 유지하면서 하려면?"},
],
)이전 대화를 계속 이어가려면 주고받은 메시지를 배열에 그대로 누적해 보내면 됩니다.
3. tool use(도구 호출) — 클로드에게 ‘손’을 주기
tool use는 클로드가 내가 정의한 함수를 호출하게 하는 기능입니다. 흐름은 4단계예요.
tools = [{
"name": "get_weather",
"description": "도시의 현재 날씨를 반환한다",
"input_schema": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
}]
# 1) tools와 함께 요청 → 2) 클로드가 'get_weather(city=서울)' 호출이 필요하다고 tool_use로 응답
# 3) 내가 실제 get_weather 함수를 실행 → 4) 그 결과를 tool_result로 다시 보내면 최종 답을 만든다핵심은 클로드가 직접 외부를 호출하는 게 아니라, “이 함수를 이 인자로 불러줘”라고 요청하고 실행은 내 코드가 한다는 점입니다. (참고 — Claude Code에서 쓰는 MCP도 결국 이 tool use 위에서 동작합니다.)
4. 모델 선택 (용도별)
| 모델 | 성격 | 잘 맞는 일 |
|---|---|---|
| Opus | 가장 강력 | 복잡한 추론·대형 코딩 |
| Sonnet | 균형(기본 추천) | 대부분의 작업 |
| Haiku | 빠르고 저렴 | 대량·단순·실시간 |
정확한 모델 ID(예 — claude-sonnet-4-6, claude-opus-4-6, claude-haiku-4-5)와 세대는 자주 갱신되니, 코딩 직전 공식 문서에서 확인하세요. 최종 확인일 2026-05-26.
5. 비용 & 레이트리밋 주의
- 토큰당 과금 → 입력·출력 토큰 수에 비례하고, 모델마다 단가가 다릅니다. 큰 컨텍스트를 매번 보내면 비용이 빠르게 늡니다.
- 레이트리밋 → 사용량 티어별로 분당 요청·토큰 한도가 있습니다. 운영 코드엔 재시도·백오프를 넣으세요.
- 키 보안 → 키는
.env·서버에만 두고, 절대 깃에 올리거나 프론트엔드에 노출하지 마세요. - 비용 통제 → 콘솔에서 사용량·예산 알림을 설정하고, 단순 작업엔 Haiku처럼 저렴한 모델을 씁니다.
마무리
API는 “키 발급 → messages.create → 필요하면 tool use”의 순서로 익히면 빠릅니다. 작은 스크립트부터 만들어보세요. 다음 글에서는 이 API 위에서 나만의 에이전트를 만드는 Claude Agent SDK로 넘어갑니다. 전체 로드맵은 개발자를 위한 클로드 활용법에서 볼 수 있습니다.
모델 ID·요금·한도는 변동될 수 있습니다. 최신 내용은 공식 문서를 확인하세요.
출처
함께 읽기