Gemini 3.1 Pro API: Setup, Pricing, Limits, and Migration Guide

As of October 10, 2026, Gemini 3.1 Pro is still a Preview model on the Gemini API, and it has no free API tier. The model ID is gemini-3.1-pro-preview (plus gemini-3.1-pro-preview-customtools for agents), Google lists no shutdown date for it, and no newer Pro model has replaced it: the newest Gemini API releases are Gemini 3.8 Flash and 3.6 Flash. Standard pricing is $2.00 input / $12.00 output per 1M tokens for prompts up to 200k tokens and $4.00 / $18.00 above that. Batch and Flex cost half, and Priority costs 1.8 times Standard. If you need a free key for prototyping, or your workload doesn't need Pro, Gemini 3.8 Flash is generally available, has a free tier, and costs $0.75 / $3.75 through December 31, 2026.

TL;DR

• Use gemini-3.1-pro-preview as the default Gemini 3.1 Pro API path. Use -customtools only when your agent mixes bash with registered tools and tool priority is the problem.
• A free Gemini 3.1 Pro API key doesn't exist. Creating a key is free, but calls to this model are billed. The free API tier covers Flash and Flash-Lite models instead.
• Output price includes thinking tokens, so the thinking level is a cost setting as much as a quality setting.
• Rate limits are per project and shown in AI Studio. Google publishes no fixed RPM table for your account, and preview models can get tighter limits.
• If you still send gemini-3-pro-preview, temperature, or a thinking_budget next to thinking_level, follow the migration checklist below.

The fastest way to get a Gemini 3.1 Pro request working

The key still comes from Google AI Studio. Open AI Studio, pick or create the Google Cloud project you want to bill, create an API key there, and set GEMINI_API_KEY or GOOGLE_API_KEY locally. The official libraries pick up either variable automatically, and GOOGLE_API_KEY wins if both are set. Keys created in AI Studio since May 28, 2026 are auth keys bound to a service account and restricted to the Gemini API, and the Gemini API rejects requests from unrestricted standard keys, so an older unrestricted key may be rejected.

Before the first Pro call, the project needs a paid billing setup, because gemini-3.1-pro-preview has no free tier. New accounts default to Prepay: you buy credits first (minimum $5) and usage is deducted in near real time. The Gemini API billing tiers guide walks through Prepay, Postpay, and the "no credits" states that block a first call.

The Gemini API also only serves the countries on Google's Gemini API available-regions list. The list includes the US, Japan, South Korea, Spain, Vietnam, and Taiwan; mainland China, Hong Kong, and Russia are not on it.

The samples below follow the generateContent request shape in Google's documentation and set the model and thinking level explicitly. They were not run for the October 2026 update, so test them against your own key before shipping. Google's newer docs examples use the Interactions API (client.interactions.create, REST POST /v1beta/interactions), which keeps multi-turn state on the server; generateContent remains documented.

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)

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);

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"
      }
    }
  }'

None of the samples set temperature. Google deprecated temperature, top_p, and top_k on July 21, 2026, so leaving them out is the current default rather than an omission. If you skip the thinking setting, Gemini 3.1 Pro defaults to high, which is the slowest and most output-heavy level.

Pick the right model ID before you optimize anything

The current default path is gemini-3.1-pro-preview. Google's Gemini 3.1 Pro model page describes it as an improvement on the Gemini 3 Pro series with "better thinking, improved token efficiency," tuned for software engineering and "agentic workflows requiring precise tool usage." It accepts text, image, video, audio, and PDF input, takes up to 1,048,576 input tokens, and returns up to 65,536 output tokens of text. Batch API, Flex inference, Priority inference, caching, code execution, function calling, Search and Maps grounding, structured outputs, thinking, and URL context are all supported; File Search is supported in AI Studio only.

It does not support image generation, audio generation, or the Live API. If your job is image output, real-time voice, or the cheapest high-volume text pipeline, start with a Flash, Flash-Lite, image, or Live model instead.

The second ID is gemini-3.1-pro-preview-customtools. It has the same price and context window as the standard model. Google built it for agents that have both bash access and registered tools: it is better at choosing custom tools such as view_file or search_code, and Google warns that quality may fluctuate in workloads that don't benefit from those tools. Use it when custom-tool priority is the reliability problem you're solving; otherwise stay on the standard ID. The Gemini 3.1 Pro customtools guide covers that choice in more depth.

Three status facts settle most "which ID?" questions as of October 10, 2026:

