LLM API 첫 호출하기: 키 발급부터 응답까지

API 키를 안전하게 두는 법부터 Python으로 첫 요청을 보내고 응답의 본문·종료 이유·사용량을 읽는 법까지, Claude API를 예로 정리했습니다.

단계별 따라하기

1. 1

   API 키 만들고 코드 밖에 두기

   API로 LLM을 쓰려면 먼저 API 키가 필요합니다. Claude API라면 Claude Console에 가입한 뒤 새 API 키를 만듭니다. 이 키로 들어온 요청은 모두 내 계정에 요금이 청구되니 비밀번호처럼 다뤄야 합니다.

   키는 코드에 직접 적지 말고 ANTHROPIC_API_KEY라는 환경 변수에 넣으세요. 공식 SDK가 이 환경 변수를 자동으로 읽기 때문에 코드에는 키가 한 글자도 남지 않습니다.

   API 키를 둘 곳과 두면 안 되는 곳

   두는 곳	판단	이유
   코드 안 (api_key="…")	안 됨	저장소에 올리거나 화면을 공유하는 순간 함께 새어 나감
   채팅·메신저·이슈 글	안 됨	기록이 남고 여러 사람이 봄
   환경 변수 ANTHROPIC_API_KEY	개발할 때 좋음	SDK가 자동으로 읽고 코드에 남지 않음
   클라우드의 비밀 관리 기능	서버·배포할 때 좋음	접근 권한과 키 교체를 한곳에서 관리

   확인해 보기

   • macOS·리눅스 터미널에서 export ANTHROPIC_API_KEY="발급받은 키"로 설정한 뒤 python3 -c "import os; print('ANTHROPIC_API_KEY' in os.environ)"를 실행해 True가 나오는지 보세요. 키 값 자체는 화면에 출력하지 마세요.
   • 키가 새어 나갔다고 의심되면 Console에서 그 키를 바로 삭제하고 새 키를 만드세요.
2. 2

   SDK 설치하고 첫 요청 보내기

   프로젝트 폴더에 가상 환경을 만들고 공식 Python SDK인 anthropic을 설치합니다. 요청 하나에는 세 가지가 꼭 들어갑니다. 어떤 모델에 보낼지(model), 답을 최대 얼마나 길게 받을지(max_tokens), 무엇을 물을지(messages)입니다.

   코드를 처음부터 쓰기 막막하다면 AI 코딩 도우미에게 조건을 분명히 주고 요청해도 됩니다. 받은 코드는 공식 문서의 시작하기 예제와 한 줄씩 비교해 보세요.

   Python으로 Claude API를 처음 호출해 보려고 해. API 키는 ANTHROPIC_API_KEY 환경 변수에 넣어 뒀어.
   공식 anthropic SDK로 claude-opus-5-5 모델에 '고객 문의 답장에 꼭 들어가야 할 것 세 가지를 알려 줘.'라고 묻고, 답의 글만 출력하는 가장 짧은 코드를 써 줘.
   설치 명령과, 코드의 각 부분이 무슨 뜻인지도 알려 줘.

   먼저 터미널에서 가상 환경을 만들어 켜고 SDK를 설치하세요. python3 -m venv .venv, source .venv/bin/activate, pip install anthropic 순서입니다.

   아래 코드를 first_call.py로 저장하고 python first_call.py로 실행하면 답이 출력됩니다.

   코드 예시복사

   import anthropic client = anthropic.Anthropic() # ANTHROPIC_API_KEY 환경 변수를 자동으로 읽음 message = client.messages.create( model="claude-opus-5-5", max_tokens=1000, messages=[ {"role": "user", "content": "고객 문의 답장에 꼭 들어가야 할 것 세 가지를 알려 줘."} ], ) for block in message.content: if block.type == "text": print(block.text)

   anthropic.Anthropic()

   클라이언트를 만듭니다. 키를 따로 넘기지 않으면 ANTHROPIC_API_KEY 환경 변수에서 읽습니다.

   model="claude-opus-5-5"

   요청을 처리할 모델입니다. 모델마다 성능·속도·가격이 다르니 공식 문서의 모델 목록에서 고르세요.

   max_tokens=1000

   출력의 상한(토큰)입니다. 이 모델이 답하기 전에 생각하는 데 쓰는 토큰도 여기에 포함되니 너무 작게 잡지 마세요.

   messages=[{"role": "user", ...}]

   주고받는 메시지 목록입니다. API는 앞의 요청을 기억하지 않으니, 이어서 물으려면 앞의 질문과 답을 목록에 함께 보냅니다.

   block.type == "text"

   응답의 content는 블록 목록입니다. 생각 과정을 담는 thinking 블록처럼 다른 종류가 섞일 수 있어서 text 블록만 골라 출력합니다.

   확인해 보기

   • 답이 출력되면 첫 호출에 성공한 것입니다. 오류가 나면 4단계의 표에서 상태 코드부터 찾아보세요.
   • export로 설정한 환경 변수는 그 터미널 창에서만 유지됩니다. 새 창에서 401 오류가 나면 1단계의 확인 명령부터 다시 실행하세요.
