AI API 연결하기
내가 만든 웹사이트에 AI 기능을 붙이는 방법입니다. Claude, OpenAI(GPT), Google Gemini — 세 가지 AI를 연결하는 법을 다룹니다. 코딩 경험이 없어도 Claude Code가 대신 해줍니다.
이 페이지, 다 따라 하는 것 아닙니다
API란 무엇인가
내 웹사이트에 AI를 연결하는 원리
API가 뭔가요?
API는 “내 프로그램에서 다른 서비스의 기능을 빌려 쓰는 통로”입니다.
예를 들어, 내가 만든 웹사이트에서 “이 글을 요약해줘” 버튼을 누르면 뒤에서 Claude나 GPT에게 요청을 보내고, 결과를 받아서 화면에 보여주는 겁니다.
이때 필요한 것이 API 키— AI 서비스에 접속하기 위한 비밀번호입니다. (API는 “Application Programming Interface”의 줄임말로, 프로그램끼리 데이터를 주고받는 통로를 뜻합니다.)
흐름 한눈에 보기
세 가지 AI 비교
 Claude |  GPT |  Gemini | |
|---|---|---|---|
| 무료 사용 | 없음 (카드 필수) | 없음 (충전 필수) | 무료 가능! |
| 가장 싼 모델 | Haiku (입력 $1/1M) | GPT-5 nano (입력 $0.05/1M) | Flash 계열 (무료 티어 있음) |
| API 키 발급 | platform.claude.com | platform.openai.com | aistudio.google.com |
| 설치 패키지 이름 | @anthropic-ai/sdk | openai | @google/genai |
| API 키 저장 이름 | ANTHROPIC_API_KEY | OPENAI_API_KEY | GEMINI_API_KEY |
| 프로토타입 추천 | 3순위 | 2순위 | 1순위 (무료!) |
가격의 “1M”은 100만 토큰. 토큰은 AI가 글을 세는 단위로, 한글 한 글자가 대략 1~2토큰입니다. A4 수백 장 분량을 보내야 1달러 안팎이라, 연습 단계에서는 사실상 무시해도 되는 금액이에요.
Claude (Anthropic)
오늘 쓰고 있는 바로 그 AI — 충전 후 사용
Claude (Anthropic)
오늘 쓰고 있는 바로 그 AI — 충전 후 사용
로그인 후 개인(Personal) 선택
platform.claude.com(예전 console.anthropic.com)에 접속해서 계정을 만들고 로그인하세요. 조직 선택 화면이 나오면 Personal을 선택합니다.
자금 추가(Add Funds) 및 결제하기
Settings → Billing에서 결제 수단을 등록하고 크레딧을 충전하세요. 최소 $5부터 가능합니다. 월간 한도(Settings → Limits)도 따로 설정할 수 있어요.
월 사용 한도 걸어두기
API Key 생성하기
왼쪽 사이드바에서 API Keys → Create Key를 누르세요. 이름은 알아보기 쉽게 지으면 됩니다 (예: “my-first-app”).
Key 복사하기
생성된 키를 즉시 복사하세요. 이 창을 닫으면 다시 볼 수 없습니다!sk-ant-api03-... 형태입니다.
.env.local 템플릿 만들기
먼저 Claude에게 빈 틀을 만들어달라고 하세요:
.env.local 파일을 만들어줘. ANTHROPIC_API_KEY 자리만 비워둬. .gitignore에도 추가해줘
Claude가 이런 파일을 만들어줍니다:
# .env.local
ANTHROPIC_API_KEY=여기에_키_붙여넣기편집기에서 직접 키 붙여넣기
API 키는 채팅으로 주지 말고 직접 파일에 넣는 게 안전해요. Claude에게 파일을 열어달라고 하세요:
.env.local 파일을 메모장(Mac은 텍스트 편집기)으로 열어줘
편집 창이 열리면 여기에_키_붙여넣기 부분을 아까 복사한 진짜 키로 바꾸고 저장(Cmd+S, Windows는 Ctrl+S)하세요.
.env.local은 내 컴퓨터에만 있는 비밀 파일이에요. GitHub에 올라가지 않으니 키가 외부에 노출되지 않습니다.Claude Code에게 AI 기능 연결 시키기
키 저장이 끝났으면, 실제 AI 기능을 붙여달라고 하세요:
이 프로젝트에 Claude API를 연결해줘. ANTHROPIC_API_KEY는 이미 .env.local에 있어. /api/chat 주소를 만들어서 사용자가 텍스트를 보내면 AI가 한국어로 답하게 해줘. 모델은 claude-haiku-4-5로
필요한 도구 설치부터 연결 코드까지 Claude Code가 전부 만들어줍니다 — 위 프롬프트의 /api/chat 주소도 이때 생겨요.
Vercel에 배포할 때도 키를 꼭 넣어야 해요!
.env.local은 내 컴퓨터에만 있어요. Vercel 서버는 이 파일을 모르기 때문에, “아까는 됐는데 배포하니까 안 되는” 문제가 생기면 거의 이게 원인이에요.
Vercel 환경변수에 ANTHROPIC_API_KEY 등록해줘. 끝나면 재배포까지 해줘
직접 넣는 법(GUI)·AI에게 시키는 법·“넣었다는데 안 될 때”(줄바꿈 함정)까지 단계별로는 환경변수 페이지에서 자세히 볼 수 있어요.
Gemini + OpenAI
무료 또는 유료 — 다른 AI도 연결하기
Google Gemini
무료로 시작 가능 — 프로토타입에 가장 추천
API 키 발급받기
- 1aistudio.google.com에 접속 → Google 계정으로 로그인
- 2왼쪽 사이드바에서 Get API Key 클릭
- 3Create API Key → 프로젝트 이름 입력 (예: “my-app”) → Create
- 4생성된 키를 복사해서 안전한 곳에 저장
무료 사용 한도
무료 티어는 “분당 몇 회 / 하루 몇 회” 식으로 요청 횟수에 제한이 있습니다. 구체적인 숫자는 모델과 시기에 따라 바뀌니 발급 페이지(aistudio.google.com)에서 현재 기준을 확인하세요.
혼자 눌러보며 테스트하는 프로토타입 단계에는 대체로 충분한 양입니다.
Claude Code에게 연결 시키기
API 키를 받았으면, Claude Code에 이렇게 말하세요:
“이 프로젝트에 Google Gemini API를 연결해줘. API 키는 GEMINI_API_KEY 이름으로 비밀 파일에 저장해서 관리하고, /api/chat 주소를 만들어서 사용자가 텍스트를 보내면 AI가 답변하게 해줘. 모델은 지금 무료로 쓸 수 있는 Flash 계열 최신 모델로 골라줘”
Claude Code가 도구 설치, 비밀 파일 설정, AI 연결 코드 생성까지 전부 해줍니다.
OpenAI (GPT)
가장 유명한 AI — 충전 후 사용
API 키 발급받기
- 1platform.openai.com에 접속 → 계정 생성 또는 로그인
- 2왼쪽 사이드바 → API Keys 클릭
- 3Create new secret key → 이름 입력 → 권한은 All 선택 → Create (연습용 키라 간단히 가는 선택이에요 — 실서비스용 키는 필요한 권한만 주는 게 원칙)
- 4키를 즉시 복사 — 창을 닫으면 다시 볼 수 없습니다!
- 5Billing에서 크레딧 충전 (최소 $5부터)
Claude Code에게 연결 시키기
보안과 실전
API 키 보호, 활용 예시, 자주 만나는 에러
API 키, 안전하게 다루기
방금 API 키를 발급받아 .env.local에 넣었죠. 키는 “돈이 청구되는 비밀번호”라 다루는 법이 중요한데, 다행히 기억할 건 딱 세 가지예요:
키는 .env.local에만. 코드에 직접 적지 않아요. (이미 그렇게 했어요 👍)
AI 호출은 서버에서만. app/api/ 폴더 안 — Claude Code가 알아서 여기에 만들어줘요.
서비스 콘솔에서 월 사용 한도 설정. 혹시 키가 새도 피해가 한도까지만.
왜 이렇게 하는지(집 열쇠 비유·F12 노출 시연), 배포 전 체크리스트, 키가 유출됐을 때 4단계 대응까지 — 전체 보안 가이드는 보안 페이지에 정리해뒀어요.
보낸 데이터는 어디로 가나요?
API로 보낸 글·이미지는 그 AI 회사의 서버에서 처리됩니다. 유료 API는 입력을 모델 학습에 쓰지 않는 것이 기본인 경우가 많지만, 무료 티어는 “서비스 개선에 활용될 수 있다”는 조건이 붙기도 해요 — 특히 무료 Gemini가 그렇습니다.
학생 작업물이나 연구 자료처럼 민감한 것을 다룰 계획이라면: ① 그 서비스의 데이터 정책 페이지를 한 번 확인하고 ② 연습은 무료로 하더라도 실제 운영은 유료 티어로, ③ 실명 같은 개인정보는 빼고 보내는 걸 원칙으로 하세요.
실전 활용 예시
AI API를 연결하면 이런 기능을 내 웹사이트에 넣을 수 있습니다. Claude Code에게 아래처럼 말하면 됩니다:
텍스트 요약
“텍스트를 입력하면 AI가 3줄로 요약해주는 기능 만들어줘”
챗봇
“화면 오른쪽 하단에 채팅 위젯을 추가해줘. 우리 서비스 FAQ를 학습시켜서 고객 질문에 답하게 해줘”
번역
“입력한 텍스트를 영어/일본어/중국어로 동시 번역해주는 기능 만들어줘”
콘텐츠 분석
“CSV 파일을 업로드하면 AI가 데이터를 분석하고 인사이트를 보여주는 페이지 만들어줘”
이미지 분석
“사진을 업로드하면 AI가 사진 속 내용을 설명해주는 기능 만들어줘. 이미지 이해(Vision) 기능 써줘”
이미지 평가 — 기준을 정해서
“이미지를 업로드하면 AI가 평가해주는 기능 만들어줘. 평가 기준은 criteria.md 파일에 적어둘 테니 그 기준대로, 잘한 점·아쉬운 점·제안 순서로 답하게 해줘”
단순 설명과 평가의 차이는 “기준”입니다. 기준을 파일로 적어두면 — 스킬 만들기에서 배우는 것처럼 — 내 감각이 도구가 됩니다.
자주 만나는 에러
401 Unauthorized
API 키가 틀렸거나, .env 파일에 키가 제대로 들어가지 않았을 때. 키를 다시 복사해서 붙여넣으세요.
429 Too Many Requests
요청 한도를 초과했거나 크레딧이 부족할 때. 잠시 기다리거나 크레딧을 충전하세요.
GEMINI_API_KEY is not defined
.env.local 파일이 없거나 변수명이 틀렸을 때. 파일 이름과 변수명을 다시 확인하세요.
AI 말고도 붙일 수 있어요 — 주소 찾기 · 날씨
API는 다른 서비스의 기능을 빌려 쓰는 통로라고 했죠. AI가 아니어도 빌릴 수 있는 기능이 많아요.
그중 제일 쉬운 두 가지는 키도, 가입도 필요 없어요. 쇼핑몰 주문서의 주소 찾기와 첫 화면의 날씨 위젯입니다.
| 서비스 | 키 필요? | 무료 조건 | 난이도 |
|---|---|---|---|
| 카카오(다음) 우편번호 | 필요 없음 | 상업용 포함 무료, 사용량 제한 없음 | 쉬움 |
| 행안부 도로명주소 API | 승인키 신청 필요 | 무료 | 보통 (키를 숨겨야 해요) |
| Open-Meteo 날씨 | 필요 없음 | 비상업용 무료 (하루 1만 회 미만) | 쉬움 |
| 기상청 단기예보 (공공데이터포털) | 인증키 필요 (활용신청) | 무료, 출처 표시 필요 | 어려움 (격자 좌표) |
표가 옆으로 길면 좌우로 밀어서 볼 수 있어요. 2026년 10월에 공식 문서로 확인한 내용이에요.
주소 찾기 — 카카오(다음) 우편번호 서비스
버튼 하나로 우편번호·도로명 주소 검색 팝업
“주소 찾기” 버튼을 누르면 검색창이 뜨고, 주소를 고르면 우편번호와 주소가 칸에 자동으로 들어가요. 배송지를 받는 사이트라면 거의 다 이 방식이에요.
- 공식 안내에 “Key를 발급 받을 필요가 없습니다”라고 적혀 있어요. 가입도 없어요.
- 기업용·상업용도 무료이고, 사용량 제한도 없다고 해요.
- 팝업 아래쪽 카카오 로고를 가리거나 스크립트를 마음대로 고치면 제한이 생길 수 있어요.
내 사이트 주문 폼에 '주소 찾기' 버튼을 넣어줘. 다음(카카오) 우편번호 서비스를 써서, 주소를 고르면 우편번호와 주소 칸이 자동으로 채워지게 하고, 상세주소 칸은 직접 입력하게 해줘.
배송지 입력
우편번호
주소
상세주소
공공기관 쪽 대안: 행정안전부 도로명주소 API
날씨 — Open-Meteo
위도·경도만 알려주면 현재 기온과 예보를 줘요
서울이면 위도 37.57, 경도 126.98처럼 “좌표”만 넘기면 지금 기온, 날씨 코드(맑음·비·눈 등), 며칠치 예보가 돌아와요. 한국 어디든 좌표로 찾을 수 있어요.
- API 키가 필요 없어요. 공식 문서에 키는 상업용에서만 필요하다고 적혀 있어요.
- 무료는 비상업용이에요. 개인·비영리 사이트처럼 구독이나 광고가 없는 곳이 해당돼요.
- 무료 한도는 하루 1만 회 미만, 시간당 5천 회, 분당 600회예요.
- 광고·구독이 있는 사이트나 상품에 넣으려면 유료 플랜(키 발급)이 필요해요.
내 사이트 첫 화면에 서울 현재 기온과 오늘 날씨를 보여주는 작은 위젯을 넣어줘. Open-Meteo API를 써줘(키 필요 없음). 날씨 코드에 맞는 아이콘도 붙여줘.
18°
맑음
오늘 최저 13° · 최고 20°
한국 공식 대안: 기상청 단기예보 API
핵심 URL 모음
| Gemini 키 발급 | aistudio.google.com |
| Gemini 문서 | ai.google.dev/docs |
| OpenAI 키 발급 | platform.openai.com |
| OpenAI 문서 | platform.openai.com/docs |
| Claude 키 발급 | platform.claude.com |
| Claude 문서 | platform.claude.com/docs |
| 우편번호 안내 (키 없음) | postcode.map.kakao.com/guide |
| 날씨 (키 없음) | open-meteo.com/en/docs |