Gemini 3.1 Pro API 실전 — 1M 컨텍스트 + 멀티모달 제대로 써보기

"RAG 파이프라인 다 걷어내고 파일 통째로 넣어봤더니 됩니다."

이번에 다루는 것:
→ Gemini 3.1 Pro가 2.5 Pro와 실제로 다른 점 (모델 ID 주의 포함)
→ 설치 및 첫 API 호출 (Python / JavaScript / REST)
→ 1M 컨텍스트 실전 — 코드베이스·대용량 문서 통째로 넣기
→ 멀티모달 실전 — 이미지·PDF·오디오 한 번에 처리하기
→ thinking_level 파라미터로 속도·비용·성능 조절하기
→ Files API + Context Caching으로 비용 최적화

---

배경 — Gemini 3.1 Pro, 뭐가 달라졌나

2026년 2월 19일 출시된 Gemini 3.1 Pro는 Gemini 3 Pro의 직계 업그레이드입니다. 그리고 Gemini 3 Pro Preview는 2026년 3월 9일에 이미 셧다운됐습니다. 아직 gemini-3-pro-preview를 쓰고 있다면 지금 당장 모델 ID를 바꿔야 합니다.

Gemini 2.5 Pro 대비 달라진 것:
→ thinking_budget 파라미터 삭제됨 (400 에러 발생)
→ thinking_level 파라미터로 교체 (LOW / MEDIUM / HIGH)
→ MEDIUM 레벨 신규 추가 — 비용·속도·성능 중간값
→ ARC-AGI-2 벤치마크 77.1% (2.5 Pro 대비 2배 이상)
→ media_resolution 파라미터 신규 추가 — 멀티모달 해상도 제어

Gemini 3 Pro Preview 대비 달라진 것:
→ 토큰 효율성 개선 (같은 작업에 더 적은 토큰)
→ 소프트웨어 엔지니어링·에이전트 성능 향상
→ 사실 일관성(factual consistency) 강화
→ 모델 ID: gemini-3.1-pro-preview (3 → 3.1 변경)

핵심 스펙 한눈에 보기:

모델 ID:     gemini-3.1-pro-preview
컨텍스트:    입력 1,048,576 토큰 / 출력 64,000 토큰
지식 컷오프: 2025년 1월
가격:        입력 $2 / 출력 $12 (200k 이하)
             입력 $4 / 출력 $18 (200k 초과)
             Batch: 위 가격의 50%
입력 포맷:   텍스트, 이미지, 오디오, 비디오, PDF
지원 기능:   Function Calling, Structured Output, Code Execution,
             Search Grounding, URL Context, Batch API, Context Caching

---

비교 — Gemini 3.1 Pro vs 다른 프론티어 모델

Gemini 3.1 Pro:
→ 1M 컨텍스트 (900장 이미지 or 1시간 영상)
→ 입력 $2/1M 토큰 — 가장 저렴한 프론티어급
→ 과학적 추론 GPQA Diamond 94.3% (현재 1위)
→ 이미지·오디오·비디오·PDF 네이티브 멀티모달
→ 단점: 산문 품질은 Claude가 우위, 구조화 출력 속도는 GPT가 빠름

Claude Opus 4.7:
→ 컨텍스트 200k, 산문·코딩 최고 품질
→ 입력 $15/1M 토큰 — 7.5배 비쌈

GPT-5.5:
→ 전방위 강자, 에이전틱 실행 강함
→ 입력 $2.50/1M 토큰

---

실전 1 — 설치 및 첫 API 호출

# Python SDK 설치
pip install google-genai

# API 키 등록 (Google AI Studio에서 발급)
export GEMINI_API_KEY="AIza..."

가장 빠른 첫 호출입니다.

# Python — Hello Gemini 3.1 Pro
from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.1-pro-preview",   # ← 반드시 이 ID 사용
    contents="이 Python 코드의 시간복잡도를 분석해줘: [코드]",
)

print(response.text)

JavaScript(Node.js)도 동일합니다.

// JavaScript — 기본 호출
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const response = await ai.models.generateContent({
  model: "gemini-3.1-pro-preview",
  contents: "이 Python 코드의 시간복잡도를 분석해줘: [코드]",
});

console.log(response.text);

REST로도 바로 쓸 수 있습니다.

# REST — curl 한 줄
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"contents": [{"parts": [{"text": "안녕, Gemini 3.1 Pro!"}]}]}'

