Claude API 시작하는 법: 처음 해본 사람이 솔직하게 쓴 단계별 가이드

아마 이 글을 찾은 건 Claude를 그냥 채팅창에서 쓰는 걸 넘어서 뭔가 만들어보고 싶어졌기 때문일 거예요. 내 앱에 Claude를 붙이고 싶다거나, 반복 작업을 자동화하고 싶다거나. 근데 막상 Anthropic 개발자 문서 들어가면 영어에 코드에 온갖 낯선 단어들이 나오고, '이게 맞나?' 싶어서 창 닫아본 경험 있지 않으세요?

저도 딱 그랬거든요. 처음엔 Claude AI가 뭔지 기본 개념도 헷갈렸는데, API까지 연결하려니 진입 장벽이 이중으로 느껴졌어요. 그래서 이 글은 공식 문서 번역 같은 게 아니라, 제가 실제로 손 움직여가며 막혔던 지점들을 같이 짚어주는 방식으로 썼습니다.

API가 대체 뭔데 이걸 써야 해?

API. 처음 들으면 뭔가 대단한 기술 같은데, 쉽게 말하면 "두 프로그램이 서로 대화하는 창구"예요. 내가 만든 앱이 Claude한테 질문을 던지고 답을 받아오는 통로라고 생각하면 됩니다.

claude.ai 웹사이트에서 채팅하는 건 사람이 직접 타이핑하는 거잖아요. API를 쓰면 그 타이핑을 코드가 대신하는 거예요. 그래서 "매일 아침 뉴스 요약해줘"를 자동으로 돌리거나, 고객 문의 메일에 자동으로 초안을 뽑거나, 나만의 챗봇 서비스를 만들 수 있는 거고요.

친구가 "너 AI로 뭔가 만든다고 했잖아, 그게 어떻게 가능해?" 물어볼 때 "API로 연결하면 돼"라고 대답하는 거 — 그게 바로 이 글을 읽고 나서 할 수 있는 대화입니다.

시작 전에 딱 하나만 확인하세요

Claude API는 무료로 무한정 쓸 수 있는 게 아니에요. 이게 claude.ai 무료 플랜이랑 다른 점입니다. API는 사용한 만큼 과금되는 구조거든요. 토큰이라는 단위로 요금이 붙는데, 토큰은 대략 한국어 기준으로 한 글자 반~두 글자 정도라고 생각하면 돼요.

Claude 3.5 Sonnet 기준으로 입력 토큰 100만 개당 3달러, 출력 토큰 100만 개당 15달러예요. 숫자만 보면 감이 안 오는데, 실제로 일반적인 대화 한 번에 1,000~2,000 토큰 정도 씁니다. 하루 100번 테스트해도 몇 백 원 수준이에요. 처음 공부하고 테스트하는 용도로는 사실 거의 안 나옵니다. 겁먹지 않아도 돼요.

다만 Anthropic 계정에 카드를 등록해야 해서, 이 부분에서 망설이는 분들이 많아요. 돈 한 푼 안 쓰고 Claude를 써보고 싶다면 그 글을 먼저 보는 게 맞고, 개발이나 자동화를 본격적으로 해보려는 거라면 여기서 계속 읽으세요.

API 키 발급받기 — 실제로 어떻게 하냐면

console.anthropic.com으로 들어가세요. Anthropic의 개발자 콘솔이에요. Claude.ai 계정이랑 별개로 로그인해야 할 수도 있어요 — 같은 이메일로 가입하면 연동되는데, 처음이라면 그냥 새로 가입하면 됩니다.

로그인하면 왼쪽 메뉴에 API Keys가 있어요. 거기 들어가서 Create Key 버튼 누르고 이름 하나 붙여주면 끝이에요. 이름은 뭐든 상관없어요. "test-key", "my-project" 이런 식으로.

그러면 sk-ant-api03-...로 시작하는 긴 문자열이 나옵니다. 이게 API 키예요. 이 창 닫으면 다시 못 봐요. 꼭 어딘가에 복사해두세요. 잊어버리면 새로 만들면 되긴 하는데, 처음엔 이걸 몰라서 당황하는 분이 많아요.