• Gemini 3.1 Pro is still Preview. Google's Gemini API deprecations page lists gemini-3.1-pro-preview as released February 19, 2026 with "No shutdown date announced" and no replacement. Preview models can be deprecated with at least two weeks' notice.
• There is no newer Pro model. The models overview lists Gemini 3.1 Pro as the only Gemini 3 Pro text model. No Gemini 3.6 Pro, 3.8 Pro, or Gemini 4 model exists on the Gemini API.
• Old Pro IDs redirect here. gemini-3-pro-preview was shut down on March 9, 2026 with gemini-3.1-pro-preview as its replacement, and the retired Gemini 2.5 Pro previews (03-25, 05-06, 06-05) also point to it. Aliasing keeps old calls alive, but new code should name the current ID.

On the Flash side, the current models are gemini-3.8-flash (GA September 2, 2026) and gemini-3.6-flash (GA July 21, 2026). On October 8, 2026, gemini-3.7-flash started routing to gemini-3.8-flash and gemini-3.5-flash to gemini-3.6-flash. gemini-3-flash-preview is labeled legacy with gemini-3.6-flash as its replacement. Since September 18, 2026, Gemini 2.5 models are limited to existing users, and Google tells new projects to use 3.5 Flash-Lite or 3.8 Flash.

Pricing and limits without the guesswork

Gemini 3.1 Pro pricing depends on two things: the service tier you call and whether your prompt crosses 200k tokens. These are the paid rates on Google's Gemini API pricing page as of October 10, 2026, per 1M tokens. The same prices apply to gemini-3.1-pro-preview-customtools.

Grounding with Google Search and Google Maps is not on the free tier. On paid accounts, 5,000 grounded requests per month are free, shared across Gemini 3 and later models, then each 1,000 requests cost $14. For other Gemini models, the Gemini API pricing guide has the full table.

The 200k line matters because the 1M-token window is a main reason to pick this model. Once a prompt crosses 200k tokens, input doubles and output rises by half. Four cost levers do more than any benchmark table:

1. Keep routine prompts below 200k tokens when you can.
2. Send background jobs through Batch or Flex at half price instead of paying Standard rates.
3. Cache large instructions or reference material you resend. With $4.50 per 1M tokens per hour of storage, caching pays off only when the block is reused often.
4. Set the thinking level on purpose, because thinking tokens bill as output.

Is there a free tier for the Gemini 3.1 Pro API?

No. Google's pricing page shows "Not available" in every free-tier row for Gemini 3.1 Pro Preview, and the Gemini 3 developer guide says plainly that "there is no free tier available for gemini-3.1-pro-preview in the Gemini API." A free API key works only with free-tier models such as Gemini 3.8 Flash, 3.6 Flash, 3.5 Flash-Lite, 3.1 Flash-Lite, and 3 Flash Preview. The Gemini API free tier guide lists those models and their limits.

AI Studio, the web interface, is a separate question, and Google's own pages disagree:

• The Gemini 3 developer guide, now marked deprecated, says "You can try Gemini 3.1 Pro and 3 Flash at no cost in Google AI Studio."
• Google's AI plans page says Google AI Pro and Ultra subscriptions "unlock paid models and higher rate limits in the Google AI Studio Playground," with AI Pro listed as giving "Access to premium models like Gemini Pro." Free accounts get a "Modest quota."
• As of October 10, 2026, the AI Studio Playground on a free personal account opens with Gemini 3.1 Pro Preview selected and no lock on the model card. A sidebar banner reads "Upgrade to unlock more — Access higher limits, Pro models, and more," and no free daily quota number is shown.

Whether a free account can complete Pro prompts in the Playground, and how many, isn't documented. After the February rollout, a Google AI Developers Forum thread reported free users hitting "You are out of free generations today" and being told to continue with their own API key. Plan benefits apply only inside the AI Studio web interface. Google states that direct Gemini API use "is billed and managed separately."

Gemini 3.1 Pro rate limits, billing tiers, and Prepay

Google no longer publishes a fixed RPM, TPM, or RPD table for your account. The Gemini API rate limits page says limits apply per project, not per API key, and tells you to view your active limits in AI Studio. Preview models such as 3.1 Pro "might come with more restrictive rate limits." For how the dimensions and 429 errors work, see the Gemini API rate limits guide.

Usage tiers belong to the billing account. Tier 1 starts when you link an active billing account and has a $250 monthly spend cap. Tier 2 needs $100 paid plus 3 days since the first successful payment ($2,000 cap). Tier 3 needs $1,000 paid plus 30 days ($20,000 to $100,000+). Rolling 10-minute spend limits of $10, $50, and $200 for Tiers 1–3 return 429 RESOURCE_EXHAUSTED when crossed. Project spend caps exist in AI Studio but Google calls them "experimental and limited in scope."

