Google Gemini 2.5 Flash 사용 가이드

1. API 키 발급

Google AI Studio에서 API 키 받기

1. Google AI Studio 접속
2. Google 계정으로 로그인
3. “Get API Key” 또는 “API 키 만들기” 클릭
4. 새 프로젝트 생성 또는 기존 프로젝트 선택
5. API 키 복사 및 안전하게 보관

환경 변수 설정

# Linux/macOS
export GOOGLE_API_KEY='your-api-key-here'

# Windows (PowerShell)
$env:GOOGLE_API_KEY='your-api-key-here'

# .env 파일 사용 (권장)
echo "GOOGLE_API_KEY=your-api-key-here" > .env

2. Python에서 Gemini 2.5 Flash 사용

설치

# Python 환경 변수 관리
pip install python-dotenv 
# Python Gemini 플러그인 설치
pip install google-generativeai

기본 사용법

from dotenv import load_dotenv
import google.generativeai as gemini
import os

load_dotenv()

# API 키 설정

gemini.configure(api_key=os.getenv('GOOGLE_API_KEY'))
# 모델 초기화
model = gemini.GenerativeModel('gemini-2.5-flash')

# 텍스트 생성
response = model.generate_content('Python으로 간단한 계산기를 만드는 방법을 알려줘')
print(response.text)

스트리밍 응답

from dotenv import load_dotenv
import os
import google.generativeai as gemini
import os

# 환경 변수 load
load_dotenv()


gemini.configure(api_key=os.environ['GOOGLE_API_KEY'])
model = gemini.GenerativeModel('gemini-2.5-flash')

# 스트리밍으로 응답 받기
response = model.generate_content(
    '머신러닝의 주요 개념 10가지를 설명해줘',
    stream=True
)

for chunk in response:
    print(chunk.text, end='', flush=True)

3. 대화 컨텍스트 유지하기

Chat 세션 사용

import google.generativeai as genai
import os

genai.configure(api_key=os.environ['GOOGLE_API_KEY'])
model = genai.GenerativeModel('gemini-2.5-flash')

# 채팅 세션 시작
chat = model.start_chat(history=[])

# 대화 진행
response1 = chat.send_message('안녕하세요! 파이썬에 대해 알려주세요.')
print(f"답변 1: {response1.text}\n")

# 이전 대화를 기억하며 계속 대화
response2 = chat.send_message('방금 설명한 내용 중 주요 특징 3가지만 요약해줘')
print(f"답변 2: {response2.text}\n")

# 대화 히스토리 확인
print("대화 히스토리:")
for message in chat.history:
    print(f"{message.role}: {message.parts[0].text[:50]}...")

시스템 프롬프트와 함께 사용

import google.generativeai as genai
import os

genai.configure(api_key=os.environ['GOOGLE_API_KEY'])

# 시스템 프롬프트 설정
model = genai.GenerativeModel(
    'gemini-2.5-flash',
    system_instruction='You are a helpful coding assistant. Always provide code examples with explanations in Korean.'
)

chat = model.start_chat()

response = chat.send_message('배열을 정렬하는 방법을 알려줘')
print(response.text)

# 컨텍스트를 유지하며 계속 대화
response2 = chat.send_message('방금 설명한 방법의 시간 복잡도는?')
print(response2.text)

대화 히스토리 초기화 및 관리

import google.generativeai as genai
import os

class GeminiChatSession:
    def __init__(self, model_name='gemini-2.5-flash', system_instruction=None):
        genai.configure(api_key=os.environ['GOOGLE_API_KEY'])

        if system_instruction:
            self.model = genai.GenerativeModel(
                model_name,
                system_instruction=system_instruction
            )
        else:
            self.model = genai.GenerativeModel(model_name)

        self.chat = self.model.start_chat(history=[])

    def send(self, message, stream=False):
        """메시지 전송"""
        response = self.chat.send_message(message, stream=stream)

        if stream:
            return response  # 스트림 객체 반환
        else:
            return response.text

    def get_history(self):
        """대화 히스토리 반환"""
        return self.chat.history

    def clear_history(self):
        """대화 히스토리 초기화"""
        self.chat = self.model.start_chat(history=[])

    def reset_with_history(self, history):
        """특정 히스토리로 세션 재설정"""
        self.chat = self.model.start_chat(history=history)