그다음 결제 수단 등록. Settings → Billing에서 카드 등록하고, 크레딧을 충전하면 됩니다. 처음엔 5달러짜리 최소 충전으로 시작해도 충분해요. 테스트 용도로는 이게 몇 달은 갑니다.

첫 API 호출 — 진짜로 동작하는 코드

파이썬 기준으로 써볼게요. 파이썬이 없다면 python.org에서 설치 먼저. 터미널(맥) 또는 명령 프롬프트(윈도우)를 열고요.

먼저 Anthropic 라이브러리를 설치해야 해요.

pip install anthropic

그다음 파일을 하나 만들어요. 이름은 아무거나, test.py라고 하죠.

import anthropic

client = anthropic.Anthropic(api_key="여기에-발급받은-API-키-붙여넣기")

message = client.messages.create(
    model="claude-opus-4-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "안녕, 간단하게 자기소개 해줘"}
    ]
)

print(message.content[0].text)

저장하고 터미널에서 python test.py 실행하면 Claude가 자기소개하는 텍스트가 출력됩니다. 이게 되면 연결된 거예요. 진짜로.

처음 이 출력 보는 순간 솔직히 좀 신기해요. 내가 만든 코드가 AI한테 말을 걸고 답을 받아온 거니까.

여기서 막히면 십중팔구 이 이유예요

API 키를 코드에 직접 붙여넣는 방식은 테스트용으로는 괜찮은데, 실제로 쓸 때는 키가 노출될 위험이 있어요. 환경변수로 관리하는 게 맞는데, 처음엔 일단 동작 확인이 먼저니까 위 방식으로 해봐도 됩니다. 단, 코드를 GitHub 같은 곳에 올리면 절대 안 돼요. API 키 포함된 채로 올렸다가 해킹당하는 사례가 꽤 있어요.

AuthenticationError가 뜨면 API 키 오타거나 공백이 끼어있는 경우예요. 키 복사할 때 앞뒤 공백까지 딸려오는 경우가 있거든요.

RateLimitError는 너무 빠르게 많이 요청했을 때 나오는 거예요. 처음 계정은 분당 요청 수에 제한이 있어요. 잠깐 기다렸다 다시 하면 됩니다.

InsufficientCreditsError는 말 그대로 크레딧이 다 떨어진 거예요. 콘솔에서 충전하면 해결돼요.

그리고 max_tokens 값을 너무 작게 잡으면 답변이 중간에 잘려요. 처음엔 그냥 1024로 써두세요. 나중에 용도에 맞게 조절하면 됩니다.

이거 되면 그다음엔 뭘 할 수 있어?

API 연결이 됐다는 건 Claude를 내 서비스 안으로 끌어들였다는 뜻이에요. 여기서 뻗어나가는 방향이 다양한데요.

시스템 프롬프트를 추가하면 Claude한테 특정 역할을 고정시킬 수 있어요. "너는 이 회사 고객센터 직원이야, 항상 존댓말로 짧게 답해"처럼요. 메시지 배열에 이전 대화 내용을 담으면 멀티턴 대화, 즉 맥락을 기억하는 챗봇처럼 만들 수 있고요. 파일을 읽어서 요약하거나, 외부 API에서 데이터 가져와서 분석시키거나. 가능성이 확 넓어지는 시점이 여기예요.

Claude가 단순 채팅 이상으로 어떻게 쓰이는지 궁금하다면, 프로젝트 기능 활용법도 같이 보면 도움이 돼요. API 없이도 꽤 복잡한 워크플로를 만들 수 있어서, 개발이 익숙하지 않은 분들한테 특히 유용합니다.

📌 한 줄 정리: Claude API 시작은 세 단계예요. console.anthropic.com에서 API 키 발급 → 크레딧 충전 → pip install anthropic하고 첫 코드 실행. 처음엔 무조건 코드 먼저 돌려보는 게 제일 빠릅니다. 막히는 건 대부분 키 오타나 크레딧 문제예요.