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

1. 1

   API 키 만들고 코드 밖에 두기

   채팅창에 질문을 쓰는 대신 내 프로그램이 질문을 보내고 응답을 받게 해 봅시다. 이번 실습은 고객 정보를 넣지 않은 짧은 문장 하나를 사용합니다. 코드를 읽고 응답 처리부터 연습한 뒤, API 요금과 계정 사용 범위를 확인한 경우에만 실제 호출합니다. 채팅 서비스 구독료와 API 사용료는 별개로 확인합니다.

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

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

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

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

   확인해 보기

   • 키를 명령문이나 채팅에 붙이지 않습니다. 아래 코드는 키 환경 변수가 없으면 화면에 표시하지 않는 입력으로 받아 현재 프로그램 안에서만 사용합니다.
   • 환경 변수도 로그·프로세스·설정 파일 관리가 필요합니다. 키 유출이 의심되면 서비스의 키 관리에서 폐기·교체하고 사용 기록을 확인합니다.

1. 2

   SDK 설치하고 첫 요청 보내기

   별도 폴더에서 python3 -m venv .venv로 가상 환경을 만들고 source .venv/bin/activate로 켠 뒤 python -m pip install anthropic으로 공식 SDK를 설치합니다(macOS·Linux 예). Windows에서는 가상 환경을 켜는 경로가 다릅니다. 설치한 버전은 python -m pip show anthropic으로 확인해 실습 기록에 남깁니다.

   

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

   공식 anthropic Python SDK로 짧은 연습 질문을 보내는 코드를 검토해 줘. 키는 출력하지 않고, 모델 ID는 내가 현재 문서와 계정에서 확인해 입력할 거야. 자동 재시도 없이 한 번 요청하고 응답의 종료 이유를 먼저 검사해.

   first_call.py라는 파일로 저장한 뒤 python first_call.py로 실행합니다. 모델 ID는 현재 공식 문서와 계정에서 사용 가능한 값을 확인해 입력합니다. 아래 코드는 편집자가 작성한 최소 실습용 예제이며 실제 응답 로그는 아닙니다.

   코드 예시복사

   import getpass import os import anthropic def completed_text(message): if message.stop_reason != "end_turn": raise ValueError(f"Response not complete: {message.stop_reason}") text = "\n".join(block.text for block in message.content if block.type == "text") if not text.strip(): raise ValueError("No text in response") return text if __name__ == "__main__": model = input("Model ID from current documentation: ").strip() if not model: raise SystemExit("A model ID is required") key = os.environ.get("ANTHROPIC_API_KEY") or getpass.getpass("API key: ") if not key: raise SystemExit("An API key is required") client = anthropic.Anthropic(api_key=key, max_retries=0, timeout=30.0) try: message = client.messages.create( model=model, max_tokens=1000, messages=[{"role": "user", "content": "List three things a customer-support reply should contain."}], ) print("usage:", message.usage.model_dump()) print(completed_text(message)) except anthropic.APIStatusError as exc: print("HTTP:", exc.status_code, "request_id:", exc.request_id) except anthropic.APIConnectionError: print("Connection failed; check the network before retrying") except ValueError as exc: print(exc)

   확인해 보기

   • 이 코드를 실행하면 실제 API 요청이 발생합니다. 모델·단가·허용 한도를 확인한 뒤 한 번만 시도하세요.
   • 답이 없으면 종료 이유 또는 오류를 확인합니다. 같은 실행을 반복하기 전에 전송 여부와 사용량을 확인하세요.
