Gemini API 설정 완전 가이드: API 키 발급부터 멀티모달 요청까지 (2026)
Gemini API 설정 완전 가이드 — Google AI Studio에서 첫 멀티모달 요청까지
Google의 Gemini API는 텍스트, 이미지, 오디오, 비디오를 하나의 모델로 처리할 수 있는 강력한 멀티모달 AI입니다. 이 가이드에서는 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 프로젝트를 선택하거나Create API key in new project를 클릭하여 새 프로젝트를 생성합니다.- 키 복사 및 저장 — 생성된 API 키를 안전한 곳에 복사합니다. 이 키는 다시 확인할 수 없으므로 반드시 바로 저장하세요.
환경 변수로 API 키 설정
API 키를 코드에 직접 넣지 말고, 환경 변수로 관리하는 것이 보안상 안전합니다.
# Linux / macOS
export GEMINI_API_KEY=“YOUR_API_KEY”
Windows PowerShell
$env:GEMINI_API_KEY=“YOUR_API_KEY”
Windows CMD
set GEMINI_API_KEY=YOUR_API_KEY
2단계: Python SDK 설치
Google의 공식 Generative AI Python SDK를 설치합니다.
# 최신 SDK 설치
pip install google-genai
설치 확인
python -c “import google.genai; print(‘SDK 설치 완료’)“
가상 환경 사용을 권장합니다:
# 가상 환경 생성 및 활성화
python -m venv gemini-env
Linux/macOS
source gemini-env/bin/activate
Windows
gemini-env\Scripts\activate
pip install google-genai
3단계: 첫 번째 텍스트 요청 보내기
import os
from google import genai
client = genai.Client(api_key=os.environ.get("GEMINI_API_KEY"))
response = client.models.generate_content(
model="gemini-2.0-flash",
contents="대한민국의 수도와 인구를 알려주세요."
)
print(response.text)4단계: 멀티모달 요청 — 이미지 분석
Gemini의 핵심 기능인 멀티모달 처리를 활용하여 이미지를 분석해보겠습니다.
import os
import pathlib
from google import genai
from google.genai import types
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)
5단계: 스트리밍 응답 처리
긴 응답을 실시간으로 받으려면 스트리밍을 사용합니다.
import os
from google import genai
client = genai.Client(api_key=os.environ.get(“GEMINI_API_KEY”))
response = client.models.generate_content_stream(
model=“gemini-2.0-flash”,
contents=“인공지능의 역사를 시대별로 정리해주세요.”
)
for chunk in response:
print(chunk.text, end="", flush=True)
6단계: 대화형 채팅 구현
import os
from google import genai
client = genai.Client(api_key=os.environ.get("GEMINI_API_KEY"))
chat = client.chats.create(model="gemini-2.0-flash")
# 첫 번째 메시지
response = chat.send_message("안녕하세요! 파이썬을 가르쳐주세요.")
print(response.text)
# 대화 이어가기 (이전 컨텍스트 유지)
response = chat.send_message("리스트 컴프리헨션 예제를 보여주세요.")
print(response.text)주요 모델 비교
| 모델 | 특징 | 용도 | 속도 |
|---|---|---|---|
gemini-2.0-flash | 빠른 응답, 비용 효율적 | 일반 작업, 채팅 | 매우 빠름 |
gemini-2.5-pro | 복잡한 추론, 사고 기능 | 코딩, 분석, 수학 | 보통 |
gemini-2.5-flash | 사고 기능 + 속도 균형 | 범용 고성능 | 빠름 |
system_instruction 파라미터로 모델의 역할과 톤을 미리 정의하면 일관된 응답을 얻을 수 있습니다.- Temperature 조절 —from google.genai import types
response = client.models.generate_content( model=“gemini-2.0-flash”, config=types.GenerateContentConfig( system_instruction=“당신은 한국어 기술 문서 전문 번역가입니다.” ), contents=“Translate: Machine learning is a subset of AI.” )
temperature=0.0이면 결정적 응답, temperature=1.0 이상이면 창의적 응답을 생성합니다.- Safety Settings 커스터마이징 — 특정 유형의 콘텐츠 필터링 수준을 조정하여 use case에 맞는 응답을 받으세요.- 구조화된 출력 — response_mime_type=“application/json”을 설정하면 JSON 형식의 응답을 받을 수 있어 후처리가 편리합니다.- 요청 배치 처리 — 여러 요청을 비동기로 처리하려면 asyncio와 함께 비동기 클라이언트를 사용하세요.
Troubleshooting — 자주 발생하는 오류 해결
| 오류 | 원인 | 해결 방법 |
|---|---|---|
400 API_KEY_INVALID | API 키가 잘못되었거나 만료됨 | AI Studio에서 새 키를 발급받고 환경 변수를 업데이트하세요 |
429 RESOURCE_EXHAUSTED | 분당 요청 한도 초과 (무료: 15 RPM) | 요청 간격을 두거나 유료 플랜으로 전환하세요 |
403 PERMISSION_DENIED | 해당 지역에서 API 사용 불가 | VPN을 사용하거나 Google Cloud 프로젝트에서 API를 활성화하세요 |
ModuleNotFoundError | SDK가 설치되지 않음 | pip install google-genai를 실행하세요 |
500 INTERNAL | 서버 측 일시적 오류 | 잠시 후 재시도하세요. 지속되면 Google 상태 페이지를 확인하세요 |
# 응답 메타데이터 확인 response = client.models.generate_content( model="gemini-2.0-flash", contents="테스트 메시지" )사용 토큰 확인
print(f”입력 토큰: {response.usage_metadata.prompt_token_count}”) print(f”출력 토큰: {response.usage_metadata.candidates_token_count}“)
무료 티어 한도 요약
| 항목 | Gemini 2.0 Flash | Gemini 2.5 Pro |
|---|---|---|
| 분당 요청 (RPM) | 15 | 5 |
| 일일 요청 (RPD) | 1,500 | 50 |
| 분당 토큰 (TPM) | 1,000,000 | 250,000 |
Q1: Gemini API는 무료로 사용할 수 있나요?
네, Google AI Studio에서 발급받은 API 키로 무료 티어를 이용할 수 있습니다. 무료 티어에서는 Gemini 2.0 Flash 기준 분당 15회 요청, 일일 1,500회 요청이 가능합니다. 프로덕션 환경이나 더 높은 처리량이 필요하면 Google Cloud의 유료 Vertex AI 플랜을 사용할 수 있습니다.
Q2: Gemini API로 어떤 종류의 파일을 처리할 수 있나요?
Gemini는 텍스트, 이미지(JPEG, PNG, WebP, GIF), 오디오(MP3, WAV, FLAC), 비디오(MP4, MOV), PDF 문서 등 다양한 형식을 지원합니다. 파일 크기가 큰 경우 File API를 통해 업로드한 후 참조하는 방식으로 처리할 수 있습니다.
Q3: OpenAI GPT에서 Gemini로 마이그레이션하려면 코드를 많이 바꿔야 하나요?
Google은 OpenAI 호환 엔드포인트를 제공하므로 기존 OpenAI SDK 코드에서 base URL과 API 키만 변경하면 기본적인 텍스트 생성 기능을 바로 사용할 수 있습니다. 다만 멀티모달 기능이나 Gemini 고유 기능을 완전히 활용하려면 공식 google-genai SDK로 전환하는 것을 권장합니다.