Claude API로 사이드 프로젝트 만들기: 비용부터 배포까지 (2026)

Claude API로 사이드 프로젝트를 시작하는 데 필요한 것은 Anthropic 계정, API 키, 그리고 pip install anthropic 한 줄이다. 이 가이드는 API 키 발급부터 첫 번째 응답 받기, 실제 동작하는 웹 앱 배포, 월 1만원 이하로 운영하는 비용 관리까지 한국 개발자 기준으로 전부 다룬다.

1단계: API 키 발급

Anthropic 계정 및 API 키 생성

1. console.anthropic.com 접속
2. 회원가입 (Google 계정 연동 가능)
3. Settings → API Keys → Create Key
4. 키 이름 입력 (예: side-project-dev) → 생성
5. 키를 즉시 복사 — 다시 볼 수 없음

키 형식: sk-ant-api03-... (60+ 자리)

크레딧 구매

처음 가입 시 $5 무료 크레딧이 제공된다. 사이드 프로젝트 테스트에는 충분하다.

추가 구매: Settings → Billing → Add credits (최소 $5 단위, 신용카드 필요).

한국 카드: 대부분의 VISA/Mastercard 해외 결제 가능 카드 사용 가능. 카카오뱅크 해외 결제 카드, 트래블로그 등도 OK.

2단계: 첫 번째 API 호출

Python

pip install anthropic

import anthropic

client = anthropic.Anthropic(api_key="sk-ant-api03-...")  # 또는 환경변수로

message = client.messages.create(
    model="claude-haiku-4-5",  # 가장 빠르고 저렴
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "안녕하세요! 파이썬으로 피보나치 수열을 구현해줘."}
    ]
)

print(message.content[0].text)

Node.js / TypeScript

npm install @anthropic-ai/sdk

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

const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

const message = await client.messages.create({
  model: "claude-haiku-4-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "TypeScript로 Todo 앱 컴포넌트 작성해줘" }],
});

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

환경변수로 키 관리 (보안 필수)

코드에 API 키를 직접 쓰지 말 것. .env 파일 사용:

# .env
ANTHROPIC_API_KEY=sk-ant-api03-...

# Python
import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

.gitignore에 .env 추가 필수:

# .gitignore
.env
.env.local

3단계: 실전 사이드 프로젝트 패턴

프로젝트 1: 이력서 분석기

def analyze_resume(resume_text: str, job_description: str) -> dict:
    """이력서와 JD를 비교해 핵심 피드백을 반환"""
    client = Anthropic()
    
    response = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=2048,
        system="""당신은 10년 경력의 채용 전문가입니다.
이력서와 채용공고를 분석해 JSON 형식으로 응답하세요:
{
  "match_score": 0-100,
  "strengths": ["강점1", "강점2"],
  "gaps": ["부족한 점1", "부족한 점2"],
  "suggestions": ["개선 제안1", "개선 제안2"]
}""",
        messages=[{
            "role": "user",
            "content": f"이력서:\n{resume_text}\n\n채용공고:\n{job_description}"
        }]
    )
    
    import json
    return json.loads(response.content[0].text)

예상 비용: 이력서 1건 분석 = ~$0.003 (Sonnet 기준, 약 4원)

프로젝트 2: 한국어 맞춤법 교정 API

def correct_korean_text(text: str) -> str:
    """한국어 맞춤법과 문체 개선"""
    client = Anthropic()
    
    response = client.messages.create(
        model="claude-haiku-4-5",  # 단순 교정엔 Haiku 충분
        max_tokens=len(text) * 2,
        system="""한국어 맞춤법 교정 전문가입니다.
입력된 텍스트의 맞춤법, 띄어쓰기, 문장 구조를 교정해 수정본만 반환하세요.
설명 없이 교정된 텍스트만 출력.""",
        messages=[{"role": "user", "content": text}]
    )
    
    return response.content[0].text

예상 비용: 500자 교정 1회 = ~$0.0003 (Haiku 기준, 0.4원)

프로젝트 3: 법률/계약서 요약기

def summarize_contract(contract_text: str) -> str:
    """계약서를 평이한 한국어로 요약"""
    client = Anthropic()
    
    response = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=1500,
        system="""법률 문서 전문 번역가입니다.
계약서를 일반인도 이해할 수 있는 쉬운 한국어로 요약하세요:
1. 핵심 내용 (3-5개 불릿)
2. 주의해야 할 조항
3. 권리와 의무 요약
형식은 마크다운 사용.""",
        messages=[{"role": "user", "content": f"계약서:\n{contract_text}"}]
    )
    
    return response.content[0].text

4단계: Next.js + Claude API 웹 앱 만들기

프로젝트 구조

my-claude-app/
├── app/
│   ├── api/
│   │   └── analyze/route.ts   ← Claude API 호출 서버 라우트
│   ├── page.tsx               ← 메인 UI
│   └── layout.tsx
├── .env.local                 ← API 키
└── package.json

API 라우트 작성

// app/api/analyze/route.ts
import Anthropic from "@anthropic-ai/sdk";
import { NextRequest, NextResponse } from "next/server";

const client = new Anthropic();

export async function POST(req: NextRequest) {
  const { text } = await req.json();
  
  if (!text?.trim()) {
    return NextResponse.json({ error: "텍스트를 입력해주세요" }, { status: 400 });
  }
  
  try {
    const message = await client.messages.create({
      model: "claude-haiku-4-5",
      max_tokens: 1024,
      messages: [{ role: "user", content: text }],
    });
    
    return NextResponse.json({ 
      result: message.content[0].text,
      usage: message.usage
    });
  } catch (error) {
    return NextResponse.json({ error: "API 호출 실패" }, { status: 500 });
  }
}

