Claude API, 처음 연결하는 날 생기는 일들

어느 날 회사 슬랙에 이런 메시지가 올라왔어요. "우리도 Claude API 붙여서 뭔가 만들어볼 수 있지 않을까요?" 그 순간 다들 고개를 끄덕였지만, 막상 누가 시작할지는 아무도 말하지 않았죠. 저도 그 자리에서 손을 들진 못했어요. API라는 단어 자체가 뭔가 개발자 영역처럼 느껴졌거든요.

근데 실제로 해보니까, 진입 장벽이 생각보다 낮았어요. 물론 처음엔 에러 메시지 앞에서 멍하니 있었지만. 이 글은 그때 제가 겪은 과정을 거의 그대로 옮긴 거예요. Claude API가 뭔지 감도 안 잡히는 상태에서 시작한다고 가정하고요.

API가 뭔지부터 짚고 넘어가야 할 것 같아서

처음에 친구한테 "Claude API 써보려고"라고 했더니, "API가 뭐야?"라고 바로 물어봤어요. 당연한 질문이에요.

API는 쉽게 말하면 두 프로그램이 대화하는 창구예요. 제가 만든 앱이 Claude한테 질문을 던지면, Claude가 답을 돌려주는 통로가 API인 거죠. 우리가 ChatGPT 웹사이트에 접속해서 채팅하는 건 사람이 직접 화면을 보는 방식이잖아요. API는 그 과정을 사람 없이, 코드가 자동으로 처리하게 만드는 거예요.

그러니까 "Claude API 쓴다"는 건 Claude 기능을 내가 만든 서비스에 직접 심는다는 뜻이에요. 고객 상담 자동화, 문서 요약 도구, 사내 챗봇... 이런 것들이 다 API로 돌아가요.

시작 전에 딱 두 가지만 준비하면 돼요

Anthropic 계정이랑 API 키. 이게 전부예요.

console.anthropic.com에 들어가서 가입하면 돼요. 구글 계정으로도 되고요. 가입 후에 "API Keys" 메뉴에서 키를 발급받는데, 이게 일종의 비밀번호예요. 이걸 가지고 있어야 Claude한테 요청을 보낼 수 있어요.

여기서 첫 번째로 많이 하는 실수가 나와요. API 키를 코드에 그대로 붙여넣는 거예요. 깃허브에 올리면 그 순간 전 세계 누구나 볼 수 있어요. 실제로 키 유출돼서 요금 폭탄 맞은 경우가 꽤 있어요. 키는 반드시 환경변수로 관리해야 해요. 쉽게 말해, 코드 파일이 아니라 별도의 숨겨진 파일에 보관하는 방식이에요. 이 부분은 나중에 별도 글에서 자세히 다룰 거예요.

그리고 요금 문제. 가입하면 일정 크레딧을 무료로 줘요. 처음 테스트하는 데는 충분해요. 근데 "토큰"이라는 개념이 나오는데, 토큰은 대략 단어 하나보다 약간 작은 단위예요. Claude한테 긴 글을 보내면 토큰을 많이 쓰고, 짧은 질문이면 적게 써요. 요금은 토큰 수에 따라 달라지는 구조예요. 1만 토큰이 어느 정도냐면, A4 7~8장 분량의 텍스트라고 보면 돼요.

첫 호출 코드, 실제로 돌려보면 이렇게 돼요

파이썬 기준으로 설명할게요. 파이썬이 없어도 일단 읽어보세요. 구조만 이해하면 되니까요.

터미널에 pip install anthropic 치면 Anthropic 공식 라이브러리가 설치돼요. 그다음 이런 코드를 실행해요.

import anthropic

client = anthropic.Anthropic(api_key="여기에_키_입력")

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

print(message.content)

실행하면 Claude가 자기소개를 해줘요. 이게 전부예요. 처음에 저도 "이게 다야?" 싶었어요. 근데 이 단순한 구조에서 모든 게 출발해요.

model 자리에 들어가는 값이 어떤 Claude를 쓸지 결정해요. claude-opus-4-5가 현재 가장 강력한 버전이고, 더 빠르고 저렴한 버전도 있어요. max_tokens는 Claude가 돌려줄 답변의 최대 길이예요. 너무 작게 설정하면 답변이 중간에 잘려요. 이 부분에서 많이 헤매거든요. 모델별 차이랑 토큰 설정 전략은 다음 글에서 따로 다룰 예정이에요.

