Gemini API Python 예제: 최신 google-genai SDK 설치와 오류 점검

Gemini API Python 빠른 시작

오래된 google-generativeai 예제를 그대로 복사하면 현재 권장 SDK와 메서드가 달라 실행 과정에서 혼란이 생길 수 있습니다. 이 글은 Google이 안내하는 google-genai 패키지를 기준으로 설치부터 첫 응답 확인까지 설명합니다. 공식 문서: Gemini API 시작하기, 모델 목록.

1. 시작 전 준비물

Python과 인터넷이 연결된 개인 실습 환경
Google AI Studio에서 발급한 유효한 Gemini API 키
현재 본인 프로젝트에서 이용 가능한 모델 이름

API 키는 블로그 본문이나 공개 GitHub 저장소에 붙여 넣지 마세요. 개발 PC에서는 환경변수로 설정합니다. 무료 사용 가능 범위와 결제 조건은 공식 가격표를 확인하세요.

2. Python 가상환경과 SDK 설치

# 프로젝트 폴더에서 실행
python -m venv .venv
# Windows PowerShell
.venv\Scripts\Activate.ps1
# macOS/Linux
# source .venv/bin/activate
python -m pip install -U google-genai python-dotenv

기존 라이브러리의 import google.generativeai as genai와 새 SDK의 from google import genai는 서로 다른 사용법입니다. 새 프로젝트는 공식적으로 안내되는 google-genai 설치 방법을 기준으로 작성하세요.

3. 키와 모델을 .env로 관리하기

프로젝트 폴더에 아래 형식의 .env 파일을 생성하세요. GEMINI_MODEL에는 본인 프로젝트의 모델 목록에서 확인한 정확한 모델 ID를 넣습니다. 아래 모델명은 예시일 뿐, 실제 사용 가능 여부를 먼저 확인해야 합니다.

GEMINI_API_KEY=여기에_개인_API_키
GEMINI_MODEL=gemini-2.5-flash

.gitignore 파일에 .env를 넣어 저장소에 키가 올라가지 않도록 설정하세요.

4. 직접 따라 하는 텍스트 생성 코드

import os
from dotenv import load_dotenv
from google import genai

load_dotenv()
api_key = os.getenv("GEMINI_API_KEY")
model_name = os.getenv("GEMINI_MODEL")
if not api_key or not model_name:
    raise RuntimeError(".env에 GEMINI_API_KEY와 GEMINI_MODEL을 설정하세요.")

client = genai.Client(api_key=api_key)
response = client.models.generate_content(
    model=model_name,
    contents="새로 개업한 작은 서점의 SNS 소개 문구를 한국어 2문장으로 작성해 줘.",
)
print(response.text or "텍스트 응답이 없습니다. 응답 내용을 확인하세요.")

실습 결과는 모델과 설정에 따라 달라지며 위 코드는 실행 과정의 구조를 보여주는 예제입니다. 오류가 발생하면 모델 ID, 키 유효성, 네트워크 연결 및 프로젝트 한도를 차례로 점검하세요.

5. 고유 실습: 고객 문의에서 필수 정보만 추출하기

아래 입력은 실제 고객 정보가 아닌 가상 데이터입니다. 서점 문의를 정리하는 용도로 프롬프트를 바꿔 봅니다.

sample = """안녕하세요. 주문한 소설 두 권 중 한 권이 빠졌어요.
배송 조회 번호는 없고 주문일은 금요일입니다."""
prompt = (
    "다음 고객 문의에서 '문의 종류', '확인할 정보', '고객에게 보낼 첫 답변'을 "
    "한국어로 각각 한 줄씩 작성하세요. 없는 주문번호를 지어내지 마세요.\n"
    + sample
)
response = client.models.generate_content(model=model_name, contents=prompt)
print(response.text)

결과가 사실과 다른 주문번호를 만들지는 않았는지, 개인정보를 요구하기 전에 문의 목적이 제대로 파악됐는지 사람이 직접 검토해야 합니다. 실제 고객 정보는 데이터 처리 정책을 검토한 뒤에만 입력하세요.

6. 자주 발생하는 오류

모듈을 찾을 수 없음: 활성화된 가상환경에 google-genai가 설치됐는지 확인합니다.
인증 실패: 환경변수 이름과 키를 확인합니다. 화면 공유나 로그에 키가 노출되지 않게 주의합니다.
404 또는 모델을 찾을 수 없음: Google AI Studio에서 현재 프로젝트가 지원하는 모델 ID와 API 버전을 확인합니다.
429 RESOURCE_EXHAUSTED: 공식 요청 한도에 따라 분당 요청·토큰·일일 요청을 확인하고, 안내된 재시도 지연과 지수 백오프를 적용합니다. 무한 반복 요청은 피합니다.

수정 기준: 2026년 9월. 실제 SDK 업데이트와 모델 서비스 종료 시점은 공식 문서에서 확인하세요.