스트리밍 응답 (UX 개선)

긴 응답은 스트리밍으로 처리하면 사용자 경험이 크게 좋아진다:

// app/api/stream/route.ts
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

export async function POST(req: Request) {
  const { message } = await req.json();
  
  const stream = client.messages.stream({
    model: "claude-haiku-4-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: message }],
  });
  
  // ReadableStream으로 변환해 클라이언트에 전달
  const readable = new ReadableStream({
    async start(controller) {
      for await (const chunk of stream) {
        if (chunk.type === "content_block_delta" && chunk.delta.type === "text_delta") {
          controller.enqueue(new TextEncoder().encode(chunk.delta.text));
        }
      }
      controller.close();
    },
  });
  
  return new Response(readable, {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
  });
}

5단계: 비용 추정 및 관리

모델별 1회 호출 비용 (일반적인 사이드 프로젝트 기준)

月 1만원 이하 운영 방법: Haiku를 기본 모델로 사용하고, 복잡한 작업만 Sonnet으로 라우팅.

프롬프트 캐싱으로 비용 90% 절감

같은 시스템 프롬프트를 반복 사용하는 경우 캐싱 필수:

# 시스템 프롬프트에 캐싱 적용
response = client.messages.create(
    model="claude-haiku-4-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "당신은 한국어 맞춤법 전문가입니다...(긴 프롬프트)",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[{"role": "user", "content": user_input}]
)

캐시 히트 시 입력 토큰 90% 할인 적용.

사용량 모니터링

# 응답에서 토큰 사용량 확인
print(f"입력 토큰: {response.usage.input_tokens}")
print(f"출력 토큰: {response.usage.output_tokens}")
print(f"캐시 히트: {getattr(response.usage, 'cache_read_input_tokens', 0)}")

Anthropic Console → Usage 탭에서 날짜별 사용량 그래프 확인 가능.

6단계: Vercel 배포

환경변수 설정

# vercel.json 또는 Vercel 대시보드에서 설정
vercel env add ANTHROPIC_API_KEY

Vercel 대시보드 → Project Settings → Environment Variables:

• ANTHROPIC_API_KEY = sk-ant-api03-...
• Environment: Production + Preview + Development

배포

# 초기 배포
vercel --prod

# 이후 배포
git push  # GitHub 연동 시 자동 배포

레이트 리밋 고려

Vercel Hobby 플랜: 함수 실행 시간 10초 제한. Claude API 응답이 10초 이상 걸릴 수 있으므로:

// vercel.json
{
  "functions": {
    "app/api/**": {
      "maxDuration": 30  // Pro 플랜은 최대 300초
    }
  }
}

스트리밍 응답 사용 시 타임아웃 문제 완화 가능.

실전 팁

API 키 보안

• 절대 GitHub에 API 키 커밋 금지
• 키 노출 시 즉시 Console에서 Revoke
• 팀 프로젝트: 개인 키가 아닌 팀 키 사용

에러 핸들링

from anthropic import APIStatusError, APIConnectionError

try:
    response = client.messages.create(...)
except APIStatusError as e:
    if e.status_code == 429:
        print("레이트 리밋 초과 — 잠시 후 재시도")
    elif e.status_code == 529:
        print("API 과부하 — 잠시 후 재시도")
    else:
        print(f"API 오류: {e.message}")
except APIConnectionError:
    print("네트워크 연결 오류")

한국어 최적화 프롬프트

한국어 응답 품질을 높이려면 시스템 프롬프트에 명시적으로 지시:

"항상 한국어로 응답하세요. 
영어 기술 용어는 한국어 설명과 함께 괄호 안에 표기하세요.
예: '비동기 처리(async/await)'"

자주 묻는 질문

Q: 무료로 사용할 수 있나요? 처음 가입 시 $5 무료 크레딧 제공. 이후엔 유료. 테스트 및 소규모 프로젝트엔 충분하다.

Q: Claude.ai 구독과 API는 다른 건가요? 다르다. Claude.ai ($20/월)는 웹 채팅 서비스, API는 개발자용 프로그래매틱 접근이다. 각각 별도 결제.

Q: 한국어 입력이 더 비싼가요? 아니다. Claude API는 텍스트를 토큰으로 계산하고, 한국어는 영어보다 토큰 효율이 낮을 수 있다(한 글자가 여러 토큰). 하지만 가격 차이는 미미한 수준이다.

Q: 개인 프로젝트에서 Claude API를 써서 돈을 벌어도 되나요? 가능하다. Anthropic의 사용 정책을 준수하면 된다. 불법 콘텐츠, 사기, 스팸 등 금지 사항 제외.

관련 가이드

• Claude Code 완벽 가이드 (한국어) — Claude API가 아닌 Claude Code CLI 가이드
• Claude API 비용 최적화 — 비용 절감 심화 전략
• Claude API Python SDK 퀵스타트 — 영어 심화 가이드

더 깊게 배우기

Claude Agent SDK Cookbook — $49 — 사이드 프로젝트를 넘어 프로덕션 에이전트까지. 40개 실전 패턴, Python + TypeScript 코드, 비용 최적화 전략 포함.

→ Agent SDK Cookbook 구매 — $49

30일 환불 보장. 즉시 다운로드.