그래서 실제로 막히는 건 어디냐면

코드 자체보다 환경 문제로 막히는 경우가 훨씬 많아요.

파이썬 버전이 맞지 않거나, 라이브러리 설치가 가상환경 밖에서 돼서 코드에서 인식을 못 하거나. 가상환경이 뭔지 모르는 분들 많은데, 쉽게 말해 프로젝트마다 독립적인 설치 공간을 만드는 거예요. 이게 없으면 나중에 다른 프로젝트에서 버전 충돌이 나요. 귀찮더라도 처음부터 습관 들이는 게 나중에 훨씬 편해요.

또 하나. API 응답이 생각보다 느리게 온다고 당황하지 마세요. 특히 답변이 긴 경우엔요. 이걸 해결하는 방법이 스트리밍인데, 답변이 생성되는 족족 실시간으로 받아오는 방식이에요. 챗GPT 쓸 때 글자가 하나씩 타이핑되듯 나오는 거 보셨죠? 그게 스트리밍이에요. 스트리밍 구현 방법은 이 시리즈 다음 글에서 실제 코드와 함께 설명할게요.

에러 코드도 처음엔 겁먹기 쉬운데, 자주 보이는 것만 알면 돼요. 401은 API 키 문제, 429는 요청을 너무 많이 보낸 거, 529는 Anthropic 서버가 바쁜 거예요. 대부분 이 세 가지 중 하나예요.

시스템 프롬프트, 이게 핵심이에요

"그냥 질문 던지면 되는 거 아니야?" 처음엔 저도 그렇게 생각했어요.

근데 Claude를 제대로 쓰려면 시스템 프롬프트를 이해해야 해요. 시스템 프롬프트는 Claude한테 역할을 미리 부여하는 지시문이에요. "너는 우리 회사 고객 상담 전문가야. 항상 친절하고, 제품 관련 질문 외에는 답변하지 마"라고 먼저 설정해두면, 이후 모든 대화가 그 틀 안에서 이뤄져요.

코드로 보면 이래요.

message = client.messages.create(
    model="claude-opus-4-5",
    max_tokens=1024,
    system="너는 친절한 고객 상담 전문가야. 제품 관련 질문에만 답해.",
    messages=[
        {"role": "user", "content": "환불 어떻게 해요?"}
    ]
)

system 파라미터 하나 추가된 게 전부인데, 결과물이 완전히 달라져요. 시스템 프롬프트 잘 짜는 게 Claude API 활용의 8할이에요. 이 부분은 프롬프트 설계 전략 편에서 구체적인 패턴들을 정리해서 다룰 거예요.

이 시리즈로 더 깊게 파고들기

이 글은 시작점이에요. 앞으로 다룰 내용들을 미리 소개할게요.

모델 선택과 토큰 비용 계산 — claude-opus-4-5, claude-sonnet, claude-haiku 각각 언제 쓰는 게 맞는지, 토큰 비용이 실제로 얼마나 나오는지 숫자로 비교해요. 같은 작업인데 모델 선택 잘못해서 비용이 10배 차이 나는 경우가 있거든요.

스트리밍 구현과 멀티턴 대화 — 답변을 실시간으로 받아오는 스트리밍 코드, 그리고 이전 대화를 기억하게 만드는 멀티턴 구조를 다뤄요. 이게 없으면 Claude가 매번 대화를 처음부터 시작해요.

시스템 프롬프트 설계 패턴 — 실제 서비스에서 쓰는 시스템 프롬프트 구조를 분해해요. 역할 부여, 제약 조건, 출력 형식 지정까지. 잘 짜인 시스템 프롬프트 하나가 fine-tuning보다 효과 좋을 때가 많아요.

API 키 보안과 환경변수 관리 — 키 유출 막는 방법, .env 파일 쓰는 법, 깃허브에 올려도 안전한 구조 만들기. 이거 모르고 배포했다가 낭패 보는 경우가 정말 많아요.

에러 핸들링과 재시도 로직 — 429 에러 왔을 때 자동으로 기다렸다가 재시도하는 코드, 서비스가 죽지 않게 만드는 방어 코드 패턴을 다뤄요.

📌 한 줄 정리: Claude API 시작은 계정 만들고, 키 발급받고, 열 줄짜리 코드 돌리는 것까지가 전부예요. 그다음부터는 시스템 프롬프트랑 에러 대응이 실력을 가르는 지점이에요.