2. 3

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

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

   

   본문을 출력하기 전에 stop_reason을 확인합니다. 이 단일 질문 예제는 end_turn으로 끝난 텍스트만 표시하고 max_tokens·refusal·다른 종료 이유는 보류합니다. 경고를 본문 뒤에 붙이면 이미 잘린 내용을 내보낸 뒤이므로 순서가 중요합니다. 도구 사용을 추가한 프로그램은 tool_use를 별도 흐름으로 처리해야 합니다.

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

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

   completed_text 함수를 API 호출 없이 테스트하고 싶어. 정상 종료, max_tokens, refusal 응답을 가짜 객체로 만들어 정상일 때만 텍스트가 나오는지 확인해 줘.

   아래를 test_first_call.py로 저장하고 python test_first_call.py로 실행합니다. 가짜 응답을 사용하는 검사라 API 키와 네트워크 호출이 필요 없습니다.

   코드 예시복사

   from types import SimpleNamespace as NS from first_call import completed_text for reason in ("end_turn", "max_tokens", "refusal"): fake = NS(stop_reason=reason, content=[NS(type="text", text="practice text")]) try: result = completed_text(fake) except ValueError: assert reason != "end_turn" else: assert reason == "end_turn" and result == "practice text" print("3 offline cases passed")

   확인해 보기

   • 정상 응답만 표시되고 잘린 응답과 거절 응답은 보류되는지 확인합니다.
   • 표의 31·412 토큰은 응답 필드를 읽는 연습용 값이며 위 질문을 실제로 측정한 사용량이 아닙니다.
3. 4

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

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

   이번 예제는 max_retries=0으로 자동 재시도를 껐습니다. 처음에는 한 실행이 몇 번의 요청을 만드는지 이해하는 편이 중요합니다. 실서비스에서 재시도를 넣을 때는 일시 오류만 대상으로 횟수와 대기 시간을 제한하고, 이미 처리된 요청을 다시 실행했을 때의 영향도 확인합니다.

   자주 보는 오류와 대처

   상태 코드	오류 종류	뜻	대처
   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) 코드가 읽는 위치를 확인합니다. 위 코드는 ANTHROPIC_API_KEY 환경 변수의 값을 먼저 쓰고, 값이 없을 때만 getpass의 숨김 입력을 엽니다. 예전 키가 환경 변수에 남아 있으면 새 키를 입력하는 창이 나오지 않습니다.

   2) Console의 키 목록에서 키가 활성 상태인지 확인합니다. 폐기되거나 유출이 의심되는 키는 교체하세요. 키 값을 출력하거나 오류 보고·채팅에 붙이지 않습니다.

   3) 숨김 입력으로 다시 지정하려면 macOS·Linux의 현재 터미널에서 unset ANTHROPIC_API_KEY로 기존 값을 제거한 뒤 python first_call.py를 실행합니다. 모델 ID 다음에 나오는 API key: 입력에 활성 키를 넣되, 앞뒤 공백·따옴표를 붙이지 않습니다. 키는 화면에 표시되지 않으며 명령문에 적지 않습니다.

   확인해 보기

   • 401은 같은 요청을 계속 반복하기보다 키·계정·요청 설정을 확인할 신호입니다. 키 값 전체를 오류 보고에 붙이지 않습니다.
   • 연결이 끊겼다는 사실만으로 서버가 요청을 처리하지 않았다고 단정하지 않습니다. 요청 ID와 사용 내역을 확인한 뒤 재시도합니다.
4. 5

   사용량으로 비용 계산하기

   연습 계산에서는 입력 100만 토큰당 4달러, 출력 20달러라는 가상 단가를 씁니다. 아래 31·412, 3,000·600 토큰도 계산을 위해 만든 값입니다. 실제 모델의 현재 가격이나 이 질문의 실측 사용량으로 인용하지 마세요.

   연습 식은 입력 토큰 × 4 ÷ 1,000,000 + 출력 토큰 × 20 ÷ 1,000,000입니다. 31·412를 넣으면 0.000124 + 0.00824 = 0.008364달러이고, 3,000·600이면 0.012 + 0.012 = 0.024달러입니다. 요청 수를 늘리기 전에 이 단위를 확인합니다.

   실제 계산에서는 선택한 모델과 사용 기능의 가격표를 사용합니다. 캐시·도구·추가 기능의 비용이 있다면 따로 포함하고, 화면에 보이는 글자 수 대신 응답의 사용량을 봅니다. max_tokens는 출력 상한이지 한 번의 요청에 대한 전체 비용 상한은 아닙니다.

   가상 단가와 토큰 수로 하는 비용 연습

   요청	입력 토큰	출력 토큰	비용
   연습 A	31	412	약 $0.0084
   보고서 요약 (입력이 긴 요청)	3,000	600	$0.024

   확인해 보기

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

