Gemini 3.1 Pro API 가이드: 설정, 가격, 제한, 마이그레이션 (2026)

Gemini 3.1 Pro API는 긴 컨텍스트, 멀티모달 입력, 그리고 도구를 포함한 개발 워크플로를 위해 Google이 제공하는 유료 preview 경로입니다. 2026년 3월 28일 기준으로 공식 문서를 다시 확인해 보면, 현재 기본 모델은 gemini-3.1-pro-preview이고, 예전의 gemini-3-pro-preview는 이미 종료되어 새 모델로 연결됩니다. 또한 bash와 등록된 도구를 함께 쓰는 에이전트용으로 gemini-3.1-pro-preview-customtools라는 별도 endpoint도 존재합니다. 지금 필요한 것은 출시 뉴스가 아니라, 오늘 실제로 어떻게 붙이고 어떤 model ID를 써야 하며 가격과 제한을 어디서 판단해야 하는지입니다. 이 페이지는 그 판단에 맞춰 구성했습니다.

“

근거 메모: 이 글은 Google의 Gemini 3.1 Pro 모델 페이지, 가격 페이지, rate limits 페이지, API key 가이드, OpenAI compatibility 문서, Gemini 3 developer guide, release notes를 2026년 3월 28일 기준으로 다시 확인한 뒤 작성했습니다.

TL;DR

• 기본 경로는 gemini-3.1-pro-preview입니다.
• gemini-3.1-pro-preview-customtools는 도구 우선순위가 실제 문제일 때만 선택하는 것이 맞습니다.
• Gemini 3.1 Pro의 프로그래밍 API 접근은 무료가 아니지만, AI Studio에서 먼저 프롬프트와 응답을 검증하는 것은 쉽습니다.
• 200k prompt까지는 input $2.00 / output $12.00이고, 그 이상부터는 상위 가격 구간으로 넘어갑니다.
• 실제 RPM, TPM, RPD는 정적인 블로그 표보다 AI Studio에서 확인해야 합니다. Google도 그렇게 안내합니다.
• 아직 gemini-3-pro-preview를 쓰고 있다면, 지금은 이름 문제가 아니라 마이그레이션 문제입니다.

가장 빠르게 Gemini 3.1 Pro 첫 요청을 띄우는 방법

Gemini API key 생성의 중심은 지금도 Google AI Studio입니다. 가장 실무적인 순서는 간단합니다. AI Studio를 열고, 사용할 프로젝트를 생성하거나 import하고, 그 안에서 API key를 만든 다음, 로컬에 GEMINI_API_KEY 또는 GOOGLE_API_KEY를 설정하면 됩니다. Google의 API key 가이드는 공식 라이브러리가 두 환경 변수를 모두 자동으로 읽고, 둘 다 있을 때는 GOOGLE_API_KEY가 우선한다고 설명합니다. 지금 당장은 프롬프트 감을 보는 것이 목적이라면 AI Studio에서 멈춰도 충분합니다. Gemini 3.1 Pro를 코드에서 호출하려면 billing 연결을 기본 전제로 두는 편이 맞습니다.

대부분의 팀에게 가장 깔끔한 시작점은 공식 GenAI SDK입니다. Python, JavaScript, REST 모두 최소 구성으로 바로 시도할 수 있습니다.

python
from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.1-pro-preview",
    contents="Review this API design and list the main tradeoffs.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="medium")
    ),
)

print(response.text)

javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const response = await ai.models.generateContent({
  model: "gemini-3.1-pro-preview",
  contents: "Review this API design and list the main tradeoffs.",
  config: {
    thinkingConfig: {
      thinkingLevel: "medium",
    },
  },
});

console.log(response.text);

bash
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": "Review this API design and list the main tradeoffs."}]
    }],
    "generationConfig": {
      "thinkingConfig": {
        "thinkingLevel": "medium"
      }
    }
  }'

중요한 것은 단순히 호출이 성공하는지가 아니라, 명시적인 model과 reasoning 설정으로 호출하는가입니다. Gemini 3 developer guide에 따르면 Gemini 3.1 Pro 계열은 high가 기본 dynamic reasoning level입니다. reasoning을 완전히 기본값에 맡기면 지연 시간과 output token 비용까지 함께 기본값에 맡기는 셈이 됩니다.

prompt보다 먼저 골라야 하는 것은 model path입니다

이 단계의 핵심 결정은 prompt engineering이 아니라 모델 경로 선택입니다.