3. 3

   응답에서 본문·종료 이유·사용량 읽기

   응답에는 답의 글 말고도 서비스에 꼭 필요한 정보가 들어 있습니다. 특히 stop_reason과 usage는 처음부터 확인하는 습관을 들이세요.

   stop_reason이 max_tokens라면 답이 상한에 걸려 중간에 잘린 것입니다. 잘린 답이 그대로 사용자에게 가지 않도록 코드에서 먼저 걸러 내세요.

   응답에서 먼저 볼 필드 (값은 예시)

   필드	뜻	예시 값
   content	답이 담긴 블록 목록. 글은 type이 text인 블록에 있음	[{type: "text", text: "…"}]
   stop_reason	생성을 멈춘 이유	end_turn (정상 종료), max_tokens (상한에서 잘림), refusal (안전상 거절)
   usage.input_tokens	보낸 입력의 토큰 수	31
   usage.output_tokens	받은 출력의 토큰 수 (생각에 쓴 토큰 포함)	412

   앞의 코드에 두 가지를 더해 줘.
   1) 답이 max_tokens에서 잘렸으면 경고를 출력할 것
   2) 마지막에 입력·출력 토큰 수를 출력할 것

   답을 출력하는 for 문 아래에 다음 코드를 덧붙이면 됩니다.

   코드 예시복사

   if message.stop_reason == "max_tokens": print("[주의] 답이 max_tokens에서 잘렸습니다.") print("입력 토큰:", message.usage.input_tokens) print("출력 토큰:", message.usage.output_tokens)

   message.stop_reason == "max_tokens"

   상한에 걸려 잘렸는지 확인합니다. 정상적으로 끝나면 end_turn입니다.

   message.usage.input_tokens

   보낸 입력의 토큰 수입니다.

   message.usage.output_tokens

   받은 출력의 토큰 수입니다. 화면에 보이는 답보다 클 수 있습니다(5단계 참고).

   확인해 보기

   • max_tokens를 50으로 바꿔 다시 실행해 보세요. 경고가 출력되면 잘린 답을 제대로 걸러 내는 것입니다. 확인한 뒤에는 원래 값으로 되돌리세요.
4. 4

   오류가 나면 상태 코드부터 보기

   요청이 실패하면 API는 HTTP 상태 코드와 함께 오류 종류(type)와 메시지를 돌려줍니다. 상태 코드만 봐도 내 요청을 고쳐야 하는지, 잠시 뒤 다시 하면 되는지 대부분 구별할 수 있습니다.

   공식 SDK는 연결 오류, 429, 5xx 같은 일시적인 오류를 기본적으로 두 번까지 자동으로 다시 시도합니다. 그래도 실패하면 오류를 잡아 사용자에게 알리고, 함께 온 request_id를 기록해 두세요. 문의할 때 원인을 찾기 쉬워집니다.

   자주 보는 오류와 대처

   상태 코드	오류 종류	뜻	대처
   400	invalid_request_error	요청 형식이나 내용에 문제가 있음	오류 메시지가 가리키는 값을 고치기
   401	authentication_error	API 키에 문제가 있음 (형식 오류, 폐기, 만료 등)	환경 변수와 키 상태 확인
   429	rate_limit_error	속도 제한이나 사용 한도에 걸림	잠시 뒤 다시 시도하고, 계속되면 Console에서 한도 확인
   500	api_error	Anthropic 쪽 내부 오류	잠시 뒤 다시 시도하고, 계속되면 request_id로 문의
   529	overloaded_error	API에 트래픽이 몰려 일시적으로 과부하	잠시 뒤 다시 시도

   첫 호출 코드를 실행했더니 이런 오류가 났어. 원인과 확인할 순서를 알려 줘.
   anthropic.AuthenticationError: Error code: 401 - {'type': 'error', 'error': {'type': 'authentication_error', 'message': 'invalid x-api-key'}}

   401 authentication_error는 API가 보낸 키를 인정하지 않았다는 뜻입니다. 코드보다 키 설정을 먼저 확인하세요.

   1) 이 터미널에 환경 변수가 있는지: 1단계의 확인 명령이 False를 출력하면 export부터 다시 합니다.

   2) 값이 온전한지: 복사할 때 키 일부가 빠지거나 앞뒤에 공백이나 따옴표가 섞이지 않았는지 확인합니다.

   3) 키가 살아 있는지: Console의 키 목록에서 그 키가 삭제·비활성화되거나 만료되지 않았는지 봅니다. 문제가 있으면 새 키를 만들어 다시 설정하세요.

   확인해 보기

   • ANTHROPIC_API_KEY=wrong python first_call.py처럼 그 명령에만 틀린 키를 넣어 실행해 보세요. 401이 날 때 내 코드가 어떻게 멈추는지 미리 볼 수 있습니다.
5. 5

   사용량으로 비용 계산하기

   요금은 usage의 토큰 수에 모델별 단가를 곱해 계산합니다. claude-opus-5-5는 100만 토큰당 입력 4달러, 출력 20달러입니다(2026년 10월 가격표 기준). 식으로 쓰면 비용(달러) = 입력 토큰 × 4 ÷ 1,000,000 + 출력 토큰 × 20 ÷ 1,000,000입니다.

   이 모델은 답하기 전에 생각하는 단계를 거칠 수 있고, 생각에 쓴 토큰도 출력 토큰으로 청구됩니다. 그래서 화면에 보이는 답이 짧아도 output_tokens가 꽤 클 수 있습니다. 간단한 작업이라면 output_config={"effort": "low"}로 생각하는 양을 줄여 비용과 응답 시간을 아낄 수 있습니다.

   요청 한 번의 비용 (claude-opus-5-5, 토큰 수는 예시)

   요청	입력 토큰	출력 토큰	비용
   2단계의 짧은 질문	31	412	약 $0.0084
   보고서 요약 (입력이 긴 요청)	3,000	600	$0.024

   확인해 보기

   • 보고서 요약을 하루 1,000번 하면 하루 $24, 30일이면 $720입니다. 서비스에 붙이기 전에 예상 호출 수로 한 달 비용을 먼저 어림해 보세요.
   • 실제 청구액은 며칠 써 본 뒤 Console의 사용량 화면에서 확인하세요. 가격은 바뀔 수 있으니 계산할 때마다 최신 가격표를 보세요.