정답을 맞혀야 다음 수업으로 가는 시험이 아닙니다. 해설을 읽고 이해하는 데 사용하세요.

1. Q1본문을 출력한 다음 max_tokens 경고를 붙였습니다. 무엇이 잘못됐나요?

   내 생각 적기 (선택)

   내 생각 적기 (선택)

   작성 내용은 전송되지 않으며, 페이지를 떠나거나 새로고침하면 사라져요. 필요한 내용은 복사해 두세요.

   답과 해설 보기

   잘린 답이 이미 사용 단계로 넘어갔습니다. 종료 이유를 먼저 검사하고 이 예제에서는 end_turn일 때만 텍스트를 표시합니다.

   해설을 읽고 이해했어요

   직접 비교한 표시이며 자동 채점은 아니에요.

2. Q2가상 단가 $4/$20에서 입력 3,000, 출력 600토큰을 100번 쓰면 얼마인가요?

   내 생각 적기 (선택)

   내 생각 적기 (선택)

   작성 내용은 전송되지 않으며, 페이지를 떠나거나 새로고침하면 사라져요. 필요한 내용은 복사해 두세요.

   답과 해설 보기

   한 번 0.024달러이므로 100번은 2.40달러입니다. 단가와 토큰 수는 연습용이며, 실제 청구에는 현재 요금과 해당하는 다른 비용도 확인해야 합니다.

   해설을 읽고 이해했어요

   직접 비교한 표시이며 자동 채점은 아니에요.

3. Q3오프라인 검사 3개가 통과했습니다. API 연동까지 성공했다고 적어도 될까요?

   내 생각 적기 (선택)

   내 생각 적기 (선택)

   작성 내용은 전송되지 않으며, 페이지를 떠나거나 새로고침하면 사라져요. 필요한 내용은 복사해 두세요.

   답과 해설 보기

   아닙니다. 가짜 응답에 대한 로컬 처리만 확인한 것입니다. 실제 계정 접근과 모델 응답은 별도의 호출 기록이 있어야 확인했다고 적을 수 있습니다.

   해설을 읽고 이해했어요

   직접 비교한 표시이며 자동 채점은 아니에요.

1. 6

   직접 해 보기: 한 호출의 기록 남기기

   먼저 네트워크 없는 테스트 세 가지를 실행하세요. 통과했다면 정상·잘림·거절을 구분하는 로컬 코드가 작동한다는 뜻입니다. 실제 모델 접속, 실제 거절 동작, 청구 정확성까지 확인한 것은 아닙니다. 시험한 범위를 기록에 구분해서 적습니다.

   실제 호출을 선택했다면 모델 ID, SDK 버전, 실행 시각, 종료 이유, usage, 요청 ID를 기록합니다. API 키와 고객 정보는 기록에 포함하지 않습니다. 결과 문장이 그럴듯한지도 별도로 읽습니다. 성공 상태의 응답을 받는 것과 고객에게 쓸 수 있는 답을 얻는 것은 다른 검사입니다.

   마지막에는 세 가지를 설명해 보세요. 키가 어디서 들어오는지, 본문을 보여 주는 조건이 무엇인지, 사용량을 비용으로 바꾸는 단위가 무엇인지입니다. 이 흐름을 설명할 수 있으면 다음 수업에서 출력 형식을 JSON으로 바꾸거나 코딩 도우미와 코드를 고칠 준비가 된 것입니다.