Gemini API 멀티모달 개발자 가이드: 이미지, 비디오, 문서 분석 코드 예제
Gemini API 멀티모달 개발자 가이드: 이미지, 비디오, 문서 분석 완전 정복
Gemini API는 텍스트, 이미지, 비디오, 오디오, 문서를 하나의 프롬프트에서 동시에 처리할 수 있는 네이티브 멀티모달 모델을 제공한다. 기존의 파이프라인에서는 OCR, 객체 감지, 음성 인식 등 별도의 모델을 조합해야 했지만, Gemini는 단일 API 호출로 여러 미디어 유형을 통합 분석할 수 있어 아키텍처 복잡성과 유지보수 비용을 크게 줄여준다.
이 가이드에서는 Python SDK를 사용하여 이미지 분석, 문서 데이터 추출, 비디오 프레임 처리, 비주얼 Q&A 시스템, 혼합 미디어 파이프라인까지 실전 코드와 함께 단계별로 다룬다.
Gemini 멀티모달 API의 핵심 장점
Gemini 멀티모달 API가 개발자에게 제공하는 주요 이점은 다음과 같다.
통합된 컨텍스트 이해. 이미지 속 텍스트, 차트의 수치, 비디오의 장면 전환을 하나의 모델이 종합적으로 이해한다. 별도의 OCR 엔진이나 비전 모델을 파이프라인으로 연결할 필요가 없다.
긴 컨텍스트 윈도우. Gemini 2.5 Pro는 최대 100만 토큰의 컨텍스트를 지원하며, 이를 통해 수십 장의 이미지나 수 시간 분량의 비디오를 한 번에 처리할 수 있다.
구조화된 출력. JSON 모드와 스키마 지정을 통해 분석 결과를 즉시 파싱 가능한 구조화된 데이터로 받을 수 있어 후처리 로직이 단순해진다.
비용 효율성. 여러 전문 모델을 조합하는 대신 하나의 API로 처리하므로 인프라 비용과 레이턴시가 모두 감소한다.
시작하기: SDK 설치와 기본 설정
SDK 설치
Google Generative AI Python SDK를 설치한다.
pip install google-genaiAPI 키 설정과 클라이언트 초기화
Google AI Studio에서 API 키를 발급받은 후, 환경 변수로 설정하고 클라이언트를 초기화한다.
import os
from google import genai
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])API 키는 코드에 직접 하드코딩하지 않고 반드시 환경 변수나 시크릿 관리 도구를 통해 관리해야 한다.
첫 번째 멀티모달 호출
로컬 이미지 파일을 읽어 Gemini에 질문하는 가장 기본적인 예제부터 살펴보자.
from google.genai import types
with open("product_photo.jpg", "rb") as f:
image_bytes = f.read()
response = client.models.generate_content(
model="gemini-2.5-pro",
contents=[
types.Content(
role="user",
parts=[
types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg"),
types.Part.from_text("이 이미지에 어떤 제품이 보이는지 설명해 주세요."),
],
)
],
)
print(response.text)Part.from_bytes로 이미지 데이터를 전달하고, Part.from_text로 질문을 함께 보내면 Gemini가 이미지 내용을 분석하여 응답한다. URL로 이미지를 전달하려면 Part.from_uri를 사용할 수도 있다.
이미지 분석 패턴
제품 이미지 분석
이커머스 환경에서 제품 이미지를 자동으로 분석하여 카테고리, 색상, 상태 등의 메타데이터를 추출하는 패턴이다.
import json
def analyze_product_image(image_path: str) -> dict:
with open(image_path, "rb") as f:
image_bytes = f.read()
response = client.models.generate_content(
model="gemini-2.5-pro",
contents=[
types.Content(
role="user",
parts=[
types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg"),
types.Part.from_text(
"이 제품 이미지를 분석하여 다음 정보를 JSON으로 반환하세요: "
"category, product_name, colors (배열), condition (new/used/refurbished), "
"estimated_price_range, key_features (배열). "
"JSON만 출력하고 다른 텍스트는 포함하지 마세요."
),
],
)
],
config=types.GenerateContentConfig(
response_mime_type="application/json",
),
)
return json.loads(response.text)response_mime_type을 application/json으로 설정하면 Gemini가 반드시 유효한 JSON을 반환하도록 강제할 수 있다. 이를 통해 파싱 오류를 방지하고 후처리 로직을 단순화할 수 있다.
멀티 이미지 비교 분석
여러 이미지를 한 번에 전달하여 비교 분석하는 패턴이다. 제품 A/B 비교, 시간 경과에 따른 변화 추적, 품질 검사 등에 활용된다.
def compare_images(image_paths: list[str], comparison_prompt: str) -> str:
parts = []
for i, path in enumerate(image_paths):
with open(path, "rb") as f:
image_bytes = f.read()
parts.append(types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg"))
parts.append(types.Part.from_text(f"[이미지 {i + 1}]"))
parts.append(types.Part.from_text(comparison_prompt))
response = client.models.generate_content(
model="gemini-2.5-pro",
contents=[types.Content(role="user", parts=parts)],
)
return response.text
result = compare_images(
["product_v1.jpg", "product_v2.jpg"],
"두 제품 이미지의 디자인 차이점을 항목별로 정리해 주세요. "
"색상, 형태, 소재, 브랜딩 요소를 비교하세요.",
)각 이미지 사이에 레이블 텍스트를 삽입하면 모델이 어떤 이미지를 참조하는지 명확하게 구분할 수 있다.
QA 스크린샷 분석
UI 테스트 자동화에서 스크린샷을 캡처한 후, Gemini로 시각적 결함을 감지하는 패턴이다.
def analyze_ui_screenshot(screenshot_path: str, expected_behavior: str) -> dict:
with open(screenshot_path, "rb") as f:
image_bytes = f.read()
response = client.models.generate_content(
model="gemini-2.5-pro",
contents=[
types.Content(
role="user",
parts=[
types.Part.from_bytes(data=image_bytes, mime_type="image/png"),
types.Part.from_text(
f"이 UI 스크린샷을 QA 관점에서 분석하세요.\n"
f"기대 동작: {expected_behavior}\n\n"
"다음 항목을 JSON으로 반환하세요: "
"pass (boolean), issues (배열: severity, description, location), "
"accessibility_concerns (배열), overall_assessment (문자열)."
),
],
)
],
config=types.GenerateContentConfig(
response_mime_type="application/json",
),
)
return json.loads(response.text)이 패턴은 CI/CD 파이프라인에 통합하여 매 배포 전 시각적 회귀 테스트를 자동화하는 데 활용할 수 있다.
문서 처리
영수증 데이터 추출
종이 영수증이나 전자 영수증 이미지에서 구조화된 데이터를 추출하는 패턴이다.
def extract_receipt_data(receipt_image_path: str) -> dict:
with open(receipt_image_path, "rb") as f:
image_bytes = f.read()
response = client.models.generate_content(
model="gemini-2.5-pro",
contents=[
types.Content(
role="user",
parts=[
types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg"),
types.Part.from_text(
"이 영수증 이미지에서 다음 정보를 추출하여 JSON으로 반환하세요: "
"store_name, date, items (배열: name, quantity, unit_price, total), "
"subtotal, tax, total, payment_method. "
"금액은 숫자만 사용하고 통화 기호는 제외하세요."
),
],
)
],
config=types.GenerateContentConfig(
response_mime_type="application/json",
),
)
return json.loads(response.text)영수증의 레이아웃이 다양하더라도 Gemini의 비전 능력이 텍스트 위치와 구조를 파악하여 정확한 데이터를 추출한다. 기존 OCR 후 규칙 기반 파싱 방식에 비해 새로운 영수증 형식에 대한 적응력이 훨씬 높다.
PDF 문서 분석
Gemini File API를 사용하면 PDF 파일을 직접 업로드하여 분석할 수 있다.
def analyze_pdf_document(pdf_path: str, analysis_prompt: str) -> str:
uploaded_file = client.files.upload(file=pdf_path)
response = client.models.generate_content(
model="gemini-2.5-pro",
contents=[
types.Content(
role="user",
parts=[
types.Part.from_uri(
file_uri=uploaded_file.uri,
mime_type="application/pdf",
),
types.Part.from_text(analysis_prompt),
],
)
],
)
return response.text
result = analyze_pdf_document(
"contract_2026.pdf",
"이 계약서에서 다음 항목을 추출하세요: "
"계약 당사자, 계약 기간, 주요 의무사항, 위약금 조항, 특이사항."
)File API를 통해 업로드된 파일은 서버 측에서 처리되며, 대용량 PDF도 효율적으로 분석할 수 있다. 업로드된 파일은 48시간 후 자동으로 삭제된다.
양식 데이터 추출
수기로 작성된 신청서나 설문지 이미지에서 필드별 데이터를 추출하는 패턴이다.
def extract_form_fields(form_image_path: str, field_definitions: list[str]) -> dict:
with open(form_image_path, "rb") as f:
image_bytes = f.read()
fields_text = ", ".join(field_definitions)
response = client.models.generate_content(
model="gemini-2.5-pro",
contents=[
types.Content(
role="user",
parts=[
types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg"),
types.Part.from_text(
f"이 양식 이미지에서 다음 필드를 추출하세요: {fields_text}. "
"수기 글씨도 최대한 정확하게 인식하세요. "
"읽을 수 없는 필드는 null로 표시하고, "
"confidence (0.0~1.0) 값도 함께 반환하세요. "
"JSON 형식으로 출력하세요."
),
],
)
],
config=types.GenerateContentConfig(
response_mime_type="application/json",
),
)
return json.loads(response.text)
result = extract_form_fields(
"application_form.jpg",
["applicant_name", "date_of_birth", "address", "phone_number", "signature_present"],
)confidence 값을 함께 요청하면 후처리 단계에서 낮은 신뢰도의 필드만 사람이 검토하는 워크플로를 구성할 수 있다.
비디오 분석
비디오 업로드와 요약
Gemini File API를 통해 비디오 파일을 업로드하고 내용을 분석한다. 업로드 후 처리가 완료될 때까지 상태를 확인해야 한다.
import time
def upload_and_wait(video_path: str) -> object:
uploaded_file = client.files.upload(file=video_path)
while uploaded_file.state.name == "PROCESSING":
time.sleep(5)
uploaded_file = client.files.get(name=uploaded_file.name)
if uploaded_file.state.name == "FAILED":
raise RuntimeError(f"비디오 처리 실패: {uploaded_file.name}")
return uploaded_file
def summarize_video(video_path: str) -> str:
uploaded_file = upload_and_wait(video_path)
response = client.models.generate_content(
model="gemini-2.5-pro",
contents=[
types.Content(
role="user",
parts=[
types.Part.from_uri(
file_uri=uploaded_file.uri,
mime_type="video/mp4",
),
types.Part.from_text(
"이 비디오의 내용을 분석하고 다음을 제공하세요: "
"1) 전체 요약 (3-5문장), "
"2) 주요 장면 목록 (타임스탬프 포함), "
"3) 등장하는 텍스트나 자막, "
"4) 핵심 키워드 5개."
),
],
)
],
)
return response.textGemini는 비디오의 시각적 프레임뿐 아니라 오디오 트랙도 함께 분석하므로, 내레이션이나 배경 음악까지 포함한 종합적인 이해가 가능하다.
비디오 콘텐츠 모더레이션
업로드된 비디오에서 부적절한 콘텐츠를 감지하는 자동 모더레이션 시스템을 구축할 수 있다.
def moderate_video_content(video_path: str) -> dict:
uploaded_file = upload_and_wait(video_path)
response = client.models.generate_content(
model="gemini-2.5-pro",
contents=[
types.Content(
role="user",
parts=[
types.Part.from_uri(
file_uri=uploaded_file.uri,
mime_type="video/mp4",
),
types.Part.from_text(
"이 비디오의 콘텐츠를 모더레이션 관점에서 분석하세요. "
"JSON으로 반환하세요: "
"is_safe (boolean), "
"categories (배열: category_name, severity [low/medium/high], "
"timestamp, description), "
"overall_risk_level (low/medium/high), "
"recommendation (approve/review/reject)."
),
],
)
],
config=types.GenerateContentConfig(
response_mime_type="application/json",
),
)
return json.loads(response.text)자동 모더레이션 결과는 최종 판단이 아닌 1차 필터로 활용하고, 고위험으로 분류된 콘텐츠는 반드시 사람이 검토하는 프로세스를 병행해야 한다.
혼합 미디어 파이프라인
실제 업무에서는 텍스트, 이미지, 문서를 하나의 분석 요청에 결합하는 경우가 많다. 예를 들어, 보험 청구 처리에서는 사고 사진, 의료 기록 PDF, 피해자 진술서를 동시에 분석해야 한다.
def process_insurance_claim(
accident_photos: list[str],
medical_report_path: str,
claim_description: str,
) -> dict:
parts = []
# 사고 사진 추가
for i, photo_path in enumerate(accident_photos):
with open(photo_path, "rb") as f:
parts.append(types.Part.from_bytes(data=f.read(), mime_type="image/jpeg"))
parts.append(types.Part.from_text(f"[사고 현장 사진 {i + 1}]"))
# 의료 보고서 PDF 업로드
medical_file = client.files.upload(file=medical_report_path)
parts.append(
types.Part.from_uri(file_uri=medical_file.uri, mime_type="application/pdf")
)
parts.append(types.Part.from_text("[의료 보고서]"))
# 청구 설명 텍스트
parts.append(
types.Part.from_text(
f"[청구인 진술]\n{claim_description}\n\n"
"위 자료를 종합적으로 분석하여 다음을 JSON으로 반환하세요: "
"damage_assessment (사진 기반 피해 분석), "
"medical_summary (의료 보고서 핵심 내용), "
"consistency_check (진술과 증거 자료 간 일관성 분석), "
"estimated_claim_amount_range, "
"risk_flags (배열: 의심스러운 점이 있다면 기재), "
"recommendation (approve/investigate/deny)."
)
)
response = client.models.generate_content(
model="gemini-2.5-pro",
contents=[types.Content(role="user", parts=parts)],
config=types.GenerateContentConfig(
response_mime_type="application/json",
),
)
return json.loads(response.text)이처럼 서로 다른 미디어 유형을 하나의 요청에 결합하면, 모델이 자료 간의 교차 참조와 일관성 검증까지 수행할 수 있다. 기존 방식에서는 각 자료를 개별 모델로 처리한 후 결과를 수작업으로 통합해야 했지만, Gemini에서는 단일 호출로 처리된다.
프로덕션 최적화
JSON 모드와 스키마 강제
프로덕션 환경에서는 응답 형식의 일관성이 중요하다. response_schema를 지정하면 Gemini가 정확히 해당 스키마에 맞는 JSON을 반환한다.
from google.genai.types import GenerateContentConfig
config = GenerateContentConfig(
response_mime_type="application/json",
response_schema={
"type": "object",
"properties": {
"product_name": {"type": "string"},
"category": {"type": "string"},
"defects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {"type": "string"},
"severity": {"type": "string", "enum": ["low", "medium", "high"]},
"location": {"type": "string"},
},
"required": ["type", "severity"],
},
},
"pass_inspection": {"type": "boolean"},
},
"required": ["product_name", "category", "defects", "pass_inspection"],
},
)스키마를 명시하면 응답 파싱 실패를 원천적으로 방지할 수 있으며, 타입 안정성도 보장된다.
배치 처리
대량의 이미지를 처리해야 할 때는 비동기 배치 처리를 활용한다.
import asyncio
from google import genai as genai_async
async def process_image_batch(image_paths: list[str], prompt: str) -> list[dict]:
semaphore = asyncio.Semaphore(5) # 동시 요청 수 제한
async def process_single(path: str) -> dict:
async with semaphore:
with open(path, "rb") as f:
image_bytes = f.read()
async_client = genai_async.Client(api_key=os.environ["GEMINI_API_KEY"])
response = await async_client.aio.models.generate_content(
model="gemini-2.5-flash",
contents=[
types.Content(
role="user",
parts=[
types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg"),
types.Part.from_text(prompt),
],
)
],
config=types.GenerateContentConfig(
response_mime_type="application/json",
),
)
return {"path": path, "result": json.loads(response.text)}
tasks = [process_single(path) for path in image_paths]
return await asyncio.gather(*tasks)Semaphore로 동시 요청 수를 제한하여 API 속도 제한(Rate Limit)에 걸리지 않도록 한다. 배치 처리 시에는 비용 효율적인 gemini-2.5-flash 모델을 사용하는 것도 좋은 전략이다.
에러 처리와 재시도
프로덕션 환경에서는 네트워크 오류나 일시적인 API 장애에 대비한 재시도 로직이 필수다.
from google.api_core import exceptions, retry
@retry.Retry(
predicate=retry.if_exception_type(
exceptions.ResourceExhausted,
exceptions.ServiceUnavailable,
exceptions.DeadlineExceeded,
),
initial=1.0,
maximum=60.0,
multiplier=2.0,
deadline=300.0,
)
def resilient_generate(contents, model="gemini-2.5-pro", config=None):
return client.models.generate_content(
model=model,
contents=contents,
config=config,
)ResourceExhausted는 속도 제한 초과, ServiceUnavailable은 서버 일시 장애, DeadlineExceeded는 요청 시간 초과를 의미한다. 지수 백오프(Exponential Backoff) 방식으로 재시도하면 대부분의 일시적 오류를 자동으로 복구할 수 있다.
비용 관리 전략
멀티모달 API는 입력 토큰에 이미지와 비디오 처리 비용이 포함되므로, 비용 관리가 중요하다.
모델 선택 전략. 단순한 이미지 분류나 텍스트 추출에는 gemini-2.5-flash를 사용하고, 복잡한 추론이나 긴 문서 분석에만 gemini-2.5-pro를 사용한다. Flash 모델은 Pro 대비 비용이 크게 낮으면서도 대부분의 실용적 작업에서 충분한 성능을 제공한다.
이미지 해상도 최적화. API에 전달하기 전에 이미지를 적절한 해상도로 리사이즈하면 토큰 소비를 줄일 수 있다. 대부분의 분석 작업에서 1024x1024 이하의 해상도로도 충분한 정확도를 얻을 수 있다.
from PIL import Image
import io
def optimize_image_for_api(image_path: str, max_dimension: int = 1024) -> bytes:
img = Image.open(image_path)
img.thumbnail((max_dimension, max_dimension), Image.LANCZOS)
buffer = io.BytesIO()
img.save(buffer, format="JPEG", quality=85)
return buffer.getvalue()컨텍스트 캐싱 활용. 동일한 시스템 프롬프트나 참조 이미지를 반복적으로 사용하는 경우, Gemini의 컨텍스트 캐싱 기능을 활용하면 중복 토큰 비용을 절감할 수 있다. 캐시된 토큰은 일반 입력 토큰 대비 할인된 가격이 적용된다.
from google.genai import types
cache = client.caches.create(
model="gemini-2.5-pro",
config=types.CreateCachedContentConfig(
display_name="product-analysis-context",
contents=[
types.Content(
role="user",
parts=[
types.Part.from_text(
"당신은 전문 제품 품질 검사관입니다. "
"다음 기준에 따라 제품 이미지를 분석하세요: ..."
),
],
)
],
ttl="3600s",
),
)
# 캐시를 참조하여 반복 호출
response = client.models.generate_content(
model="gemini-2.5-pro",
contents=[
types.Content(
role="user",
parts=[
types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg"),
types.Part.from_text("이 제품의 품질 상태를 평가하세요."),
],
)
],
config=types.GenerateContentConfig(
cached_content=cache.name,
),
)자주 묻는 질문
지원되는 이미지 형식은 무엇인가?
Gemini API는 JPEG, PNG, GIF, WebP, HEIC, HEIF 형식을 지원한다. 인라인 데이터로 전달할 때 단일 이미지의 최대 크기는 20MB이며, File API를 통해 업로드하면 더 큰 파일도 처리할 수 있다.
한 번의 요청에 이미지를 몇 장까지 포함할 수 있는가?
모델의 컨텍스트 윈도우 내에서 처리할 수 있는 만큼 포함 가능하다. Gemini 2.5 Pro 기준 약 3,600장의 이미지를 처리할 수 있다고 알려져 있으나, 실용적으로는 요청당 수십 장 이내로 제한하는 것이 레이턴시와 비용 측면에서 효율적이다.
비디오의 최대 길이는 얼마인가?
File API를 통해 업로드하는 경우 최대 2GB 크기의 비디오를 처리할 수 있다. 길이에 대한 엄격한 제한보다는 파일 크기와 컨텍스트 윈도우가 실질적인 제약 조건이 된다. 1시간 분량의 비디오도 처리 가능하지만, 처리 시간과 비용을 고려하여 필요한 구간만 추출해서 전송하는 것을 권장한다.
Flash 모델과 Pro 모델 중 어떤 것을 선택해야 하는가?
일반적인 이미지 분류, OCR, 단순한 비주얼 Q&A에는 gemini-2.5-flash가 충분하며 비용 대비 효율이 높다. 복잡한 추론, 긴 문서의 심층 분석, 여러 자료 간의 교차 검증이 필요한 경우에는 gemini-2.5-pro를 사용한다. 프로토타입 단계에서 Pro로 시작하고, 프로덕션에서 Flash로 전환하면서 품질을 비교하는 접근 방식도 효과적이다.
멀티모달 입력에서 환각(Hallucination)을 줄이는 방법은?
프롬프트에서 “이미지에 보이는 내용만 기반으로 답변하세요”, “확신할 수 없는 정보는 추측하지 말고 불확실하다고 명시하세요” 같은 지침을 포함한다. 또한 response_schema로 출력 구조를 제한하고, 각 필드에 confidence 점수를 함께 요청하면 후처리 단계에서 신뢰도가 낮은 결과를 필터링할 수 있다. 중요한 결정에 사용되는 분석이라면 반드시 사람의 검토 단계를 포함해야 한다.
민감한 데이터를 Gemini API로 전송해도 되는가?
Google의 API 데이터 사용 정책에 따르면, 유료 API를 통해 전송된 데이터는 모델 학습에 사용되지 않는다. 그러나 의료 기록, 개인 식별 정보 등 민감한 데이터를 처리할 때는 조직의 데이터 거버넌스 정책을 확인하고, 필요한 경우 Vertex AI를 통한 엔터프라이즈 환경에서의 사용을 검토해야 한다.
마무리
Gemini API의 멀티모달 기능은 이미지 분석, 문서 처리, 비디오 이해를 하나의 통합된 인터페이스로 제공하여 개발자의 생산성을 크게 높여준다. 핵심은 적절한 프롬프트 설계, JSON 모드를 활용한 구조화된 출력, 그리고 모델과 해상도의 적절한 선택을 통한 비용 최적화에 있다. 이 가이드의 코드 예제를 기반으로 자신의 도메인에 맞는 멀티모달 파이프라인을 구축해 보길 권한다.