Gemini API 설치 및 설정 완벽 가이드 – API 키 발급부터 멀티모달 요청까지
Gemini API란?
Gemini API는 Google이 제공하는 최신 생성형 AI 모델에 접근할 수 있는 인터페이스입니다. 텍스트, 이미지, 오디오, 비디오 등 다양한 입력을 처리하는 멀티모달 기능을 갖추고 있으며, Python SDK를 통해 몇 줄의 코드만으로 강력한 AI 기능을 애플리케이션에 통합할 수 있습니다. 이 가이드에서는 Google AI Studio에서 API 키를 발급받고, Python SDK를 설치한 뒤, 텍스트와 이미지를 결합한 멀티모달 요청을 보내는 전체 과정을 단계별로 안내합니다.
사전 준비 사항
- Google 계정 (Gmail 계정이면 충분합니다)- Python 3.9 이상 설치- pip 패키지 관리자- 터미널 또는 명령 프롬프트 접근 권한
1단계: Google AI Studio에서 API 키 발급
- Google AI Studio 접속: 브라우저에서
aistudio.google.com에 접속하고 Google 계정으로 로그인합니다.- API 키 생성: 왼쪽 메뉴에서 “Get API Key” 버튼을 클릭합니다.- 프로젝트 선택: 기존 Google Cloud 프로젝트를 선택하거나 새 프로젝트를 생성합니다.- 키 복사: 생성된 API 키를 안전한 곳에 복사하여 저장합니다. 이 키는 다시 확인할 수 없으므로 반드시 기록해 두세요.
2단계: Python SDK 설치
터미널에서 다음 명령어를 실행하여 Google Generative AI Python SDK를 설치합니다.
pip install google-genai
설치가 완료되면 버전을 확인합니다.
python -c “import google.genai; print(google.genai.version)“
가상 환경을 사용하는 것이 권장됩니다.
# 가상 환경 생성 및 활성화
python -m venv gemini-env
macOS/Linux
source gemini-env/bin/activate
Windows
gemini-env\Scripts\activate
SDK 설치
pip install google-genai
3단계: API 키 환경 변수 설정
API 키를 코드에 직접 하드코딩하는 것은 보안상 위험합니다. 환경 변수로 설정하세요.
macOS / Linux
export GEMINI_API_KEY=“YOUR_API_KEY”
Windows (PowerShell)
$env:GEMINI_API_KEY="YOUR_API_KEY"영구 저장하려면 .bashrc, .zshrc 또는 시스템 환경 변수에 추가합니다.
4단계: 첫 번째 텍스트 요청 보내기
from google import genai
import os
client = genai.Client(api_key=os.environ.get(“GEMINI_API_KEY”))
response = client.models.generate_content(
model=“gemini-2.0-flash”,
contents=“한국의 4계절 특징을 간단히 설명해 주세요.”
)
print(response.text)
위 코드를 first_request.py로 저장하고 실행합니다.
python first_request.py
5단계: 멀티모달 요청 – 이미지 분석
Gemini의 핵심 강점은 멀티모달 처리입니다. 로컬 이미지 파일을 업로드하여 분석할 수 있습니다.
from google import genai
from google.genai import types
import os
import pathlib
client = genai.Client(api_key=os.environ.get(“GEMINI_API_KEY”))
로컬 이미지 파일 로드
image_path = pathlib.Path(“sample.jpg”)
image_data = image_path.read_bytes()
response = client.models.generate_content(
model=“gemini-2.0-flash”,
contents=[
types.Part.from_bytes(data=image_data, mime_type=“image/jpeg”),
“이 이미지에 무엇이 보이는지 한국어로 자세히 설명해 주세요.”
]
)
print(response.text)
6단계: 대화형 채팅 구현
멀티턴 대화를 구현하려면 채팅 세션을 사용합니다.
from google import genai
import os
client = genai.Client(api_key=os.environ.get(“GEMINI_API_KEY”))
chat = client.chats.create(model=“gemini-2.0-flash”)
첫 번째 메시지
response = chat.send_message(“Python 리스트 컴프리헨션을 설명해 줘.”)
print(response.text)
후속 질문 (이전 대화 맥락 유지)
response = chat.send_message(“그걸 딕셔너리에도 적용할 수 있어?”)
print(response.text)
7단계: 스트리밍 응답 처리
긴 응답을 실시간으로 받으려면 스트리밍을 활용합니다.
from google import genai
import os
client = genai.Client(api_key=os.environ.get(“GEMINI_API_KEY”))
response = client.models.generate_content_stream(
model=“gemini-2.0-flash”,
contents=“머신러닝의 주요 알고리즘 10가지를 설명해 주세요.”
)
for chunk in response:
print(chunk.text, end="")
Gemini 모델 비교
| 모델 | 특징 | 권장 용도 | 컨텍스트 윈도우 |
|---|---|---|---|
| Gemini 2.5 Pro | 사고 모델, 최고 성능 | 복잡한 추론, 코딩 | 1M 토큰 |
| Gemini 2.0 Flash | 빠른 응답, 균형 잡힌 성능 | 일반 목적, 프로토타이핑 | 1M 토큰 |
| Gemini 2.0 Flash-Lite | 경량, 최저 비용 | 대량 처리, 간단한 작업 | 1M 토큰 |
config 매개변수에 system_instruction을 설정하면 모델의 역할과 응답 스타일을 일관되게 제어할 수 있습니다.- **안전 설정 커스터마이징**: safety_settings를 조정하여 콘텐츠 필터링 수준을 애플리케이션에 맞게 구성하세요.- **구조화된 출력**: response_mime_type="application/json"을 설정하면 JSON 형식의 응답을 받을 수 있어 후처리가 편리합니다.- **토큰 카운팅**: client.models.count_tokens()를 사용하여 요청 전 토큰 수를 확인하면 비용을 관리할 수 있습니다.- **비동기 처리**: google.genai.Client의 비동기 메서드를 활용하면 대규모 배치 처리 시 성능을 크게 향상시킬 수 있습니다.
## Troubleshooting – 자주 발생하는 오류 해결
| 오류 메시지 | 원인 | 해결 방법 |
|---|---|---|
InvalidArgument: API key not valid | 잘못된 API 키 | Google AI Studio에서 키를 다시 발급받으세요. 키 앞뒤 공백이 없는지 확인하세요. |
ResourceExhausted: 429 | 분당 요청 한도 초과 | 무료 티어는 분당 15 RPM입니다. 요청 간 지연을 추가하거나 유료 플랜으로 전환하세요. |
ModuleNotFoundError: No module named 'google.genai' | SDK 미설치 또는 잘못된 환경 | pip install google-genai를 실행하고, 올바른 가상 환경이 활성화되었는지 확인하세요. |
PermissionDenied: 403 | API 키 권한 부족 또는 지역 제한 | Google Cloud 콘솔에서 Generative Language API가 활성화되었는지 확인하세요. |
BlockedPromptException | 안전 필터에 의해 차단됨 | 프롬프트를 수정하거나 safety_settings를 조정하세요. |
Q1: Gemini API는 무료로 사용할 수 있나요?
네, Google AI Studio를 통해 무료 티어를 제공합니다. 무료 티어에서는 분당 15회 요청(RPM)과 일일 1,500회 요청(RPD) 제한이 적용됩니다. 프로덕션 수준의 사용량이 필요하면 Google Cloud Vertex AI를 통한 유료 플랜을 이용할 수 있으며, 사용한 토큰 수에 따라 과금됩니다.
Q2: Gemini API에서 지원하는 입력 형식은 무엇인가요?
Gemini 모델은 텍스트, 이미지(JPEG, PNG, WebP, GIF), 오디오(MP3, WAV, FLAC 등), 비디오(MP4, MOV 등), PDF 문서를 입력으로 지원합니다. 멀티모달 모델이므로 이러한 입력을 하나의 요청에서 조합하여 사용할 수 있습니다. 예를 들어 이미지와 텍스트 질문을 함께 보내 이미지 내용에 대한 분석을 요청할 수 있습니다.
Q3: 기존 OpenAI 프로젝트를 Gemini로 마이그레이션할 수 있나요?
Gemini API는 OpenAI 호환 엔드포인트를 제공하므로 기존 OpenAI SDK 기반 코드에서 base_url과 API 키만 변경하면 기본적인 전환이 가능합니다. 다만 멀티모달 입력 형식, 안전 설정, 시스템 지시문 구조 등에서 차이가 있으므로 공식 마이그레이션 가이드를 참고하여 세부 사항을 조정하는 것이 좋습니다.