On Prepay, when the balance reaches $0, every API key in every project linked to that billing account stops working, and requests fail with HTTP 402 Payment Required until you add credits. Credits expire after 12 months and are non-refundable. Google is moving existing Postpay accounts to Prepay. Impress Watch reported the cutover as October 12, 2026, based on Google's account notice, but Google's billing page refers only to "the cutover date in your account notice," so check your own notice. The $300 Google Cloud Free Trial has not covered Gemini API usage since March 2026. The Gemini API billing tiers guide covers auto-reload and the edge cases.

Thinking, long context, and the cost levers that actually matter

Gemini 3.1 Pro supports three thinking levels: low, medium, and high. high is the default and is dynamic. minimal is not supported on 3.1 Pro, even though Gemini 3.1 Flash-Lite and 3 Flash accept it. You also can't send thinking_level together with the legacy thinking_budget in one request: Google's docs say "Doing so will return a 400 error." thinking_budget still works on its own for backward compatibility, but Google's migration checklist says to replace it with thinking_level.

A workable default is medium for daily work. Drop to low for extraction, classification, and short rewrites. Move to high only for problems that need it, such as large-codebase review or long multi-step analysis. That is an engineering rule of thumb, not a Google rule. It follows from two documented facts: thinking tokens bill at the output rate ($12.00 per 1M up to 200k), and an unset level means high. The Gemini 3.1 Pro thinking level guide has more examples per level.

Long context needs the same discipline. The 1M-token window is real, but the question is how often you pay the >200k rate. If you resend a giant system prompt, the same document pack, or unchanged repository context, cache it or summarize it first. Otherwise long context becomes a billing habit rather than a deliberate choice.

Migrate cleanly if you used Gemini 3 Pro Preview or the OpenAI SDK

If your code still calls gemini-3-pro-preview, it has been served by gemini-3.1-pro-preview since March 9, 2026. Change the string to the current ID so logs, cost reports, and alerts name the model you actually pay for. Then work through the checklist Google publishes in its latest-model notes:

• Thinking: replace thinking_budget with the string enum thinking_level (low, medium, or high on 3.1 Pro). Never send both.
• Sampling: remove temperature, top_p, and top_k (deprecated since July 21, 2026) and candidate_count, which is "unsupported in Gemini 3 and later."
• Prefill: remove prefilled model turns.
• Multi-turn state: Google recommends standardizing on server-side previous_interaction_id in the Interactions API.
• Function calling: if you stay on generateContent, make sure every FunctionResponse includes call_id and name.
• Thought signatures: Gemini 3 models use thought signatures to keep reasoning context across calls. With stateful Interactions the server manages them. If you build history yourself, Google says "you must include thought blocks with their signatures in subsequent requests."

If your stack is built on the OpenAI SDK, Google's OpenAI compatibility docs for the Gemini API let you keep the client and change three things: the API key, the base URL, and the model name.

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)

Google says OpenAI's reasoning_effort is "automatically mapped to Gemini (thinking_level) equivalents." Because 3.1 Pro accepts only low, medium, and high, pass one of those three rather than relying on how another value gets mapped. Don't add a separate Gemini thinking control in extra_body on top of reasoning_effort unless the compatibility docs say that combination is supported. Like the native samples, this one wasn't run for the October 2026 update.

Before you move a production route, check that no stale tutorial code is left (old IDs, sampling parameters, thinking_budget). Re-run your cost math against the price table above and send a few representative prompts through a test project.

When Gemini 3.1 Pro is the right API and when it is not

For most new work in October 2026, the real choice is between Gemini 3.1 Pro and Gemini 3.8 Flash. Gemini 3.6 Flash, the previous Flash generation, has the same prices as 3.8 Flash. Google gives the two models overlapping descriptions. Pro is tuned for "software engineering behavior and usability, as well as agentic workflows requiring precise tool usage," while 3.8 Flash is "our most intelligent Flash model, engineered for long-horizon software engineering, autonomous agents, and complex enterprise workflows."

The list-price gap shrinks on January 1, 2027. Through December 31, 2026, Pro input costs 2.67 times Flash ($2.00 ÷ $0.75) and Pro output 3.2 times ($12.00 ÷ $3.75). From January 1, 2027, the multiples drop to 1.33 ($2.00 ÷ $1.50) and 1.6 ($12.00 ÷ $7.50). As a worked example, a month of 10M input and 2M output tokens under 200k costs $44 on Pro (10 × $2.00 + 2 × $12.00), $15 on 3.8 Flash in 2026 (10 × $0.75 + 2 × $3.75), and $30 on 3.8 Flash in 2027 (10 × $1.50 + 2 × $7.50). These are list prices, not task costs. Google notes that 3.8 Flash "can use more tokens on longer running and complex tasks, by design," and suggests lowering the reasoning effort or using 3.6 Flash for everyday tasks.

