[튜토리얼] Gemini 3.1 Pro API 시작 가이드 — 65K 토큰 출력 활용하기

Gemini 3.1 Pro의 차별점

Gemini 3.1 Pro는 100만 토큰 입력과 65,000 토큰 출력을 지원합니다. 특히 65K 출력은 경쟁 모델 대비 수 배 수준으로, 긴 코드 파일이나 상세 문서를 한 번에 생성하는 데 강점이 있습니다.

사전 준비

API 키 발급

Google AI Studio에 접속
"Get API Key" 클릭
프로젝트 생성 후 API 키 복사

패키지 설치

pip install google-genai

환경 변수 설정

export GEMINI_API_KEY="your-api-key-here"

기본 사용법

Python 클라이언트 설정

from google import genai

client = genai.Client(api_key="YOUR_API_KEY")

response = client.models.generate_content(
    model="gemini-3.1-pro",
    contents="2026년 AI 산업의 주요 트렌드를 분석해주세요."
)

print(response.text)

시스템 프롬프트 사용

response = client.models.generate_content(
    model="gemini-3.1-pro",
    config={
        "system_instruction": "당신은 AI 산업 전문 분석가입니다. 데이터 기반의 객관적인 분석을 제공합니다.",
        "max_output_tokens": 65000,
    },
    contents="HBM 반도체 시장의 2026년 전망을 상세히 분석해주세요."
)

65K 출력 활용 예제

예제 1: 전체 기술 문서 생성

response = client.models.generate_content(
    model="gemini-3.1-pro",
    config={"max_output_tokens": 65000},
    contents="""다음 프로젝트의 기술 문서를 작성해주세요:
    - 프로젝트: AI 기반 고객 서비스 챗봇
    - 기술 스택: Next.js, FastAPI, PostgreSQL, Claude API
    - 포함 항목: 아키텍처 설계, API 명세, 데이터베이스 스키마,
      배포 가이드, 모니터링 설정"""
)

예제 2: 대규모 코드베이스 분석 + 리팩토링 제안

# 1M 토큰 입력으로 전체 코드베이스 로드
with open("codebase_dump.txt", "r") as f:
    codebase = f.read()

response = client.models.generate_content(
    model="gemini-3.1-pro",
    config={"max_output_tokens": 65000},
    contents=f"""다음 코드베이스를 분석하고:
    1. 아키텍처 다이어그램 (텍스트)
    2. 주요 문제점 목록
    3. 리팩토링 계획
    4. 우선순위별 수정 코드

    코드베이스:
    {codebase}"""
)

예제 3: 멀티모달 — 이미지 분석

import base64

with open("architecture_diagram.png", "rb") as f:
    image_data = base64.b64encode(f.read()).decode()

response = client.models.generate_content(
    model="gemini-3.1-pro",
    contents=[
        {"text": "이 아키텍처 다이어그램을 분석하고 개선점을 제안해주세요."},
        {"inline_data": {"mime_type": "image/png", "data": image_data}}
    ]
)

비용 최적화 팁

출력 토큰 제한: 항상 필요한 만큼만 max_output_tokens 설정
캐싱 활용: 반복적인 시스템 프롬프트는 context caching 사용
모델 선택: 단순 작업에는 Gemini 3.1 Flash 사용 (비용 1/10)

Claude/GPT와의 API 비교

항목	Gemini 3.1 Pro	Claude Opus 4.6	GPT-5.4
최대 입력	1M 토큰	1M 토큰 (베타)	1M 토큰
최대 출력	65K 토큰	~8K 토큰	~16K 토큰
이미지 입력	O	O	O
무료 티어	O (제한적)	X	X

출력 길이가 중요한 사용 사례(장문 문서, 전체 코드 파일)에서는 Gemini 3.1 Pro가 명확한 이점을 가집니다.

결론

Gemini 3.1 Pro의 65K 출력은 "AI에게 질문"하는 것을 넘어 "AI에게 프로젝트를 맡기는" 사용 패턴을 가능하게 합니다. API 시작은 간단하니, 직접 테스트해보시기 바랍니다.