# 사용 예시
session = GeminiChatSession(
    system_instruction='You are a helpful AI assistant. Answer in Korean.'
)

print(session.send('Python의 리스트와 튜플의 차이는?'))
print('\n---\n')

print(session.send('그럼 언제 튜플을 사용하는게 좋아?'))
print('\n---\n')

# 대화 히스토리 확인
print(f"총 {len(session.get_history())}개의 메시지")

# 히스토리 초기화
session.clear_history()
print("대화가 초기화되었습니다.")

대화 저장 및 불러오기

import google.generativeai as genai
import os
import json
from google.generativeai.types import content_types

class PersistentGeminiChat:
    def __init__(self, model_name='gemini-2.5-flash', session_file='gemini_chat.json'):
        genai.configure(api_key=os.environ['GOOGLE_API_KEY'])
        self.model = genai.GenerativeModel(model_name)
        self.session_file = session_file

        # 저장된 히스토리 로드
        history = self.load_history()
        self.chat = self.model.start_chat(history=history)

    def load_history(self):
        """저장된 대화 불러오기"""
        try:
            with open(self.session_file, 'r', encoding='utf-8') as f:
                data = json.load(f)

            # JSON을 Gemini 히스토리 형식으로 변환
            history = []
            for msg in data:
                history.append({
                    'role': msg['role'],
                    'parts': [msg['content']]
                })
            return history
        except FileNotFoundError:
            return []

    def save_history(self):
        """대화 저장"""
        # Gemini 히스토리를 JSON 형식으로 변환
        history_data = []
        for msg in self.chat.history:
            history_data.append({
                'role': msg.role,
                'content': msg.parts[0].text
            })

        with open(self.session_file, 'w', encoding='utf-8') as f:
            json.dump(history_data, f, ensure_ascii=False, indent=2)

    def send(self, message):
        """메시지 전송 및 자동 저장"""
        response = self.chat.send_message(message)
        self.save_history()
        return response.text

# 사용 예시
chat = PersistentGeminiChat()

print(chat.send('안녕하세요!'))
print(chat.send('내 이름은 김철수야'))

# 프로그램을 재시작해도 이전 대화가 유지됩니다
# chat2 = PersistentGeminiChat()
# print(chat2.send('내 이름이 뭐였지?'))  # "김철수" 기억

4. 이미지와 함께 사용 (멀티모달)

이미지 파일 업로드

import google.generativeai as genai
import os
from PIL import Image

genai.configure(api_key=os.environ['GOOGLE_API_KEY'])
model = genai.GenerativeModel('gemini-2.5-flash')

# 이미지 로드
image = Image.open('example.jpg')

# 이미지와 텍스트 함께 전송
response = model.generate_content([
    '이 이미지에 무엇이 보이나요? 자세히 설명해주세요.',
    image
])

print(response.text)

URL에서 이미지 사용

import google.generativeai as genai
import os
import requests
from PIL import Image
from io import BytesIO

genai.configure(api_key=os.environ['GOOGLE_API_KEY'])
model = genai.GenerativeModel('gemini-2.5-flash')

# URL에서 이미지 가져오기
image_url = 'https://example.com/image.jpg'
response = requests.get(image_url)
image = Image.open(BytesIO(response.content))

# 이미지 분석
response = model.generate_content([
    '이 이미지의 주요 객체들을 나열하고 설명해주세요.',
    image
])

print(response.text)

여러 이미지 분석

import google.generativeai as genai
import os
from PIL import Image

genai.configure(api_key=os.environ['GOOGLE_API_KEY'])
model = genai.GenerativeModel('gemini-2.5-flash')

# 여러 이미지 로드
image1 = Image.open('before.jpg')
image2 = Image.open('after.jpg')

# 여러 이미지 비교
response = model.generate_content([
    '두 이미지의 차이점을 분석해주세요.',
    image1,
    image2
])

print(response.text)

5. 고급 설정

생성 파라미터 조정

import google.generativeai as genai
import os

