Gemini API 연동 방법은 Google AI Studio에서 키를 받고 Python이나 자바스크립트 SDK 또는 REST로 첫 요청을 보내는 과정입니다. 인증은 API 키로 이뤄지며 한도와 사용량 추적에도 같은 키가 쓰입니다. 이 글은 발급부터 호출, 할당량 오류 대응까지 실제 연동 순서를 안내합니다. 신규 키는 auth key 유형입니다.
클라이언트는 GEMINI_API_KEY 또는 GOOGLE_API_KEY 환경 변수를 자동으로 읽습니다. 둘 다 있으면 GOOGLE_API_KEY가 우선합니다. REST는 x-goog-api-key 헤더로 키를 넘깁니다. 키를 소스에 넣지 않는 습관이 보안의 출발점입니다.
Gemini API란 무엇이고 언제 쓰나
Gemini API는 Google의 생성형 모델을 HTTP와 공식 SDK로 호출하는 인터페이스입니다. 챗 앱, 문서 요약, 코드 보조, 이미지 설명처럼 모델 응답이 필요한 서비스에 씁니다. 브라우저 챗과 달리 키, 한도, 재시도, 로깅을 서비스 코드에서 직접 다룹니다.
공식 SDK는 Python의 google-genai와 JavaScript의 @google/genai입니다. pip install -U google-genai 후 genai.Client, npm install @google/genai 후 GoogleGenAI로 초기화합니다. REST도 같은 Interactions API를 제공합니다. REST 경로도 같은 제품군입니다.
API 키 발급과 프로젝트 준비
(출처: AI어떡환)
Gemini API 요청에는 인증용 API 키가 필요합니다. Google AI Studio는 신규 사용자에게 프로젝트와 키를 자동 생성합니다. API keys 페이지의 Create API key로 추가 발급할 수 있습니다. 키는 요청 인증과 한도 적용, 사용량 추적에 쓰입니다.
AI Studio에서 새로 만드는 키는 모두 auth key입니다. Key Type이 Standard인 키는 API Keys 페이지에서 새 auth key로 교체한 뒤 옛 키를 폐기하라고 안내합니다. 프로젝트 선택이 할당량 단위이므로 키만 여러 개 만들어도 한도는 프로젝트에 묶입니다. 키 이름과 생성 시각을 기록해 두면 교체 때 혼선이 줄어듭니다.
키 제한 화면에서 API를 제한할 수 있습니다. 생성 언어 API만 열어 두면 오용 범위가 줄어듭니다.
Python·자바스크립트로 첫 연동하기
Python과 자바스크립트는 공식 클라이언트가 환경 변수의 키를 읽어 Client를 만듭니다. 둘 다 있으면 GOOGLE_API_KEY가 우선하므로 배포 환경의 변수 이름을 먼저 확인합니다. REST를 쓸 때는 같은 키를 헤더로 직접 붙입니다. 설치 버전은 -U로 올려 예제와 맞춰 둡니다.
초기화 뒤에는 모델 이름과 입력 텍스트를 정해 상호작용 요청을 보냅니다. SDK는 HTTP 세부 사항을 감추고 REST는 엔드포인트와 JSON 본문을 직접 구성합니다. 첫 연동은 텍스트 한 건이 성공하는지만 보면 됩니다. 모델 식별자는 콘솔의 사용 가능 목록과 맞춰야 404를 피할 수 있습니다.
텍스트 생성 요청 보내기
텍스트 생성은 모델에 프롬프트를 넣고 응답 텍스트를 받는 기본 호출입니다. Python이면 google-genai의 genai.Client로 요청을 만들고 자바스크립트면 GoogleGenAI 인스턴스로 같은 흐름을 탑니다. 응답 객체에서 텍스트 필드만 먼저 확인하면 연동이 맞는지 바로 알 수 있습니다.
REST는 POST https://generativelanguage.googleapis.com/v1beta/interactions 에 JSON을 보냅니다. Content-Type은 application/json이고 키는 x-goog-api-key 헤더에 넣습니다. 상태 코드가 200이면 본문의 생성 결과를 파싱하면 됩니다.
스트리밍·멀티모달 호출 차이
스트리밍은 토큰이 나오는 대로 클라이언트가 받는 방식입니다. 전체 JSON이 끝날 때까지 기다리지 않아 채팅 UI에서 체감 지연이 줄어듭니다. 연결이 끊기면 부분 응답만 남을 수 있어 재연결과 타임아웃을 같이 설계해야 합니다. 스트리밍 응답은 이벤트 단위로 오므로 버퍼에 이어 붙여 화면을 갱신합니다.
멀티모달 호출은 텍스트와 함께 이미지 같은 입력을 실어 보냅니다. 본문 필드와 MIME 타입이 텍스트 전용 요청과 다르므로 샘플 JSON을 그대로 복사하기보다 필드 이름을 확인합니다. 할당량은 토큰 기준으로도 집계되므로 이미지가 붙으면 TPM에 더 빨리 닿을 수 있습니다. 텍스트만 보낼 때는 이미지 필드를 비웁니다.
호출 오류·할당량·보안 점검 포인트
할당량은 API 키가 아니라 프로젝트 단위입니다. 분당 요청 RPM, 분당 토큰 TPM, 일일 요청 RPD를 넘기면 오류가 납니다. RPD는 태평양 자정에 리셋됩니다. 어느 한도든 초과하면 rate limit 오류로 처리됩니다.
할당량 초과 시 HTTP 429 RESOURCE_EXHAUSTED가 반환됩니다. 429와 503 같은 일시 오류는 지수 백오프 재시도가 권장됩니다. 잘못된 키나 권한 문제인 400과 403은 재시도하지 않습니다. 같은 프로젝트의 여러 키가 한도를 나눠 쓰므로 키를 늘려도 RPM이 늘지는 않습니다.
로그에 어떤 한도인지 구분이 안 되면 RPM과 TPM, RPD를 각각 의심합니다. 재시도 간격은 짧게 반복하지 말고 지수적으로 늘립니다.
| 상태 코드 | 원인 | 대응 |
|---|---|---|
| 429 RESOURCE_EXHAUSTED | RPM·TPM·RPD·지출 한도 초과 | 지수 백오프 재시도 |
| 503 | 일시적 서비스 오류 | 지수 백오프 재시도 |
| 400·403 | 잘못된 키 또는 권한 문제 | 재시도하지 않고 설정 수정 |
키를 코드에 넣지 않는 방법
클라이언트 라이브러리는 GEMINI_API_KEY 또는 GOOGLE_API_KEY를 자동 사용합니다. 소스와 채팅 로그, 프론트엔드 번들에 키를 넣으면 유출됩니다. 서버 환경 변수나 시크릿 저장소에만 두고 프로세스에 주입합니다.
브라우저에서 직접 호출하면 키가 노출되므로 백엔드가 대신 호출하는 구조가 안전합니다. REST 예제의 헤더 값도 저장소에 커밋하지 않습니다. 유출이 의심되면 AI Studio에서 키를 폐기하고 auth key를 새로 발급합니다. 로컬 개발은 .env 파일을 gitignore에 넣고 셸에서 변수를 export합니다.
Gemini API 연동 정리와 다음 단계
Gemini API 연동 방법은 프로젝트와 키를 준비하고 SDK 또는 REST로 첫 텍스트 호출을 성공시키는 일입니다. 키는 환경 변수로만 주입하고 Standard 키는 auth key로 교체합니다. 429는 한도 초과이므로 백오프하고 400과 403은 키와 권한을 고칩니다. 호출이 안정되면 프롬프트와 모델 버전을 설정 파일로 분리해 운영합니다.
다음 단계는 스트리밍 채팅과 멀티모달 입력을 같은 클라이언트로 확장하는 일입니다. RPM과 TPM, RPD를 모니터링해 프로젝트 한도를 넘기지 않게 조절합니다. Google AI Studio의 사용량 화면과 서버 로그의 상태 코드를 함께 보면 원인 파악이 빨라집니다. 문서의 할당량 표는 모델 패밀리마다 다를 수 있습니다.
