Gemini API 연결 방법
웹사이트에 인공지능 기능을 추가하고 싶으신가요? Gemini API 연결 방법을 알면 단순한 웹페이지를 사용자의 질문에 답하는 AI 웹사이트로 바꿀 수 있습니다.
이번 글에서는 Google AI Studio에서 API 키를 발급받고, Next.js로 만든 웹사이트에 Gemini를 연결하는 방법을 알아보겠습니다.
코딩을 처음 접하는 분도 따라 할 수 있도록 API 키 발급부터 Vercel 배포까지 단계별로 정리했습니다.
이번 글에서 완성할 기능
- 웹사이트에서 사용자가 질문을 입력합니다.
- 서버가 Gemini API에 질문을 전달합니다.
- Gemini가 생성한 답변을 웹페이지에 표시합니다.
- 로컬 컴퓨터와 인터넷에 공개된 사이트에서 모두 작동하는지 확인합니다.
1. Gemini API란 무엇인가?
Gemini API는 Google의 인공지능 모델을 외부 프로그램에서 사용할 수 있도록 제공하는 연결 통로입니다.
쉽게 말하면 웹사이트와 Gemini가 대화할 수 있도록 연결해 주는 창구입니다.
예를 들어 사용자가 웹사이트에 다음과 같이 입력했다고 가정해 보겠습니다.
사용자 질문
오늘 하루를 긍정적으로 시작할 수 있는 문장을 만들어 줘.
웹사이트는 이 질문을 서버로 전달합니다.
서버는 Gemini API를 통해 질문을 보내고, Gemini가 생성한 답변을 다시 웹사이트로 전달합니다.
이 과정은 다음과 같습니다.
사용자
질문 입력
↓
내 웹사이트
서버에 질문 전달
↓
Gemini API
인공지능 답변 생성
↓
내 웹사이트
답변을 화면에 표시
이처럼 API를 연결하면 별도의 인공지능 모델을 직접 개발하지 않아도 AI 기능을 웹사이트에 추가할 수 있습니다.
2. 실습용 스타터 프로젝트 준비하기
이번 실습에서는 화면이 미리 만들어진 프로젝트를 사용합니다.
화면을 처음부터 제작하는 대신, Gemini를 연결하는 부분에 집중할 수 있습니다.
① GitHub 스타터 저장소 열기
아래 주소를 열어 실습용 프로젝트를 확인합니다.
AI Mini App Starter GitHub 저장소
② 내 저장소 만들기
- GitHub에 로그인합니다.
- 저장소 오른쪽 위의 Use this template을 누릅니다.
- Create a new repository를 선택합니다.
- Repository name에
my-first-ai-app을 입력합니다. - 공개 범위는 Public을 선택합니다.
- Create repository를 눌러 저장소를 만듭니다.
이제 내 계정에 실습용 프로젝트가 복사됩니다.
③ 내 컴퓨터로 프로젝트 가져오기
안티그래비티에서 File → Open Folder를 선택합니다.
바탕화면에 my-first-ai-app이라는 새 폴더를 만들고 엽니다.
그다음 AI 도구에 다음 내용을 요청합니다.
복사용 프롬프트
이 폴더는 비어 있습니다. GitHub에 만든 내 저장소를 현재 폴더 안으로 받아 주세요. git clone 주소 . 명령을 사용해 주세요. 그다음 npm install을 실행해 필요한 패키지를 설치해 주세요. 작업이 끝나면 결과를 한국어로 설명해 주세요.
여기서 내 저장소 주소는 방금 만든 GitHub 저장소 주소로 바꿔야 합니다.
설치가 끝나면 왼쪽 파일 목록에서 app, lib, .env.example, .gitignore 파일을 확인합니다.
3. Google AI Studio에서 Gemini API 키 발급받기
Gemini API를 사용하려면 먼저 API 키가 필요합니다.
API 키는 내 웹사이트가 Google AI 서비스에 접근할 수 있도록 인증하는 비밀 열쇠입니다.
① Google AI Studio 접속
아래 공식 주소를 엽니다.
개인 Google 계정으로 로그인합니다.
② API 키 만들기
- Create API key 또는 API 키 만들기를 누릅니다.
- 프로젝트 선택 화면이 나오면 안내에 따라 프로젝트를 선택합니다.
- API 키가 생성되면 복사 아이콘을 누릅니다.
- 복사한 키를 다음 단계에서 사용할 수 있도록 준비합니다.
API 키 보안 주의사항
API 키는 비밀번호처럼 관리해야 합니다. 코드 파일이나 GitHub에 올리면 안 됩니다.
AI 채팅창, 카카오톡, 이메일, 캡처 화면에도 붙여 넣지 마세요.
③ 무료 사용 시 주의할 점
Gemini API에는 무료 사용 등급이 있습니다.
다만 모든 모델과 기능을 무제한으로 사용할 수 있는 것은 아닙니다. 모델별 요청 횟수와 사용량 제한이 적용됩니다.
무료 등급으로 전송한 콘텐츠는 Google 제품 개선에 사용될 수 있다고 안내되어 있습니다.
따라서 실습용 웹사이트에는 이름, 전화번호, 주소, 건강 정보 등 민감한 개인정보를 입력하지 않는 것이 좋습니다.
사용량과 요금은 변경될 수 있으므로 실제 사용 전 공식 요금표를 확인하세요.
4. .env 파일에 API 키 안전하게 보관하기
API 키를 발급받았다면 이제 내 컴퓨터에 안전하게 보관해야 합니다.
이때 사용하는 파일이 .env입니다.
.env는 API 키와 같은 민감한 정보를 소스 코드와 분리해서 보관하는 환경 변수 파일입니다.
① 먼저 .gitignore 확인하기
API 키를 입력하기 전에 반드시 .gitignore 파일부터 확인합니다.
파일 안에 다음 내용이 있는지 확인하세요.
.env*
!.env.example
첫 번째 줄은 .env로 시작하는 파일을 Git이 추적하지 않도록 합니다.
두 번째 줄은 예시 파일인 .env.example은 저장소에 포함할 수 있도록 예외 처리합니다.
② .env 파일 만들기
.env.example 파일을 복사해 같은 폴더에 .env라는 이름으로 저장합니다.
파일을 열어 다음 항목을 확인합니다.
GEMINI_API_KEY=여기에_본인_API_키
안내 문구를 지우고 복사한 실제 API 키를 붙여 넣습니다.
등호 앞뒤에 공백이나 불필요한 따옴표를 넣지 않습니다.
입력한 뒤 Ctrl + S를 눌러 저장합니다.
③ Git에서 .env가 제외되었는지 확인
터미널에서 다음 명령어를 실행합니다.
git status
변경 파일 목록에 .env가 나타나지 않아야 합니다.
.env.example은 보여도 괜찮습니다. 실제 API 키가 들어 있는 .env가 보이지 않는지 확인하는 것이 중요합니다.
중요한 보안 확인
이미 Git이 .env 파일을 추적하고 있었다면 .gitignore에 추가하는 것만으로는 충분하지 않습니다.
이 경우 커밋이나 푸시를 멈추고 추적 상태를 먼저 바로잡아야 합니다.
5. Gemini API를 웹사이트에 연결하기
이제 웹사이트와 Gemini를 실제로 연결할 차례입니다.
스타터 프로젝트에는 Gemini API를 호출할 파일이 준비되어 있습니다.
안티그래비티 왼쪽 파일 목록에서 다음 경로를 엽니다.
app/api/gemini/route.ts
파일 안에 있는 TODO 부분을 채우도록 AI에게 요청합니다.
Gemini 연결 복사용 프롬프트
이 route.ts 파일의 TODO 부분을 완성해 주세요.
- Google 공식 패키지 @google/genai를 사용해 주세요.
- 모델은 gemini-3.5-flash-lite를 사용해 주세요.
- 사용자가 입력한 prompt를 Gemini API에 전달해 주세요.
- 생성된 답변은 { text: '답변 내용' } 형식으로 NextResponse.json에 담아 반환해 주세요.
- API 키는 process.env.GEMINI_API_KEY에서 읽어 주세요.
- API 키를 코드에 직접 작성하지 마세요.
- API 키가 없거나 요청에 실패하면 적절한 HTTP 오류 상태와 메시지를 반환해 주세요.
- 서버에서만 API를 호출하고 브라우저에 API 키가 노출되지 않도록 해 주세요.
AI가 패키지를 설치하거나 파일을 수정하겠다고 요청하면 내용을 확인하고 진행합니다.
수정된 코드에서 확인할 부분
AI가 작업을 마쳤다면 다음 두 가지를 확인합니다.
@google/genai패키지를 사용하는지 확인합니다.process.env.GEMINI_API_KEY에서 API 키를 읽는지 확인합니다.
실제 API 키 문자열이 코드 안에 들어 있다면 해당 코드를 그대로 사용하지 마세요.
Gemini 모델은 변경될 수 있습니다. 모델을 찾을 수 없다는 오류가 나오면 Google 공식 모델 목록에서 현재 사용 가능한 모델명을 확인해야 합니다.
6. 내 컴퓨터에서 Gemini 연결 테스트하기
코드 수정이 끝났다면 먼저 인터넷에 공개하기 전에 내 컴퓨터에서 테스트합니다.
안티그래비티에 다음과 같이 요청합니다.
사이트를 실행해 주세요. npm run dev 명령을 사용하고, 브라우저에서 접속할 주소를 알려 주세요.
서버가 실행되면 보통 다음 주소가 표시됩니다.
http://localhost:3000
브라우저에서 안내된 주소를 엽니다.
스타터 화면에는 다음과 같은 AI 기능 카드가 준비되어 있습니다.
- AI 자기소개 도우미
- 내 마음 위로 받기
- 한 줄 일기 펼치기
- AI 명언 생성기
- 메일 문구 다듬기
카드 하나를 선택하고 간단한 질문을 입력합니다.
버튼을 눌렀을 때 Gemini가 생성한 답변이 화면에 나타나면 연결에 성공한 것입니다.
.env 파일을 수정했다면 서버 재시작
개발 서버는 실행할 때 환경 변수를 읽습니다.
따라서 API 키를 새로 입력하거나 변경했다면 기존 서버를 종료해야 합니다.
- 터미널에서 Ctrl + C를 누릅니다.
- 개발 서버를 다시 실행합니다.
- 브라우저를 새로 고침합니다.
- 질문을 입력해 다시 테스트합니다.
7. GitHub에 올리고 Vercel에 배포하기
내 컴퓨터에서 Gemini가 정상적으로 작동한다면 이제 인터넷에 공개할 차례입니다.
여기서 꼭 알아야 할 점이 있습니다.
Vercel은 GitHub에 올라간 코드만으로 내 컴퓨터의 .env 파일을 자동으로 가져오지 못합니다.
따라서 Vercel에도 API 키를 별도로 등록해야 합니다.
① GitHub에 코드 업로드
안티그래비티에 변경 내용을 커밋하고 GitHub로 푸시해 달라고 요청합니다.
지금까지 수정한 내용을 GitHub에 커밋하고 푸시해 주세요. 커밋 메시지는 '제미나이연결'로 해 주세요. 먼저 git status로 변경 파일을 보여 주고 .env가 포함되지 않았는지 확인해 주세요.
푸시하기 전에 변경 파일 목록에 .env가 없는지 다시 확인합니다.
GitHub 저장소를 열어 .env.example은 있지만 .env는 없는지 확인합니다.
② Vercel에서 프로젝트 가져오기
- Vercel 공식 사이트에 접속합니다.
- 대시보드에서 Add New를 선택합니다.
- Project를 선택합니다.
- GitHub에 올린
my-first-ai-app저장소를 찾습니다. - Import를 누릅니다.
③ 환경 변수 등록하기
프로젝트 설정 화면에서 Environment Variables 항목을 찾습니다.
다음과 같이 입력합니다.
Name
GEMINI_API_KEY
Value
Google AI Studio에서 발급받은 실제 API 키
이름은 반드시 GEMINI_API_KEY로 입력해야 합니다.
대소문자와 밑줄까지 정확하게 입력하세요.
Value에는 실제 API 키를 붙여 넣습니다.
등록이 끝나면 Deploy를 눌러 배포를 시작합니다.
④ 배포 완료 확인하기
배포 상태가 Ready로 바뀌면 Vercel이 제공하는 공개 주소를 엽니다.
로컬 테스트 때와 마찬가지로 질문을 입력하고 답변이 나오는지 확인합니다.
인터넷에 공개된 주소에서도 정상적으로 답변이 나오면 Gemini API 연결이 완료된 것입니다.
⑤ 환경 변수를 나중에 등록했다면 Redeploy
처음 배포할 때 API 키를 등록하지 않았다면 나중에 환경 변수를 추가할 수 있습니다.
다만 환경 변수 변경은 이미 완료된 기존 배포에 자동으로 적용되지 않습니다.
- Vercel 프로젝트에서 Settings를 엽니다.
- Environment Variables를 선택합니다.
GEMINI_API_KEY항목을 추가하거나 수정합니다.- Save를 누릅니다.
- Deployments 메뉴로 이동합니다.
- 최신 배포의 메뉴에서 Redeploy를 선택합니다.
- 새 배포가 Ready 상태가 되면 사이트를 다시 확인합니다.
기억해야 할 핵심
Vercel에 환경 변수를 새로 등록하거나 변경했다면 새 배포가 필요합니다. Redeploy를 완료해야 변경된 값이 적용됩니다.
8. Gemini API 연결 오류와 해결 방법
처음 API를 연결할 때는 오류가 발생할 수 있습니다.
오류 메시지를 확인하고 아래 순서대로 점검하면 대부분의 문제를 찾을 수 있습니다.
① 내 컴퓨터에서는 되지만 공개 사이트에서 오류가 발생하는 경우
Vercel에 API 키가 등록되지 않았거나 새 배포가 적용되지 않았을 가능성이 있습니다.
- Vercel Settings에서 환경 변수를 확인합니다.
GEMINI_API_KEY이름이 정확한지 확인합니다.- 값이 정상적으로 저장되었는지 확인합니다.
- Redeploy를 실행합니다.
② 404 또는 모델을 찾을 수 없다는 오류
코드에 입력한 모델명이 잘못되었거나 더 이상 제공되지 않는 모델일 수 있습니다.
Google 공식 모델 목록에서 현재 사용할 수 있는 모델명을 확인한 뒤 코드의 모델명을 수정합니다.
③ 429 또는 quota 오류
무료 등급의 요청 횟수나 사용량 한도에 도달했을 수 있습니다.
잠시 기다린 후 다시 요청하거나 Google AI Studio의 사용량 제한을 확인합니다.
④ API 키 인증 오류
API 키가 잘못 입력되었거나 삭제·폐기된 경우 발생할 수 있습니다.
- Google AI Studio에서 키가 유효한지 확인합니다.
.env의 키 값에 공백이 들어갔는지 확인합니다.- Vercel의 환경 변수 값도 확인합니다.
- 키를 새로 발급했다면 로컬 서버를 재시작하고 Vercel도 Redeploy합니다.
⑤ 아직 Gemini API가 연결되지 않았다는 메시지
스타터 프로젝트의 TODO 부분이 아직 수정되지 않았을 수 있습니다.
app/api/gemini/route.ts 파일을 다시 확인하고 Gemini 연결 작업이 완료되었는지 확인합니다.
9. API 키가 노출되었다면 어떻게 해야 할까?
API 키가 GitHub나 채팅창에 공개되었다면 단순히 파일에서 지우는 것으로 끝내면 안 됩니다.
다른 사람이 이미 키를 복사했을 가능성이 있기 때문입니다.
다음 순서로 조치하는 것이 안전합니다.
- Google AI Studio에서 노출된 API 키를 삭제하거나 폐기합니다.
- 새 API 키를 발급받습니다.
- 내 컴퓨터의
.env에 새 키를 입력합니다. - Vercel의
GEMINI_API_KEY값도 교체합니다. - Vercel에서 Redeploy를 실행합니다.
- GitHub 커밋 기록에 키가 남아 있다면 저장소 기록에서도 제거 조치를 합니다.
API 키는 코드에 직접 넣지 마세요.
브라우저에서 실행되는 코드에 API 키를 넣으면 방문자가 개발자 도구 등을 통해 키를 확인할 수 있습니다.
서버에서 API를 호출하고 비밀 키는 환경 변수로 관리해야 합니다.
10. Gemini API 연결 과정 정리
이번 실습에서 진행한 내용을 간단히 정리해 보겠습니다.
- GitHub 스타터 프로젝트를 내 저장소로 복사합니다.
- 내 컴퓨터에 프로젝트를 내려받습니다.
- Google AI Studio에서 Gemini API 키를 발급받습니다.
.gitignore를 확인한 뒤.env파일을 만듭니다.GEMINI_API_KEY에 실제 키를 입력합니다.route.ts파일의 TODO 부분을 완성합니다.- 로컬 웹사이트에서 Gemini 답변을 테스트합니다.
- API 키가 제외된 코드만 GitHub에 업로드합니다.
- Vercel에 환경 변수를 등록합니다.
- 배포 후 공개 사이트에서 다시 테스트합니다.
이제 단순히 정해진 글자만 보여 주는 웹페이지가 아니라, 사용자의 질문에 따라 답변을 생성하는 AI 웹사이트를 만들 수 있습니다.
마무리: 내 웹사이트에 AI 기능 추가하기
Gemini API를 연결하는 과정에서 가장 중요한 것은 API 키를 안전하게 관리하는 것입니다.
내 컴퓨터에서는 .env 파일에 보관하고, Vercel에서는 환경 변수로 등록합니다.
그리고 GitHub에는 실제 API 키가 포함된 파일을 올리지 않아야 합니다.
이번 과정을 완료했다면 AI 자기소개 도우미, 일기 작성 도우미, 문장 다듬기 등 다양한 기능을 직접 확장할 수 있습니다.
먼저 간단한 질문과 답변 기능부터 완성해 보세요. 작은 기능 하나를 직접 연결해 보는 것이 AI 웹서비스 개발의 좋은 출발점입니다.
댓글 없음:
댓글 쓰기