genai.configure(api_key=os.environ['GOOGLE_API_KEY'])
model = genai.GenerativeModel('gemini-2.5-flash')

# 생성 설정
generation_config = genai.GenerationConfig(
    temperature=0.9,          # 창의성 (0.0 ~ 2.0)
    top_p=0.95,               # Nucleus sampling
    top_k=40,                 # Top-k sampling
    max_output_tokens=2048,   # 최대 출력 토큰
    stop_sequences=['END']    # 중지 시퀀스
)

response = model.generate_content(
    '창의적인 단편 소설을 써줘',
    generation_config=generation_config
)

print(response.text)

안전 설정

import google.generativeai as genai
from google.generativeai.types import HarmCategory, HarmBlockThreshold
import os

genai.configure(api_key=os.environ['GOOGLE_API_KEY'])
model = genai.GenerativeModel('gemini-2.5-flash')

# 안전 설정
safety_settings = {
    HarmCategory.HARM_CATEGORY_HATE_SPEECH: HarmBlockThreshold.BLOCK_NONE,
    HarmCategory.HARM_CATEGORY_HARASSMENT: HarmBlockThreshold.BLOCK_NONE,
    HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
    HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
}

response = model.generate_content(
    '프롬프트 내용',
    safety_settings=safety_settings
)

print(response.text)

6. 함수 호출 (Function Calling)

함수 정의 및 사용

import google.generativeai as genai
import os

genai.configure(api_key=os.environ['GOOGLE_API_KEY'])

# 함수 정의
def get_weather(location: str, unit: str = "celsius"):
    """날씨 정보를 가져옵니다."""
    # 실제로는 API 호출
    return f"{location}의 날씨는 맑음, 온도는 20{unit}입니다."

def calculate(operation: str, a: float, b: float):
    """계산을 수행합니다."""
    if operation == "add":
        return a + b
    elif operation == "subtract":
        return a - b
    elif operation == "multiply":
        return a * b
    elif operation == "divide":
        return a / b if b != 0 else "0으로 나눌 수 없습니다"

# 함수를 모델에 등록
tools = [get_weather, calculate]

model = genai.GenerativeModel('gemini-2.5-flash', tools=tools)
chat = model.start_chat()

# 함수 호출을 포함한 대화
response = chat.send_message('서울의 날씨가 어때? 그리고 25 곱하기 4는?')

# 함수 호출 실행
for part in response.parts:
    if fn := part.function_call:
        # 함수 실행
        if fn.name == 'get_weather':
            result = get_weather(**dict(fn.args))
        elif fn.name == 'calculate':
            result = calculate(**dict(fn.args))

        print(f"함수 실행: {fn.name}({fn.args}) = {result}")

print(response.text)

7. 토큰 수 계산

입력 토큰 수 확인

import google.generativeai as genai
import os

genai.configure(api_key=os.environ['GOOGLE_API_KEY'])
model = genai.GenerativeModel('gemini-2.5-flash')

prompt = "이것은 토큰 수를 계산하기 위한 예시 텍스트입니다."

# 토큰 수 계산
token_count = model.count_tokens(prompt)
print(f"토큰 수: {token_count.total_tokens}")

대화 히스토리 토큰 수

import google.generativeai as genai
import os

genai.configure(api_key=os.environ['GOOGLE_API_KEY'])
model = genai.GenerativeModel('gemini-2.5-flash')

chat = model.start_chat()
chat.send_message('안녕하세요')
chat.send_message('오늘 날씨가 좋네요')

# 전체 대화 토큰 수
total_tokens = model.count_tokens(chat.history)
print(f"전체 대화 토큰 수: {total_tokens.total_tokens}")

8. REST API 직접 사용

cURL 예시

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=$GOOGLE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "parts": [{
        "text": "Python으로 Hello World를 출력하는 방법을 알려줘"
      }]
    }]
  }'

Python requests 사용

import requests
import os
import json

API_KEY = os.environ['GOOGLE_API_KEY']
url = f'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key={API_KEY}'

headers = {
    'Content-Type': 'application/json'
}

