왕초보를 위한 API 만들기 실행 가이드 진행한 후기

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 파일을 사용하는 이유

  • 서버가 켜진 상태가 왜 정상인지

까지 하나씩 설명해 주었습니다.

덕분에 단순히 따라 하는 것이 아니라 왜 이 과정을 하는지 이해하면서 진행할 수 있었습니다.

실제로 진행한 순서는 다음과 같았습니다.

  1. 터미널 실행

  2. Python 설치 확인

  3. 프로젝트 폴더 이동

  4. requirements.txt 설치

  5. Claude API Key 발급

  6. .env 설정

  7. uvicorn으로 서버 실행

  8. Swagger(/docs) 접속

  9. /hello, /predict API 테스트

마지막에는 자주 발생하는 오류와 해결 방법까지 정리되어 있어서 막히는 부분도 스스로 해결할 수 있었습니다.

결과물

왕초보를 위한 실행 가이드

이 폴더 안의 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)에게 질문을 보내고 답을 받아옵니다. 이때 "이 요청은 당신 것이다"를 증명하는 열쇠(키)가 필요해요. 이 키는 비밀번호처럼 나만 알고 있어야 해요.

어떻게 하나요:

  1. https://console.anthropic.com 접속 후 회원가입/로그인

  2. 왼쪽 메뉴에서 API Keys 클릭

  3. "Create Key" 버튼 클릭 후 이름 아무거나 입력

  4. 생성된 키(문자열)를 복사 (한 번만 보여주니 꼭 복사해두기)

결과물: 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 테스트해보기

이게 뭔가요: 방금 본 화면에서 직접 버튼을 눌러 요청을 보내보는 단계예요.

어떻게 하나요:

  1. /hello/{name} 항목 클릭 → "Try it out" 클릭 → name 칸에 본인 이름 입력 → "Execute" 클릭

  2. /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에게 요청하면 훨씬 빠르게 배우고 이해할 수 있겠다는 자신감도 생겼습니다.

2
2개의 답글
밀어주고 끌어주는

온·오프라인 AI 스터디

AI로 어디까지 할 수 있는지
직접 확인하실 분만 신청하세요.