기본 경로는 gemini-3.1-pro-preview입니다. Google의 모델 페이지는 이 모델을 Gemini 3 Pro 계열을 더 다듬은 preview 모델로 설명하며, thinking, token efficiency, software engineering, agentic workflow에서의 사용성을 강조합니다. 입력은 text, image, video, audio, PDF를 받고, 출력은 text입니다. 그리고 Batch API, caching, code execution, function calling, search grounding, Maps grounding, structured outputs, URL context를 지원합니다. 큰 문서 분석, 멀티모달 reasoning, 복합 입력에서의 구조화 추출, 도구가 들어가는 워크플로에는 충분히 의미 있는 선택입니다.

반대로 한계도 분명합니다. Gemini 3.1 Pro Preview는 image generation, audio generation, Live API를 지원하지 않습니다. 실제 업무가 이미지 출력, 실시간 음성 대화, 또는 최대한 싸게 대량 텍스트 처리를 돌리는 일이라면, 처음부터 Pro를 기본값으로 둘 이유가 없습니다. 그런 경우는 Flash, Flash-Lite, image 계열, live 계열 모델이 더 자연스럽습니다. 무료 API 진입로가 필요하다면 먼저 Gemini API free tier 가이드를 보는 편이 낫습니다.

다른 갈림길은 gemini-3.1-pro-preview-customtools입니다. 이것은 별도의 더 비싼 모델이라기보다, bash와 custom tools를 함께 쓰는 에이전트용 endpoint입니다. Google의 모델 페이지는 view_file, search_code 같은 도구를 더 잘 우선시할 수 있다고 설명하는 동시에, 이런 도구가 별 이점이 없는 작업에서는 quality fluctuation이 생길 수 있다고도 적습니다. 즉, 도구 우선순위가 진짜 문제일 때만 customtools가 답입니다. 일반 reasoning, 채팅, 문서 분석이 중심이라면 standard가 더 자연스럽습니다. 더 깊게 보고 싶다면 별도 문서인 Gemini 3.1 Pro customtools 가이드를 참고하면 됩니다.

분명하게 받아들여야 할 사실도 있습니다. Google의 release notes는 gemini-3-pro-preview가 2026년 3월 9일에 shut down 되었고, gemini-3.1-pro-preview를 가리키게 되었다고 적습니다. 오래된 alias가 일부 코드를 살려 주더라도, 새 구현은 현재 model string을 명시적으로 써야 합니다.

가격과 제한은 "그럴듯한 표"보다 실제 운영 기준으로 봐야 합니다

Gemini 3.1 Pro 가격에서 중요한 것은 prompt 길이가 임계값을 넘는 순간 가격대가 바뀐다는 점입니다. 현재 Google pricing 페이지 기준으로 200k tokens까지의 표준 가격은 다음과 같습니다.

이 임계값이 중요한 이유는 Gemini 3.1 Pro의 강점이 1,048,576 tokens 입력 창에 있기 때문입니다. 많은 글이 1M context만 강조하고 끝나지만, 실제로 긴 컨텍스트를 자주 쓰면 비용 구조 자체가 달라집니다. 실무에서는 벤치마크 몇 줄보다 아래 네 가지 레버가 먼저 중요해집니다.

1. 일상적인 prompt는 가능하면 200k 아래에 유지합니다.
2. 실시간이 필요 없는 작업은 Batch로 보냅니다.
3. 반복해서 보내는 큰 instruction이나 reference block에는 caching을 씁니다.
4. thinking level을 비용 레버로 취급합니다.

Google의 pricing 페이지는 Gemini 3.1 Pro에서 caching이 지원된다는 점과 search grounding이 별도 비용을 가진다는 점도 확인해 줍니다. 현재 웹 정보가 정말 필요한 작업이라면 grounding이 가치가 있지만, 그렇지 않다면 불필요한 비용 증폭기로 바뀌기 쉽습니다.

제한은 더 조심해서 봐야 합니다. Google의 rate limits 페이지는 실제 API limits가 usage tier와 account 상태에 따라 달라지며, AI Studio에서 active limits를 확인해야 한다고 명시합니다. 즉, 이 주제에서는 정적인 블로그 표를 진실처럼 받아들이는 것이 가장 위험합니다. 그래도 공식 페이지가 분명히 말하는 운영 규칙은 있습니다.

• rate limiting은 RPM, TPM, RPD로 평가됩니다
• quota는 API key가 아니라 project 기준으로 적용됩니다
• RPD는 Pacific 자정에 리셋됩니다
• preview 모델은 제한이 더 엄격합니다
• 현재 active limits는 AI Studio에 있습니다

