API와 키 관리

모든 AI API는 같은 방식으로 동작합니다. 요청(request)을 보내고 응답(response)을 받습니다. 세부사항은 바뀌어도 패턴(pattern)은 바뀌지 않습니다.

유형: Build 언어: Python, TypeScript 선수 지식: Phase 0, Lesson 01 예상 시간: 약 30분

학습 목표

• 환경 변수(environment variable)와 .env 파일(file)을 사용해 API 키(API key)를 안전하게 저장합니다.
• Anthropic Python SDK와 원시 HTTP(raw HTTP)를 모두 사용해 LLM API 호출(API call)을 실행합니다.
• SDK 기반 요청/응답(request/response)과 raw HTTP 요청/응답 형식을 비교해 디버깅(debugging) 기준을 잡습니다.
• 인증(authentication), 사용량 제한(rate limit) 같은 흔한 API 오류(API error)를 식별하고 처리합니다.

문제

Phase 11부터는 Anthropic, OpenAI, Google 같은 LLM API를 호출하게 됩니다. Phase 13-16에서는 이런 API를 반복문(loop) 안에서 사용하는 에이전트(agent)를 만듭니다. API 키가 어떻게 동작하는지, 어디에 안전하게 저장해야 하는지, 첫 API 호출을 어떻게 만드는지 알아야 합니다.

PAI OJT에서는 키를 다루는 습관도 중요한 학습 대상입니다. API 키는 개인 비용과 회사 보안에 연결될 수 있으므로 코드에 직접 넣지 않고 환경 변수나 비공개 설정으로 분리합니다.

개념

sequenceDiagram
    participant C as 내 코드
    participant S as API 서버
    C->>S: HTTP 요청(API 키 포함)
    S->>C: HTTP 응답(JSON)

모든 API 호출에는 네 가지가 있습니다.

1. 엔드포인트(endpoint): 요청을 보낼 URL
2. API 키(API key): 인증(authentication) 정보
3. 요청 본문(request body): 내가 원하는 작업
4. 응답 본문(response body): 서버(server)가 돌려준 결과

직접 만들기

Step 1: API 키를 안전하게 저장하기

API 키를 코드에 직접 넣지 않습니다. 환경 변수를 사용합니다.

export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

또는 .env 파일을 사용할 수 있습니다. .env는 반드시 .gitignore에 추가합니다.

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

Step 2: 첫 API 호출(Python)

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=256,
    messages=[{"role": "user", "content": "신경망을 한 문장으로 설명해줘."}],
)

print(response.content[0].text)

SDK는 환경 변수에서 키를 읽고, 요청 형식을 Python 객체(object)로 감싸 줍니다.

Step 3: 첫 API 호출(TypeScript)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const response = await client.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 256,
  messages: [{ role: "user", content: "신경망을 한 문장으로 설명해줘." }],
});

console.log(response.content[0].text);

Step 4: 원시 HTTP(raw HTTP, SDK 없이)

import json
import os
import urllib.request

url = "https://api.anthropic.com/v1/messages"
headers = {
    "Content-Type": "application/json",
    "x-api-key": os.environ["ANTHROPIC_API_KEY"],
    "anthropic-version": "2023-06-01",
}
body = json.dumps({
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "신경망을 한 문장으로 설명해줘."}],
}).encode()

req = urllib.request.Request(url, data=body, headers=headers, method="POST")
with urllib.request.urlopen(req) as resp:
    result = json.loads(resp.read())
    print(result["content"][0]["text"])

SDK는 내부적으로 이런 HTTP 요청을 만들어 보냅니다. 원시 HTTP를 이해하면 인증 오류(authentication error), 요청 형식 오류(request format error), 응답 파싱 오류(response parsing error)를 더 쉽게 디버깅할 수 있습니다.

사용해보기

이 과정에서 자주 쓰게 될 API는 아래와 같습니다. 무료 크레딧(credit)이나 요금 정책은 바뀔 수 있으므로 실제 사용 전 제공자(provider) 문서를 확인합니다.

지금 당장 모든 API를 설정할 필요는 없습니다. 강의에서 요구할 때 설정합니다.

산출물 만들기

이 강의는 API 문제를 진단하는 프롬프트(prompt)를 산출합니다.

• outputs/prompt-api-troubleshooter.md: 인증(authentication), 사용량 제한(rate limit), 타임아웃(timeout) 같은 API 오류를 진단하는 프롬프트

또한 code/first_api_call.py를 실행해 SDK와 원시 HTTP 호출을 비교할 수 있습니다.

python phases/00-setup-and-tooling/04-apis-and-keys/code/first_api_call.py

연습문제

1. Anthropic API 키를 발급받아 첫 API 호출을 실행합니다.
2. 원시 HTTP 버전을 실행하고 SDK 버전과 응답 형식(response format)을 비교합니다.
3. 일부러 잘못된 API 키를 넣고 오류 메시지(error message)를 읽어 봅니다.
4. .env 또는 셸(shell) 환경 변수에 키를 저장하고, 키가 Git에 포함되지 않는지 확인합니다.

핵심 용어

더 읽을거리

• Anthropic Messages API — messages 요청/응답 구조를 확인합니다.
• OpenAI API Reference — OpenAI API 엔드포인트와 요청 형식을 비교합니다.
• The Twelve-Factor App: Config — 비밀값(secret)과 구성(config)을 코드에서 분리하는 이유를 확인합니다.