API가 무엇인지도 모르는 완전 초보라서 클로드에게 왕초보를 위한 실행 가이드를 부탁하여 진행했어요
소개
스터디를 하면서 API를 만들어보는 실습을 진행하게 되었는데, 사실 저는 API가 무엇인지도 잘 모르는 완전 초보였습니다. 코드를 받아도 어디서부터 시작해야 할지 막막했고, main.py를 실행하세요. 라는 말조차 어떻게 해야 하는지 몰랐습니다.
그래서 Claude에게 "API를 전혀 모르는 사람도 따라 할 수 있는 실행 가이드"를 만들어 달라고 요청했습니다. 목표는 단 하나였습니다. > 프로그램을 실제로 실행해서 API 서버가 동작하는 모습을 내 눈으로 확인해보기!
사용한 도구
- Claude
- Python
- FastAPI
- Uvicorn
- Anthropic API
Claude에게 요청한 프롬프트
text API가 무엇인지도 모르는 완전 초보입니다. 이 폴더 안의 main.py를 실제로 실행해서 API 서버를 확인하는 과정을 처음부터 끝까지 단계별로 설명해주세요. 터미널이 무엇인지부터, 왜 이 작업을 하는지, 어떤 결과가 정상인지, 초보자가 흔히 만나는 오류까지 함께 알려주세요.
Claude가 만들어준 실행 가이드
가이드는 단순히 명령어만 알려주는 것이 아니라,
API가 무엇인지
터미널은 왜 사용하는지
Python이 필요한 이유
requirements.txt가 하는 역할
Claude API Key가 필요한 이유
.env 파일을 사용하는 이유
서버가 켜진 상태가 왜 정상인지
까지 하나씩 설명해 주었습니다.
덕분에 단순히 따라 하는 것이 아니라 왜 이 과정을 하는지 이해하면서 진행할 수 있었습니다.
실제로 진행한 순서는 다음과 같았습니다.
터미널 실행
Python 설치 확인
프로젝트 폴더 이동
requirements.txt 설치
Claude API Key 발급
.env 설정
uvicorn으로 서버 실행
Swagger(
/docs) 접속/hello,/predictAPI 테스트
마지막에는 자주 발생하는 오류와 해결 방법까지 정리되어 있어서 막히는 부분도 스스로 해결할 수 있었습니다.
결과물
왕초보를 위한 실행 가이드
이 폴더 안의 main.py를 실제로 켜서 나만의 API 서버를 눈으로 확인하는 과정을 처음부터 끝까지 따라가는 가이드예요. 컴퓨터 프로그래밍 경험이 없어도 순서대로 따라 하면 됩니다.
0단계. API가 뭔지 한 줄로 다시
API는 "이렇게 요청하면 이런 응답을 준다"는 약속이에요. 우리가 만든 main.py가 그 약속을 지키는 프로그램이고, 지금부터 이 프로그램을 컴퓨터에서 실행시켜서(=서버를 켜서) 실제로 요청과 응답을 주고받아 볼 거예요.
1단계. 터미널 열기
이게 뭔가요: 터미널(Terminal)은 마우스 클릭 대신 글자로 명령을 내리는 화면이에요. 우리가 만든 파이썬 프로그램을 실행시키려면 이 화면이 필요해요.
어떻게 하나요:
Mac:
Command + Space를 누르고 "터미널" 입력 후 엔터Windows: 시작 메뉴에서 "명령 프롬프트" 또는 "PowerShell" 검색 후 실행
결과물: 커서가 깜빡이는 검은색(또는 흰색) 화면이 뜹니다. 여기에 글자를 치고 엔터를 누르면 컴퓨터가 명령을 실행해요.
2단계. 파이썬이 설치되어 있는지 확인
이게 뭔가요: 우리 프로그램은 파이썬(Python)이라는 언어로 짜여 있어서, 컴퓨터에 파이썬이 깔려 있어야 실행할 수 있어요.
어떻게 하나요: 터미널에 아래를 치고 엔터
bash
python3 --version결과물: Python 3.10.x 같은 버전 숫자가 나오면 설치되어 있는 거예요. "command not found" 같은 에러가 나오면 https://www.python.org/downloads/ 에서 먼저 설치해야 해요.
3단계. 이 폴더로 이동하기
이게 뭔가요: 터미널은 지금 어느 폴더에 있는지에 따라 명령이 다르게 동작해요. main.py가 있는 폴더로 직접 이동해야 그 파일을 실행시킬 수 있어요.
어떻게 하나요: 터미널에 cd (cd 뒤에 띄어쓰기)를 치고, 이 폴더("1주차 API만들기")를 마우스로 터미널 창에 끌어다 놓으면 경로가 자동으로 채워져요. 그다음 엔터.
bash
cd 여기에_폴더를_끌어다_놓으세요결과물: 터미널에 표시되는 경로가 .../1주차 API만들기로 바뀝니다.
4단계. 필요한 부품(패키지) 설치하기
이게 뭔가요: main.py는 FastAPI, uvicorn 같은 남이 만들어둔 도구들을 가져다 쓰고 있어요. requirements.txt에 그 도구 목록이 적혀 있고, 이 단계에서 그 도구들을 한 번에 설치해요. (레고 조립 전에 필요한 블록들을 상자에서 꺼내는 것과 비슷해요.)
어떻게 하나요:
bash
pip install -r requirements.txt결과물: 여러 줄의 설치 로그가 쭉 내려가다가 Successfully installed ...로 끝나면 성공이에요. (한 번은 몇 분 걸릴 수 있어요.)
5단계. Claude API 키 발급받기
이게 뭔가요: /predict 기능은 Anthropic이 만든 AI(Claude)에게 질문을 보내고 답을 받아옵니다. 이때 "이 요청은 당신 것이다"를 증명하는 열쇠(키)가 필요해요. 이 키는 비밀번호처럼 나만 알고 있어야 해요.
어떻게 하나요:
https://console.anthropic.com 접속 후 회원가입/로그인
왼쪽 메뉴에서 API Keys 클릭
"Create Key" 버튼 클릭 후 이름 아무거나 입력
생성된 키(문자열)를 복사 (한 번만 보여주니 꼭 복사해두기)
결과물: sk-ant-...로 시작하는 긴 문자열을 갖게 됩니다. (사용량만큼 과금되는 유료 서비스이니, 정확한 요금은 콘솔 사이트에서 확인하세요.)
6단계. 키를 .env 파일에 저장하기
이게 뭔가요: 방금 받은 키를 코드에 직접 적으면 위험해요 (남에게 파일을 공유하는 순간 키도 같이 넘어가니 까요). 그래서 .env라는 별도 파일에 저장하고, 코드는 이 파일을 몰래 읽어오게 만들어요.
어떻게 하나요:
bash
cp .env.example .env그다음 이 폴더에 생긴 .env 파일을 메모장이나 텍스트 편집기로 열어서, ANTHROPIC_API_KEY= 뒤에 5단계에서 복사한 키를 붙여넣고 저장합니다.
ANTHROPIC_API_KEY=sk-ant-실제로_복사한_키결과물: .env 파일 안에 본인 키가 한 줄로 저장되어 있는 상태. (이 파일은 .gitignore에 등록되어 있어서 깃허브에 실수로 올라가지 않아요.)
7단계. 서버 켜기
이게 뭔가요: 지금까지는 준비 단계였고, 이제 진짜로 main.py를 실행해서 컴퓨터가 요청을 기다리게 만드는 단계예요.
어떻게 하나요:
bash
uvicorn main:app --reload결과물: 터미널에 아래와 비슷한 줄이 뜨고, 커서가 멈춘 채로 대기합니다 (에러 없이 멈춰있는 게 정상이에요, 껐다는 뜻이 아니에요).
INFO: Uvicorn running on http://127.0.0.1:8000
INFO: Application startup complete.서버를 끄고 싶을 땐 이 터미널 창에서 Control + C.
8단계. 브라우저로 확인하기
이게 뭔가요: 서버가 잘 켜졌는지, 어떤 기능들이 있는지 눈으로 확인하는 화면이에요.
어떻게 하나요: 웹 브라우저를 열고 주소창에 아래를 입력
http://127.0.0.1:8000/docs결과물: "1주차 실습 API"라는 제목과 함께 /, /hello/{name}, /predict 세 개의 기능이 목록으로 보이는 화면(Swagger UI)이 뜹니다.
9단계. 실제로 API 테스트해보기
이게 뭔가요: 방금 본 화면에서 직접 버튼을 눌러 요청을 보내보는 단계예요.
어떻게 하나요:
/hello/{name}항목 클릭 → "Try it out" 클릭 → name 칸에 본인 이름 입력 → "Execute" 클릭/predict항목 클릭 → "Try it out" 클릭 → text 칸에 궁금한 질문 입력 → "Execute" 클릭
결과물: 화면 아래 "Response body"에 결과가 JSON 형태로 나타납니다.
/hello는{"greeting": "안녕하세요, 세진님!"}같은 인사말/predict는 입력한 질문에 대한 Claude의 실제 답변
여기까지 나오면 성공이에요. 나만의 AI 서버가 실제로 작동하고 있는 거예요.
자주 만나는 에러
command not found: python3→ 2단계에서 파이썬 미설치. python.org에서 설치.command not found: uvicorn→ 4단계 설치가 안 됐거나 실패함.pip install -r requirements.txt다시 실행.브라우저에서 "연결할 수 없음" → 7단계 터미널이 아직 켜져 있는지 확인 (Control+C로 꺼졌으면 다시
uvicorn main:app --reload)./predict응답이 "ANTHROPIC_API_KEY가 설정되어 있지 않아요" → 6단계를 다시 확인,.env파일 이름과 내용이 정확한지 확인.
결과와 배운 점
처음에는
"API를 실행한다"는 말 자체가 너무 어렵게 느껴졌습니다.
하지만 Claude가 '왜 하는지 → 어떻게 하는지 → 정상 결과는 무엇인지' 순서로 설명해 주니 훨씬 이해하기 쉬웠습니다.
특히 좋았던 점은 단순히 명령어를 알려주는 것이 아니라,
왜 Python이 필요한지
왜 .env를 사용하는지
왜 서버가 켜진 상태로 기다리는지
같은 배경까지 함께 설명해 준 점이었습니다.
덕분에 단순히 따라 하는 수준을 넘어 API 서버가 어떻게 실행되는지 전체 흐름을 이해할 수 있었습니다.
앞으로도 새로운 기술을 배울 때는
"전혀 모르는 사람이라고 생각하고 하나씩 설명해줘."
라는 방식으로 AI에게 요청하면 훨씬 빠르게 배우고 이해할 수 있겠다는 자신감도 생겼습니다.