같은 페이지는 tier 경로도 설명합니다. Tier 1은 billing을 연결한 시점부터 시작되고, Tier 2는 결제 이력과 일정 시간이 필요하며, Tier 3는 더 높은 spend와 이력이 필요합니다. capacity planning을 진지하게 한다면 공식 페이지로 규칙을 이해한 뒤, 실제 판단은 AI Studio 숫자로 해야 합니다.

2026년 3월 12일 release notes에 따르면 AI Studio에는 project-level spend caps도 추가되었습니다. Gemini 3.1 Pro를 팀에 열어 둘 계획이라면 예산 가드레일로 먼저 설정해 둘 만합니다.

thinking, 긴 컨텍스트, 캐시를 방치하면 비용이 커집니다

Gemini 3.1 Pro는 API 표면이 깔끔하다고 해서 완전히 기본값에 맡길 모델이 아닙니다. Gemini 3 developer guide는 Gemini 3.1 Pro에서 low, medium, high thinking level을 지원하며, high가 기본 dynamic level이라고 설명합니다. 동시에 thinking_level과 오래된 thinking_budget를 같은 요청에 함께 넣으면 400이 난다고도 적습니다. 이건 마이그레이션에서 아주 중요합니다.

실무적으로는 medium을 일상 작업의 첫 기본값으로 놓고, 작업 난도에 따라 낮추거나 높이는 편이 다루기 쉽습니다. 이것은 Google의 그대로인 문장이라기보다 문서에 나온 동작과 비용 구조에서 나온 엔지니어링 판단입니다. 추출, 분류, 짧은 변환처럼 깊은 reasoning이 핵심이 아닌 작업은 low부터 시작하는 것이 자연스럽습니다. 반대로 복잡한 분석, 큰 코드베이스 리뷰, 다단 reasoning처럼 Pro의 강점을 진짜로 쓰는 업무만 high를 명시적으로 선택하는 편이 낫습니다.

긴 컨텍스트도 마찬가지입니다. 1M token window가 있다는 사실은 맞지만, 중요한 질문은 "들어가느냐"가 아니라 "얼마나 자주 긴 컨텍스트 요금을 낼 것인가"와 "어떤 부분을 먼저 캐시하거나 요약할 수 있는가"입니다. 매번 동일한 거대한 system prompt, 문서 묶음, repo context를 다시 보내고 있다면 가장 게으른 구현이 가장 비싼 구현이 됩니다.

thinking 운용을 더 깊게 보고 싶다면 별도 문서인 Gemini 3.1 Pro thinking level 가이드를 보면 됩니다. 이 총괄 가이드 수준에서는 reasoning을 명시하고, 200k 임계값을 잊지 말고, 긴 컨텍스트를 "되니까 쓴다" 수준으로 습관화하지 않는 것만 기억하면 충분합니다.

Gemini 3 Pro Preview 또는 OpenAI SDK에서 넘어온다면

예전에 Gemini 3 Pro Preview를 썼다면 마이그레이션의 핵심은 단순합니다. 2026년 3월 9일 release notes에서 Google은 이 모델이 shut down 되었고 gemini-3-pro-preview가 이제 gemini-3.1-pro-preview를 가리킨다고 적었습니다. 실무적으로는 코드의 model string을 현재 값으로 바꾸고, thinking에 대한 가정을 점검하고, workload를 standard로 유지할지 -customtools로 옮길지 판단하는 것이 맞습니다.

이미 OpenAI SDK를 많이 쓰는 팀이라면 Google의 OpenAI compatibility layer가 가장 마찰이 적은 다리입니다. 공식 문서는 API key, base URL, model name만 바꾸면 OpenAI의 Python, JavaScript 라이브러리에서 Gemini를 부를 수 있다고 설명합니다. 기존 OpenAI client stack 안에서 먼저 Gemini를 시험해 보고 싶은 팀에게 실용적인 경로입니다.

python
from openai import OpenAI

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

response = client.chat.completions.create(
    model="gemini-3.1-pro-preview",
    reasoning_effort="medium",
    messages=[
        {"role": "user", "content": "Summarize the migration risks in this API design."}
    ]
)

print(response.choices[0].message.content)