Google publishes no head-to-head benchmark table for 3.8 Flash against 3.1 Pro, and third-party comparisons disagree on which one scores higher. Your own prompts are the deciding test. A practical split:

• Choose Gemini 3.1 Pro when your evaluation shows it wins on your hardest tasks, such as precise multi-tool agent runs, large-codebase review, or mixed document, image, and video analysis, and you can accept Preview status: possibly tighter limits and as little as two weeks' notice before a deprecation.
• Choose gemini-3.1-pro-preview-customtools when the agent has bash plus registered tools and keeps ignoring the registered ones.
• Choose Gemini 3.8 Flash when you need a free tier for prototyping, a GA model for production, or lower cost at volume. Pick 3.6 Flash if 3.8 Flash's longer token use inflates your bill.
• Choose a different model family when you need image output or live audio, which 3.1 Pro doesn't produce.

laozhang.ai lists gemini-3.1-pro-preview at $2.00 input / $12.00 output per 1M tokens behind an OpenAI-compatible base URL, with its own key and balance rather than a Google key. With any gateway, confirm that it passes through the exact model ID and features you rely on, such as -customtools or thinking levels.

Disclosure: laozhang.ai is our own service. Its prices are platform pricing, not an independent comparison.

The bottom line: use Gemini 3.1 Pro when you need what it does, not because it carries the Pro label. For fast, cheap, high-volume text, 3.8 Flash is the default to beat until at least December 31, 2026. For one large multimodal context with structured output, grounded reasoning, and reliable multi-step tool use, Gemini 3.1 Pro is still Google's current Pro option.

FAQ

Is the Gemini 3.1 Pro API free, or is there a free Gemini 3.1 Pro API key?
No. Creating a Gemini API key is free, but gemini-3.1-pro-preview has no free tier as of October 10, 2026. Every call is billed from $2.00 input / $12.00 output per 1M tokens. A free key works with free-tier models such as Gemini 3.8 Flash.

Can I use Gemini 3.1 Pro for free in Google AI Studio?
Possibly, but only in the web Playground and without a published quota. A deprecated Google guide says you can try 3.1 Pro at no cost in AI Studio, while Google's AI plans page says AI Pro and Ultra unlock "premium models like Gemini Pro" there. On a free account, the Playground shows 3.1 Pro selected next to an "Upgrade to unlock more" banner. None of this applies to API calls.

Does a Google AI Pro subscription include Gemini 3.1 Pro API access?
No. Google AI Pro and Ultra raise limits inside the AI Studio web interface and the Gemini app. Google states that direct Gemini API use "is billed and managed separately," so API calls need a billing account with Prepay credits.

Is Gemini 3.1 Pro the same as Extended thinking?
No. Gemini 3.1 Pro is a model; Extended thinking is a thinking level in the Gemini app. In the app, Standard thinking is the default and Extended is "best for complex problem solving." The setting can apply to Flash or Pro, and higher levels use up more of your usage. On the API, the equivalent control is thinking_level (low, medium, high).

Does gemini-3-pro-preview still work?
It was shut down on March 9, 2026, and requests to it are served by gemini-3.1-pro-preview. Update your code to the current ID so billing and logs match the model you're actually using.

Is there a newer Gemini Pro model than 3.1 Pro in the API?
No. As of October 10, 2026, Gemini 3.1 Pro Preview is the only Gemini 3 Pro text model on the Gemini API. The newer releases are Flash models: 3.8 Flash and 3.6 Flash.

Should I use gemini-3.1-pro-preview-customtools for every project?
No. Use it when custom-tool prioritization is the point. Google warns that quality may fluctuate in workloads that don't benefit from such tools. Price and context window match the standard model.

Where do I see my real RPM, TPM, and RPD?
In AI Studio's rate-limit view for your project. Google applies limits per project, ties tiers to your billing account, and doesn't publish a fixed table, and preview models like 3.1 Pro may get tighter limits.

Can I call Gemini 3.1 Pro through the OpenAI SDK?
Yes. Point the OpenAI client at https://generativelanguage.googleapis.com/v1beta/openai/, use your Gemini API key, and set the model to gemini-3.1-pro-preview. reasoning_effort maps to Gemini thinking levels; use low, medium, or high.

Does Gemini 3.1 Pro support image generation or Live API?
No. The model page lists image generation, audio generation, and Live API as unsupported. It accepts image, video, audio, and PDF input but returns text only.