제미나이 API 시작하기｜키 발급·무료 한도·첫 호출

자신만의 웹 서비스, 모바일 앱, 사내 자동화 프로그램이나 챗봇에 구글 제미나이(Gemini)의 고성능 언어 및 멀티모달 모델을 탑재하고자 하는 개발자라면 공식 개발자 포털인 Google AI Studio를 통해 API 키를 발급받아야 합니다. 제미나이 API는 복잡한 서버 인프라 구축 없이 몇 줄의 코드만으로 텍스트 생성, 문서 요약, 이미지 분석, 코드 작성을 연동할 수 있도록 지원합니다. 본 가이드에서는 일반 제미나이 웹 앱과 API의 핵심 차이점부터 안전한 공식 키 발급 절차, 첫 요청 실습 예시, 무료 할당량 정책 및 키 보안 수칙을 정리해 드립니다.

제미나이 API를 안전하게 시작하기 위한 3대 핵심 수칙은 다음과 같습니다.

• 과금 체계 분리 인지: 일반 제미나이 웹 앱 구독(Google One)과 개발자용 Gemini API는 완전히 별개의 과금 및 할당량 체계로 운영됩니다.
• 공식 발급 포털(Google AI Studio) 이용: aistudio.google.com에서 개인 또는 회사 구글 계정으로 로그인하여 정식 API 키를 생성합니다.
• API 키 유출 방지 및 보안: 발급받은 키는 프론트엔드 코드나 GitHub 공개 저장소에 직접 노출하지 않고 반드시 백엔드 환경 변수(.env)로 관리합니다.

앱과 API 차이

일반 사용자가 브라우저에서 접속하는 Gemini 웹 앱과 개발자가 코드로 호출하는 Gemini API는 목적과 요금 체계에서 큰 차이가 있습니다.

Google One AI 프리미엄 요금제를 결제했다고 해서 개발자 API 호출이 무제한 무료로 제공되는 것이 아니므로, 자체 개발 프로젝트에는 API 전용 할당량과 결제 프로젝트를 별도로 관리해야 합니다.

프로그래밍 및 코드 작성에 제미나이를 활용하는 기본 팁은 제미나이 코딩 사용법을 함께 참고하세요.

키 발급

Google AI Studio에서 API 키를 만들 수 있지만, 무료 티어 제공 여부와 결제 설정 요구는 계정·지역·프로젝트에 따라 달라질 수 있습니다. (2026-08-21 기준 공식 개발자 화면 기준입니다.)

API 키 발급 5단계 순서

1. Google AI Studio 접속: 웹 브라우저에서 https://aistudio.google.com으로 이동합니다.
2. 구글 계정 로그인: API를 관리할 구글 계정으로 로그인하고 이용 약관에 동의합니다.
3. API 키 관리 화면 찾기: [Get API key] 또는 [API keys]에 해당하는 메뉴를 찾습니다. 명칭과 위치는 화면 개편에 따라 달라질 수 있습니다.
4. 새 API 키 생성: 생성 항목을 선택하고 화면에서 요구하는 Google Cloud 프로젝트 연결 절차를 따릅니다.
5. 발급된 키 복사 및 안전 보관: 생성된 긴 문자열 형태의 API 키(AIzaSy...)를 복사하여 안전한 메모장이나 비밀번호 관리자에 임시 보관합니다. (키 문자열은 타인에게 절대 보여주지 마세요.)

기본적인 인터페이스 조작과 입력창 위치는 제미나이 사용방법에서 기초부터 확인하실 수 있습니다.

첫 요청

발급받은 키가 정상적으로 동작하는지 확인하기 위해 가장 널리 쓰이는 cURL 명령어와 Python 코드로 첫 테스트 요청을 보내는 방법입니다. (코드 속 API 키 부분은 본인의 실제 발급 키로 대체해야 합니다.)

1. REST 요청으로 연결 확인