자주 겪는 초기 에러:
→ 400 Bad Request + thinking_budget 언급 → 파라미터 삭제 후 thinking_level 사용
→ 404 Model not found → gemini-3-pro-preview → gemini-3.1-pro-preview 로 변경
→ 403 Billing not set up → AI Studio는 테스트만 가능, API 호출은 결제 계정 필요
→ 400 context_length_exceeded → 1,048,576 토큰 초과, Files API로 분할 필요

---

실전 2 — 1M 컨텍스트 실전: 대형 코드베이스 통째로 분석

1M 토큰은 텍스트 기준 약 750만 단어입니다. 웬만한 중형 프로젝트 전체 소스코드가 들어갑니다.

# Python — 코드베이스 전체 분석 에이전트
import os
from google import genai
from google.genai import types

client = genai.Client()

def load_codebase(repo_path: str, extensions=(".py", ".ts", ".go")) -> str:
    """저장소 파일을 하나의 문자열로 합침"""
    files = []
    for root, _, filenames in os.walk(repo_path):
        if ".git" in root or "node_modules" in root:
            continue
        for fname in filenames:
            if fname.endswith(extensions):
                fpath = os.path.join(root, fname)
                with open(fpath) as f:
                    files.append(f"### {fpath}\n{f.read()}")
    return "\n\n".join(files)

codebase = load_codebase("./my-backend")

response = client.models.generate_content(
    model="gemini-3.1-pro-preview",
    contents=f"""
다음은 프로젝트 전체 소스코드입니다:

{codebase}

---
위 코드베이스를 분석해서:
1. 인증/인가 로직의 보안 취약점
2. DB 쿼리 최적화 여지 (N+1 포함)
3. 에러 핸들링이 누락된 부분
을 각각 파일명과 라인 번호와 함께 정리해줘.
""",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="HIGH"),
        max_output_tokens=64000,
    )
)

print(response.text)

컨텍스트가 200k 토큰을 넘으면 가격이 올라갑니다. Files API와 Context Caching을 함께 쓰면 비용을 줄일 수 있습니다.

# Python — Files API로 대용량 파일 업로드 후 재사용
import pathlib

# 1. 파일 업로드 (한 번만)
uploaded_file = client.files.upload(
    file=pathlib.Path("./large_codebase.txt"),
    config={"mime_type": "text/plain"},
)
print(f"파일 업로드 완료: {uploaded_file.uri}")

# 2. 업로드된 파일 URI로 여러 질문 가능 (재업로드 불필요)
for question in [
    "인증 로직 취약점 분석해줘",
    "성능 병목 찾아줘",
    "테스트 커버리지 낮은 모듈 뽑아줘",
]:
    response = client.models.generate_content(
        model="gemini-3.1-pro-preview",
        contents=[
            types.Part.from_uri(
                file_uri=uploaded_file.uri,
                mime_type="text/plain",
            ),
            question,
        ],
    )
    print(f"\n[질문] {question}")
    print(response.text)