data = {
    'contents': [{
        'parts': [{
            'text': 'Python으로 Hello World를 출력하는 방법을 알려줘'
        }]
    }]
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

print(result['candidates'][0]['content']['parts'][0]['text'])

Node.js에서 사용

const fetch = require('node-fetch');

const API_KEY = process.env.GOOGLE_API_KEY;
const url = `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=${API_KEY}`;

async function generateContent(prompt) {
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      contents: [{
        parts: [{
          text: prompt
        }]
      }]
    })
  });

  const data = await response.json();
  return data.candidates[0].content.parts[0].text;
}

// 사용 예시
generateContent('JavaScript로 배열을 정렬하는 방법').then(console.log);

대화 컨텍스트 유지 (REST API)

import requests
import os

class GeminiRESTChat:
    def __init__(self, model='gemini-2.5-flash'):
        self.api_key = os.environ['GOOGLE_API_KEY']
        self.model = model
        self.url = f'https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent?key={self.api_key}'
        self.history = []

    def send_message(self, text):
        # 새 메시지 추가
        self.history.append({
            'role': 'user',
            'parts': [{'text': text}]
        })

        # API 요청
        response = requests.post(
            self.url,
            headers={'Content-Type': 'application/json'},
            json={'contents': self.history}
        )

        result = response.json()
        assistant_message = result['candidates'][0]['content']

        # 응답을 히스토리에 추가
        self.history.append({
            'role': 'model',
            'parts': assistant_message['parts']
        })

        return assistant_message['parts'][0]['text']

    def clear_history(self):
        self.history = []

# 사용 예시
chat = GeminiRESTChat()

print(chat.send_message('안녕하세요'))
print('\n---\n')
print(chat.send_message('방금 내가 뭐라고 말했지?'))  # 컨텍스트 유지

9. 에러 처리

기본 에러 처리

import google.generativeai as genai
import os
from google.api_core import exceptions

genai.configure(api_key=os.environ['GOOGLE_API_KEY'])
model = genai.GenerativeModel('gemini-2.5-flash')

try:
    response = model.generate_content('테스트 프롬프트')
    print(response.text)
except exceptions.InvalidArgument as e:
    print(f"잘못된 인자: {e}")
except exceptions.ResourceExhausted as e:
    print(f"할당량 초과: {e}")
except exceptions.PermissionDenied as e:
    print(f"권한 거부: {e}")
except Exception as e:
    print(f"에러 발생: {e}")

안전 필터 처리

import google.generativeai as genai
import os

genai.configure(api_key=os.environ['GOOGLE_API_KEY'])
model = genai.GenerativeModel('gemini-2.5-flash')

response = model.generate_content('프롬프트')

# 안전 필터로 차단되었는지 확인
if response.prompt_feedback.block_reason:
    print(f"차단됨: {response.prompt_feedback.block_reason}")
else:
    print(response.text)

10. 성능 최적화 팁

배치 처리

import google.generativeai as genai
import os
from concurrent.futures import ThreadPoolExecutor

genai.configure(api_key=os.environ['GOOGLE_API_KEY'])
model = genai.GenerativeModel('gemini-2.5-flash')

prompts = [
    'Python이란?',
    'JavaScript란?',
    'Go언어란?',
]

def generate(prompt):
    response = model.generate_content(prompt)
    return response.text

# 병렬 처리
with ThreadPoolExecutor(max_workers=3) as executor:
    results = executor.map(generate, prompts)

for prompt, result in zip(prompts, results):
    print(f"Q: {prompt}")
    print(f"A: {result[:100]}...\n")

캐싱 (간단한 예시)

import google.generativeai as genai
import os
from functools import lru_cache

genai.configure(api_key=os.environ['GOOGLE_API_KEY'])
model = genai.GenerativeModel('gemini-2.5-flash')

@lru_cache(maxsize=100)
def cached_generate(prompt):
    """동일한 프롬프트에 대해 캐싱"""
    response = model.generate_content(prompt)
    return response.text

# 첫 번째 호출 - API 요청
result1 = cached_generate('Python이란?')

# 두 번째 호출 - 캐시에서 반환 (빠름)
result2 = cached_generate('Python이란?')

print(result1 == result2)  # True