이 compatibility 문서는 reasoning_effort와 Gemini reasoning control의 대응도 보여 줍니다. minimal과 low는 Gemini low, medium은 medium, high는 high에 대응합니다. 핵심 규칙은 native path와 같습니다. 기능이 겹치는 reasoning 설정을 두 겹으로 얹지 마세요. OpenAI 호환 경로에서 reasoning_effort를 쓰고 있다면, 별도의 Gemini thinking 설정을 또 올리지 않는 편이 안전합니다.

오래된 튜토리얼이나 내부 스니펫을 정리하기에도 지금이 좋은 시점입니다. preview 모델 계열에서는 낡은 model name 하나보다, 그 model name과 함께 굳어 있는 낡은 파라미터와 비용 가정이 더 위험한 경우가 많기 때문입니다. 현재 model string으로 통일하고, 대표 prompt를 AI Studio에서 다시 검증한 뒤 production으로 보내는 편이 가장 안전합니다.

언제 Gemini 3.1 Pro를 쓰고, 언제 다른 길을 택해야 하는가

Gemini 3.1 Pro가 맞는 API는 강한 reasoning, 긴 컨텍스트, tool-aware 멀티모달 표면이 동시에 필요한 경우입니다. 큰 문서 리뷰, 큰 코드베이스 분석, 복잡한 mixed input에서의 구조화 추출, code execution, function calling, grounding, URL context가 필요한 agent workflow에서 이 조합은 의미가 큽니다. 또한 preview 모델과 stricter limits를 감수할 수 있는 팀에게도 맞습니다.

gemini-3.1-pro-preview-customtools는 bash와 등록 도구를 함께 쓰는 에이전트에서, 문제의 핵심이 tool priority일 때 선택하면 됩니다. 반대로 지연과 비용 민감도가 더 중요하다면 더 저렴한 Flash나 Flash-Lite가 맞습니다. image output이나 live audio가 필요하면 다른 모델 계열로 가야 합니다. 그리고 출발점이 "무료 API로 먼저 시험해 보고 싶다"라면 Pro를 기본 선택지로 두지 않는 것이 좋고, 그 경우에는 Gemini API free tier 가이드와 Gemini API rate limits 가이드를 먼저 보는 편이 더 실용적입니다.

Gemini, OpenAI, Claude를 하나의 routing layer 뒤에서 비교하고 싶다면 laozhang.ai 같은 게이트웨이가 편리할 수 있습니다. 다만 확인해야 할 것은 모델 이름 나열이 아니라, 정말 필요한 variant와 feature가 그대로 노출되는가입니다. customtools나 preview 전용 동작이 필요할수록 이 점이 더 중요합니다.

결론은 단순합니다. Gemini 3.1 Pro API는 그것의 실제 모양이 필요한 경우에만 값어치가 있습니다. 진짜 일이 "싸고 빠른 고처리량 텍스트"라면 Pro 가격을 낼 이유가 없습니다. 반대로 "거대한 멀티모달 컨텍스트, structured output, grounding, 신뢰할 수 있는 multi-step execution"이 필요하다면 Gemini 3.1 Pro는 여전히 강한 현재 선택지입니다.

FAQ

Gemini 3.1 Pro API는 무료인가요?
무료가 아닙니다. Google의 현재 pricing 페이지에는 Gemini 3.1 Pro Preview용 free API tier가 없습니다. AI Studio에서 시험은 가능하지만 프로그래밍 호출은 유료입니다.

gemini-3-pro-preview는 아직 동작하나요?
2026년 3월 9일에 종료되었습니다. release notes에 따르면 지금은 gemini-3.1-pro-preview를 가리키지만, 새 코드는 현재 model string을 명시적으로 써야 합니다.

모든 프로젝트에서 gemini-3.1-pro-preview-customtools를 써야 하나요?
아닙니다. custom tool 우선순위가 실제 문제일 때만 쓰는 것이 맞습니다. Google도 해당 이점이 없는 작업에서는 quality fluctuation 가능성을 언급합니다.

내 실제 RPM, TPM, RPD는 어디서 보나요?
AI Studio입니다. Google의 rate limits 페이지도 active limits를 거기서 확인하라고 안내합니다.

OpenAI SDK로 Gemini 3.1 Pro를 부를 수 있나요?
가능합니다. Google의 OpenAI compatibility 문서는 API key, base URL, model name만 바꾸면 된다고 설명합니다.

Gemini 3.1 Pro는 이미지 생성이나 Live API를 지원하나요?
지원하지 않습니다. 현재 모델 페이지에서는 image generation, audio generation, Live API가 unsupported입니다.