1M 컨텍스트 실전 팁:
→ 파일 구분자 (### filepath) 명시 → 라인 번호 참조 정확도 상승
→ 200k 토큰 이하 유지 → $2/$12 요금 구간 유지 (Files API + Caching 활용)
→ 한 번 업로드한 파일은 URI로 재사용 → 중복 토큰 비용 0
→ 1M 초과 시 400 에러 — 파일 분할 또는 chunking 전략 필요
→ RAG가 필요해지는 진짜 기준: 1M 넘거나 실시간 업데이트가 필요한 경우

---

실전 3 — 멀티모달 실전: 이미지 + PDF + 오디오 한 번에

Gemini 3.1 Pro는 멀티모달이 애드온이 아니라 네이티브입니다. 단일 API 호출에 텍스트·이미지·PDF·오디오를 섞어서 보낼 수 있습니다.

# Python — 스크린샷 + 코드파일 + 명세서 PDF 동시 분석
import pathlib
from google import genai
from google.genai import types

client = genai.Client()

# 이미지 파일 로드
screenshot = pathlib.Path("./error_screenshot.png").read_bytes()

# PDF 로드
spec_pdf = pathlib.Path("./api_spec.pdf").read_bytes()

response = client.models.generate_content(
    model="gemini-3.1-pro-preview",
    contents=[
        # 1. 에러 스크린샷
        types.Part.from_bytes(
            data=screenshot,
            mime_type="image/png",
        ),
        # 2. API 명세 PDF
        types.Part.from_bytes(
            data=spec_pdf,
            mime_type="application/pdf",
        ),
        # 3. 텍스트 질문
        "스크린샷의 에러가 API 명세의 어느 부분과 불일치하는지 찾아줘. "
        "불일치 항목을 표로 정리하고 수정 코드를 제안해줘.",
    ],
    config=types.GenerateContentConfig(
        # media_resolution으로 이미지 토큰 수 제어
        # LOW=280, MEDIUM=560, HIGH=1120 토큰/이미지
        media_resolution=types.MediaResolution.MEDIA_RESOLUTION_HIGH,
        thinking_config=types.ThinkingConfig(thinking_level="MEDIUM"),
    )
)

print(response.text)

비디오 파일 분석도 가능합니다.

# Python — 비디오 파일 분석 (최대 1시간)
video_file = pathlib.Path("./code_review_recording.mp4").read_bytes()

response = client.models.generate_content(
    model="gemini-3.1-pro-preview",
    contents=[
        types.Part.from_bytes(
            data=video_file,
            mime_type="video/mp4",
        ),
        "이 코드 리뷰 영상에서 리뷰어가 지적한 문제점들을 타임스탬프와 함께 정리해줘.",
    ],
)
print(response.text)

멀티모달 입력 포맷 치트시트:
→ 이미지: JPEG, PNG, GIF, WebP, HEIC/HEIF
→ 오디오: MP3, WAV, FLAC, AAC, OGG, OPUS
→ 비디오: MP4, MPEG, MOV, AVI, WebM
→ 문서: PDF (텍스트/스캔 모두 가능)
→ 1M 토큰 ≈ 이미지 900장 or 영상 1시간
→ media_resolution 미지정 시 모델이 자동 최적화
→ 이미지 생성은 불가 — Nano Banana 모델 사용 필요

---

실전 4 — thinking_level로 속도·비용·성능 조절하기

Gemini 3.1 Pro의 thinking은 기본값이 HIGH입니다. 용도에 따라 조절하면 속도와 비용을 크게 줄일 수 있습니다.

# Python — thinking_level 비교
from google import genai
from google.genai import types
import time

client = genai.Client()

PROMPT = "주어진 배열에서 중복을 제거하고 정렬하는 Python 함수를 작성해줘."

for level in ["LOW", "MEDIUM", "HIGH"]:
    start = time.time()
    response = client.models.generate_content(
        model="gemini-3.1-pro-preview",
        contents=PROMPT,
        config=types.GenerateContentConfig(
            thinking_config=types.ThinkingConfig(
                thinking_level=level,  # LOW / MEDIUM / HIGH
            ),
        )
    )
    elapsed = time.time() - start
    tokens = response.usage_metadata.total_token_count
    print(f"[{level}] {elapsed:.1f}초 / {tokens} 토큰")
    print(response.text[:200])
    print("---")

thinking_level 선택 가이드:
→ LOW:    분류, 단순 Q&A, 자동완성 → 가장 빠름, 최저 비용
→ MEDIUM: 일반 코드 생성, 문서 요약 → 균형잡힌 선택 (3.1에서 신규 추가)
→ HIGH:   복잡한 추론, 보안 분석, 수학 → 최고 품질, 느리고 비쌈 (기본값)
→ 주의: thinking_budget 파라미터는 삭제됨. 쓰면 400 에러

---

마무리 / 결론

✅ 이럴 때 써라
→ 전체 코드베이스를 RAG 없이 통째로 분석하고 싶을 때
→ 이미지·PDF·오디오·영상을 단일 API 호출로 처리할 때
→ 프론티어급 모델 중 비용을 최소화해야 할 때 (Claude 대비 ~7배 저렴)
→ 과학적 추론, 알고리즘 설계, 대규모 데이터 합성
→ Google Cloud / Vertex AI 생태계와 깊이 연동할 때

❌ 이럴 때 쓰지 마라
→ 자연스러운 산문 작성 — Claude Opus가 확실히 우위
→ 빠른 구조화 JSON 출력이 핵심일 때 — GPT-5.5가 유리
→ 이미지 생성이 필요할 때 — Nano Banana 모델 사용
→ 실시간 음성 대화 — Live API 미지원, 별도 모델 필요
→ 1M 토큰 미만의 단순 태스크를 대량 처리 — Flash가 훨씬 저렴

---