pages/gemini-3.txt

route: /gemini-api/docs/gemini-3
title: Gemini 3 Developer Guide
description: Learn about the new features of Gemini 3 in the Gemini API.

Note: This version of the page covers the Interactions API. You can use the toggle on this page to switch to the generateContent API version of this page.
Deprecation notice: This page is deprecated and will be removed.
See the What's new
in Gemini 3.5 Flash guide for the latest developer guidance, including
migration instructions, prompting best practices, and an updated feature
overview for all Gemini 3.x models.
Gemini 3 is our most intelligent model family to date, built on a foundation of
state-of-the-art reasoning. It is designed to bring any idea to life by
mastering agentic workflows, autonomous coding, and complex multimodal tasks.
This guide covers key features of the Gemini 3 model family and how to get the
most out of it.
Explore our collection of Gemini 3 apps to
see how the model handles advanced reasoning, autonomous coding, and complex
multimodal tasks.
Get started with a few lines of code:
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3.1-pro-preview",
input="Find the race condition in this multi-threaded C++ snippet: [code here]",
)
print(interaction.output_text)
JavaScript
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
async function run() {
const interaction = await client.interactions.create({
model: "gemini-3.1-pro-preview",
input: "Find the race condition in this multi-threaded C++ snippet: [code here]",
});
console.log(interaction.output_text);
}
run();
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3.1-pro-preview",
"input": "Find the race condition in this multi-threaded C++ snippet: [code here]"
}'
Meet the Gemini 3 series
Gemini 3.1 Pro is best for complex tasks that
require broad world knowledge and advanced reasoning across modalities.
Gemini 3 Flash is our latest 3-series model, with Pro-level intelligence at the
speed and pricing of Flash.
Nano Banana Pro (also known as Gemini 3 Pro Image) is our highest quality image
generation model, and Nano Banana 2 (also known as Gemini 3.1 Flash Image) is
the high-volume, high-efficiency, lower price-point equivalent.
Gemini 3.1 Flash-Lite is our workhorse model built for cost-efficiency model and
high-volume tasks.
All Gemini 3 models are currently in preview.
Model ID
Context Window (In / Out)
Knowledge Cutoff
Pricing (Input / Output)*
gemini-3.1-flash-lite
1M / 64k
Jan 2025
$0.25 (text, image, video), $0.50 (audio) / $1.50
gemini-3.1-flash-image-preview
128k / 32k
Jan 2025
$0.25 (Text Input) / $0.067 (Image Output)**
gemini-3.1-pro-preview
1M / 64k
Jan 2025
$2 / $12 (<200k tokens)
$4 / $18 (>200k tokens)
gemini-3-flash-preview
1M / 64k
Jan 2025
$0.50 / $3
gemini-3-pro-image-preview
65k / 32k
Jan 2025
$2 (Text Input) / $0.134 (Image Output)**
* Pricing is per 1 million tokens unless otherwise noted.
** Image pricing varies by resolution. See the pricing page for details.
For detailed limits, pricing, and additional information, see the
models page.
New API features in Gemini 3
Gemini 3 introduces new parameters designed to give developers more control over
latency, cost, and multimodal fidelity.
Level of thinking
Gemini 3 series models use dynamic thinking by default to reason through
prompts. You can use the thinking_level parameter, which controls the
maximum depth of the model's internal reasoning process before it produces a
response. Gemini 3 treats these levels as relative allowances for thinking
rather than strict token guarantees.
If thinking_level is not specified, Gemini 3 will default to high. For
faster, lower-latency responses when complex reasoning isn't required, you can
constrain the model's thinking level to low.
Thinking Level
Gemini 3.1 Pro
Gemini 3.1 Flash-Lite
Gemini 3 Flash
Description
minimal
Not supported
Supported (Default)
Supported
Matches the "no thinking" setting for most queries. The model may think very minimally for complex coding tasks. Minimizes latency for chat or high throughput applications. Note, minimal does not guarantee that thinking is off.
low
Supported
Minimizes latency and cost. Best for simple instruction following, chat, or high-throughput applications.
medium
Supported
Balanced thinking for most tasks.
high
Supported (Default, Dynamic)
Supported (Dynamic)
Supported (Default, Dynamic)
Maximizes reasoning depth. The model may take significantly longer to
reach a first (non thinking) output token, but the output will be more carefully reasoned.
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3.1-pro-preview",
input="How does AI work?",
generation_config={"thinking_level": "low"},
)
print(interaction.output_text)
JavaScript
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: "gemini-3.1-pro-preview",
input: "How does AI work?",
generation_config: {
thinking_level: "low",
},
});
console.log(interaction.output_text);
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3.1-pro-preview",
"input": "How does AI work?",
"generation_config": {
"thinking_level": "low"
}
}'
Important: You cannot use both thinking_level and the legacy thinking_budget
parameter in the same request. Doing so will return a 400 error.
Temperature
For all Gemini 3 models, we strongly recommend keeping the temperature parameter
at its default value of 1.0.
While previous models often benefited from tuning temperature to control
creativity versus determinism, Gemini 3's reasoning capabilities are optimized
for the default setting. Changing the temperature (setting it below 1.0) may
lead to unexpected behavior, such as looping or degraded performance,
particularly in complex mathematical or reasoning tasks.
Thought signatures
Gemini 3 models use thought signatures to maintain reasoning context across API calls. These signatures are encrypted representations of the model's internal thought process.
Stateful Mode (Recommended): When using the Interactions API in stateful mode (providing previous_interaction_id), the server automatically manages conversation history and thought signatures.
Stateless Mode: If you are managing conversation history manually, you must include thought blocks with their signatures in subsequent requests to validate authenticity.
For detailed information, see the Thought Signatures page.`
Structured Outputs with tools
Gemini 3 models allow you to combine Structured Outputs with built-in tools, including
Grounding with Google Search, URL Context, Code Execution, and Function Calling.
Python
from google import genai
from pydantic import BaseModel, Field
from typing import List
class MatchResult(BaseModel):
winner: str = Field(description="The name of the winner.")
final_match_score: str = Field(description="The final match score.")
scorers: List[str] = Field(description="The name of the scorer.")
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3.1-pro-preview",
input="Search for all details for the latest Euro.",
tools=[
{"type": "google_search"},
{"type": "url_context"}
],
response_format={
"type": "text",
"mime_type": "application/json",
"schema": MatchResult.model_json_schema()
},
)
result = MatchResult.model_validate_json(interaction.output_text)
print(result)
JavaScript
import { GoogleGenAI } from "@google/genai";
import * as z from "zod";
const matchJsonSchema = {
type: "object",
properties: {
winner: { type: "string", description: "The name of the winner." },
final_match_score: { type: "string", description: "The final score." },
scorers: {
type: "array",
it
…