공식 API 문서의 generateContent 예제를 기준으로 요청 URL의 MODEL_NAME을 현재 지원되는 모델명으로 바꾸고, API 키는 소스에 직접 적지 말고 환경 변수에서 불러오세요. 요청 헤더에는 JSON 콘텐츠 형식을 지정하고 본문의 contents와 parts에 짧은 테스트 질문을 넣습니다.

2. 공식 SDK로 첫 요청 보내기

Python 또는 JavaScript용 최신 공식 SDK와 초기화 방식은 Google AI for Developers 문서에서 확인하세요. SDK 이름과 메서드는 버전에 따라 바뀔 수 있으므로 오래된 블로그 예제를 그대로 복사하지 말고, 설치한 버전과 공식 빠른 시작 예제를 맞춘 뒤 GEMINI_API_KEY 환경 변수를 사용합니다.

첫 요청은 "연결 성공 여부를 한 줄로 답해 줘"처럼 짧게 보내고, 응답 본문 또는 오류 코드를 확인한 다음 실제 기능을 개발하는 순서가 안전합니다.

무료·유료 한도

Google AI Studio는 개발자가 아이디어를 빠르게 프로토타이핑할 수 있도록 관대한 무료 등급(Free Tier)을 제공합니다. 다만 상용 서비스 배포 시에는 유료 플랜(Pay-as-you-go) 전환을 고려해야 합니다.

무료 티어 vs 유료 종량제 비교

• 무료 티어 (Free Tier)
• 비용: 지원되는 모델과 지역에서는 무료 티어가 제공될 수 있으며, 현재 가격표와 프로젝트 결제 상태를 확인해야 함
• 속도 제한: 모델·프로젝트·서비스 등급별 RPM·TPM·일일 한도가 다르므로 공식 rate limits 화면에서 현재 값 확인
• 데이터 정책: 무료 티어에서 입력된 데이터는 구글의 모델 성능 개선 및 품질 검토에 활용될 수 있음
• 유료 종량제 (Pay-as-you-go Tier)
• 비용: 모델과 입력·출력 유형별 단가가 다르므로 호출 전 공식 가격표 확인
• 속도 제한: 유료 등급에서도 모델·프로젝트별 제한이 적용되므로 현재 할당량 확인
• 데이터 정책: 데이터 사용 조건은 선택한 서비스와 현재 약관을 확인하고 민감정보 전송을 최소화

키 보안

API 키는 금융 계좌의 비밀번호와 같습니다. 키가 외부에 유출되면 타인이 내 할당량을 고갈시키거나 유료 결제 계정의 경우 막대한 요금 폭탄을 유발할 수 있습니다.

필수 보안 수칙 4가지

1. 환경 변수 파일(`.env`) 사용: 코드 내부에 키를 직접 하드코딩하지 않고 .env 파일에 저장한 후 os.environ 또는 dotenv 라이브러리로 불러옵니다.
2. `.gitignore`에 등록: Git 저장소를 사용할 때 .env 파일이 GitHub 등 공개 저장소에 푸시되지 않도록 .gitignore 파일에 반드시 .env를 추가합니다.
3. 클라이언트 사이드 노출 금지: 리액트(React), 뷰(Vue), 일반 웹페이지 HTML/자바스크립트 등 브라우저 소스코드에서 API를 직접 호출하지 말고, 반드시 백엔드 API 서버를 거쳐 호출하도록 중계합니다.
4. Google Cloud 콘솔에서 예산 알림 설정: 결제를 연결했다면 예산과 알림 기준을 업무 상황에 맞게 설정합니다. 예산 알림은 비용 자체를 자동 차단하는 기능과 다를 수 있으므로 별도의 할당량 제한도 확인하세요.

오류 해결

API 호출 시 가장 자주 발생하는 HTTP 에러 코드와 해결 방법입니다.

서버 네트워크 및 방화벽 환경에 대한 추가적인 트러블슈팅은 제미나이 오류 해결 문서를 참고하시기 바랍니다.