Repository Public
1> [!CAUTION]2> **Deprecation notice:** This page is deprecated and will be removed. See the [What's new3> in Gemini 3.5 Flash](https://ai.google.dev/gemini-api/docs/whats-new-gemini-3.5) guide for the latest developer guidance, including migration instructions, prompting best practices, and an updated feature overview for all Gemini 3.x models.45Gemini 3 is our most intelligent model family to date, built on a foundation of6state-of-the-art reasoning. It is designed to bring any idea to life by7mastering agentic workflows, autonomous coding, and complex multimodal tasks.8This guide covers key features of the Gemini 3 model family and how to get the9most out of it.1011Explore our [collection of Gemini 3 apps](https://aistudio.google.com/app/apps?source=showcase&showcaseTag=gemini-3) to12see how the model handles advanced reasoning, autonomous coding, and complex13multimodal tasks.1415Get started with a few lines of code:1617### Python1819 from google import genai2021 client = genai.Client()2223 interaction = client.interactions.create(24 model="gemini-3.1-pro-preview",25 input="Find the race condition in this multi-threaded C++ snippet: [code here]",26 )2728 print(interaction.output_text)2930### JavaScript3132 import { GoogleGenAI } from "@google/genai";3334 const client = new GoogleGenAI({});3536 async function run() {37 const interaction = await client.interactions.create({38 model: "gemini-3.1-pro-preview",39 input: "Find the race condition in this multi-threaded C++ snippet: [code here]",40 });4142 console.log(interaction.output_text);43 }4445 run();4647### Java4849 import com.google.genai.Client;50 import com.google.genai.gaos.models.interactions.CreateModelInteraction;51 import com.google.genai.gaos.models.interactions.Interaction;52 import com.google.genai.gaos.models.interactions.InteractionsInput;53 import com.google.genai.gaos.models.interactions.Model;54 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;5556 Client client = new Client();5758 CreateModelInteraction request =59 CreateModelInteraction.builder()60 .model(Model.of("gemini-3.1-pro-preview"))61 .input(62 InteractionsInput.of(63 "Find the race condition in this multi-threaded C++ snippet: [code here]"))64 .build();6566 Interaction interaction =67 client.interactions.create(CreateInteractionRequestBody.of(request)).interaction().get();6869 System.out.println(interaction.outputText().orElse(""));7071### REST7273 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \74 -H "x-goog-api-key: $GEMINI_API_KEY" \75 -H 'Content-Type: application/json' \76 -d '{77 "model": "gemini-3.1-pro-preview",78 "input": "Find the race condition in this multi-threaded C++ snippet: [code here]"79 }'8081## Meet the Gemini 3 series8283Gemini 3.1 Pro is best for complex tasks that84require broad world knowledge and advanced reasoning across modalities.8586Gemini 3 Flash is our latest 3-series model, with Pro-level intelligence at the87speed and pricing of Flash.8889Nano Banana Pro (also known as Gemini 3 Pro Image) is our highest quality image90generation model, and Nano Banana 2 (also known as Gemini 3.1 Flash Image) is91the high-volume, high-efficiency, lower price-point equivalent.9293Gemini 3.1 Flash-Lite is our workhorse model built for cost-efficiency model and94high-volume tasks.9596All Gemini 3 models are currently in preview.9798| Model ID | Context Window (In / Out) | Knowledge Cutoff | Pricing (Input / Output)\* |99|---|---|---|---|100| **gemini-3.1-flash-lite** | 1M / 64k | Jan 2025 | $0.25 (text, image, video), $0.50 (audio) / $1.50 |101| **gemini-3.1-flash-image-preview** | 128k / 32k | Jan 2025 | $0.25 (Text Input) / $0.067 (Image Output)\*\* |102| **gemini-3.1-pro-preview** | 1M / 64k | Jan 2025 | $2 / $12 (\<200k tokens) $4 / $18 (\>200k tokens) |103| **gemini-3-flash-preview** | 1M / 64k | Jan 2025 | $0.50 / $3 |104| **gemini-3-pro-image-preview** | 65k / 32k | Jan 2025 | $2 (Text Input) / $0.134 (Image Output)\*\* |105106*\* Pricing is per 1 million tokens unless otherwise noted.*107*\*\* Image pricing varies by resolution. See the [pricing page](https://ai.google.dev/gemini-api/docs/pricing) for details.*108109For detailed limits, pricing, and additional information, see the110[models page](https://ai.google.dev/gemini-api/docs/models/gemini).111112## New API features in Gemini 3113114Gemini 3 introduces new parameters designed to give developers more control over115latency, cost, and multimodal fidelity.116117### Level of thinking118119Gemini 3 series models use dynamic thinking by default to reason through120prompts. You can use the `thinking_level` parameter, which controls the121**maximum** depth of the model's internal reasoning process before it produces a122response. Gemini 3 treats these levels as relative allowances for thinking123rather than strict token guarantees.124125If `thinking_level` is not specified, Gemini 3 will default to `high`. For126faster, lower-latency responses when complex reasoning isn't required, you can127constrain the model's thinking level to `low`.128129| Thinking Level | Gemini 3.1 Pro | Gemini 3.1 Flash-Lite | Gemini 3 Flash | Description |130|---|---|---|---|---|131| **`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. |132| **`low`** | Supported | Supported | Supported | Minimizes latency and cost. Best for simple instruction following, chat, or high-throughput applications. |133| **`medium`** | Supported | Supported | Supported | Balanced thinking for most tasks. |134| **`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. |135136### Python137138 from google import genai139140 client = genai.Client()141142 interaction = client.interactions.create(143 model="gemini-3.1-pro-preview",144 input="How does AI work?",145 generation_config={"thinking_level": "low"},146 )147148 print(interaction.output_text)149150### JavaScript151152 import { GoogleGenAI } from "@google/genai";153154 const client = new GoogleGenAI({});155156 const interaction = await client.interactions.create({157 model: "gemini-3.1-pro-preview",158 input: "How does AI work?",159 generation_config: {160 thinking_level: "low",161 },162 });163164 console.log(interaction.output_text);165166### Java167168 import com.google.genai.Client;169 import com.google.genai.gaos.models.interactions.CreateModelInteraction;170 import com.google.genai.gaos.models.interactions.GenerationConfig;171 import com.google.genai.gaos.models.interactions.Interaction;172 import com.google.genai.gaos.models.interactions.InteractionsInput;173 import com.google.genai.gaos.models.interactions.Model;174 import com.google.genai.gaos.models.interactions.ThinkingLevel;175 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;176177 Client client = new Client();178179 CreateModelInteraction request =180 CreateModelInteraction.builder()181 .model(Model.of("gemini-3.1-pro-preview"))182 .input(InteractionsInput.of("How does AI work?"))183 .generationConfig(184 GenerationConfig.builder()185 .thinkingLevel(ThinkingLevel.LOW)186 .build())187 .build();188189 Interaction interaction =190 client.interactions.create(CreateInteractionRequestBody.of(request)).interaction().get();191192 System.out.println(interaction.outputText().orElse(""));193194### REST195196 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \197 -H "x-goog-api-key: $GEMINI_API_KEY" \198 -H 'Content-Type: application/json' \199 -d '{200 "model": "gemini-3.1-pro-preview",201 "input": "How does AI work?",202 "generation_config": {203 "thinking_level": "low"204 }205 }'206207> [!IMPORTANT]208> **Important:** You cannot use both `thinking_level` and the legacy `thinking_budget` parameter in the same request. Doing so will return a 400 error.209210### Temperature211212For all Gemini 3 models, we strongly recommend keeping the temperature parameter213at its default value of `1.0`.214215While previous models often benefited from tuning temperature to control216creativity versus determinism, Gemini 3's reasoning capabilities are optimized217for the default setting. Changing the temperature (setting it below 1.0) may218lead to unexpected behavior, such as looping or degraded performance,219particularly in complex mathematical or reasoning tasks.220221### Thought signatures222223Gemini 3 models use thought signatures to maintain reasoning context across API calls. These signatures are encrypted representations of the model's internal thought process.224225- **Stateful Mode (Recommended)** : When using the Interactions API in stateful mode (providing `previous_interaction_id`), the server automatically manages conversation history and thought signatures.226- **Stateless Mode**: If you are managing conversation history manually, you must include thought blocks with their signatures in subsequent requests to validate authenticity.227228For detailed information, see the [Thought Signatures](https://ai.google.dev/gemini-api/docs/thinking) page.\`229230### Structured Outputs with tools231232Gemini 3 models allow you to combine [Structured Outputs](https://ai.google.dev/gemini-api/docs/structured-output) with built-in tools, including233[Grounding with Google Search](https://ai.google.dev/gemini-api/docs/google-search), [URL Context](https://ai.google.dev/gemini-api/docs/url-context), [Code Execution](https://ai.google.dev/gemini-api/docs/code-execution), and [Function Calling](https://ai.google.dev/gemini-api/docs/function-calling).234235### Python236237 from google import genai238 from pydantic import BaseModel, Field239 from typing import List240241 class MatchResult(BaseModel):242 winner: str = Field(description="The name of the winner.")243 final_match_score: str = Field(description="The final match score.")244 scorers: List[str] = Field(description="The name of the scorer.")245246 client = genai.Client()247248 interaction = client.interactions.create(249 model="gemini-3.1-pro-preview",250 input="Search for all details for the latest Euro.",251 tools=[252 {"type": "google_search"},253 {"type": "url_context"}254 ],255 response_format={256 "type": "text",257 "mime_type": "application/json",258 "schema": MatchResult.model_json_schema()259 },260 )261262 result = MatchResult.model_validate_json(interaction.output_text)263 print(result)264265### JavaScript266267 import { GoogleGenAI } from "@google/genai";268 import * as z from "zod";269270 const matchJsonSchema = {271 type: "object",272 properties: {273 winner: { type: "string", description: "The name of the winner." },274 final_match_score: { type: "string", description: "The final score." },275 scorers: {276 type: "array",277 items: { type: "string" },278 description: "The name of the scorer."279 }280 },281 required: ["winner", "final_match_score", "scorers"]282 };283284 const matchSchema = z.fromJSONSchema(matchJsonSchema);285286 const client = new GoogleGenAI({});287288 async function run() {289 const interaction = await client.interactions.create({290 model: "gemini-3.1-pro-preview",291 input: "Search for all details for the latest Euro.",292 tools: [293 { type: "google_search" },294 { type: "url_context" }295 ],296 response_format: {297 type: "text",298 mime_type: "application/json",299 schema: matchJsonSchema300 },301 });302303 const match = matchSchema.parse(JSON.parse(interaction.output_text));304 console.log(match);305 }306307 run();308309### Java310311 import com.google.genai.Client;312 import com.google.genai.gaos.models.interactions.CreateModelInteraction;313 import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;314 import com.google.genai.gaos.models.interactions.GoogleSearch;315 import com.google.genai.gaos.models.interactions.Interaction;316 import com.google.genai.gaos.models.interactions.InteractionsInput;317 import com.google.genai.gaos.models.interactions.Model;318 import com.google.genai.gaos.models.interactions.ResponseFormat;319 import com.google.genai.gaos.models.interactions.TextResponseFormat;320 import com.google.genai.gaos.models.interactions.TextResponseFormatMimeType;321 import com.google.genai.gaos.models.interactions.URLContext;322 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;323 import java.util.Arrays;324 import java.util.HashMap;325 import java.util.Map;326327 Client client = new Client();328329 Map<String, Object> properties = new HashMap<>();330 properties.put("winner", Map.of("type", "string", "description", "The name of the winner."));331 properties.put(332 "final_match_score", Map.of("type", "string", "description", "The final match score."));333 properties.put(334 "scorers",335 Map.of(336 "type", "array",337 "items", Map.of("type", "string"),338 "description", "The name of the scorer."));339340 Map<String, Object> schema = new HashMap<>();341 schema.put("type", "object");342 schema.put("properties", properties);343 schema.put("required", Arrays.asList("winner", "final_match_score", "scorers"));344345 CreateModelInteraction request =346 CreateModelInteraction.builder()347 .model(Model.of("gemini-3.1-pro-preview"))348 .input(InteractionsInput.of("Search for all details for the latest Euro."))349 .tools(Arrays.asList(GoogleSearch.builder().build(), URLContext.builder().build()))350 .responseFormat(351 CreateModelInteractionResponseFormat.of(352 ResponseFormat.of(353 TextResponseFormat.builder()354 .mimeType(TextResponseFormatMimeType.APPLICATION_JSON)355 .schema(schema)356 .build())))357 .build();358359 Interaction interaction =360 client.interactions.create(CreateInteractionRequestBody.of(request)).interaction().get();361362 System.out.println(interaction.outputText().orElse(""));363364### REST365366 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \367 -H "x-goog-api-key: $GEMINI_API_KEY" \368 -H 'Content-Type: application/json' \369 -d '{370 "model": "gemini-3.1-pro-preview",371 "input": "Search for all details for the latest Euro.",372 "tools": [373 {"type": "google_search"},374 {"type": "url_context"}375 ],376 "response_format": {377 "type": "text",378 "mime_type": "application/json",379 "schema": {380 "type": "object",381 "properties": {382 "winner": {"type": "string", "description": "The name of the winner."},383 "final_match_score": {"type": "string", "description": "The final score."},384 "scorers": {385 "type": "array",386 "items": {"type": "string"},387 "description": "The name of the scorer."388 }389 },390 "required": ["winner", "final_match_score", "scorers"]391 }392 }393 }'394395### Image generation396397Gemini 3.1 Flash Image and Gemini 3 Pro Image let you generate and edit images398from text prompts. It uses399reasoning to "think" through a prompt and can retrieve real-time data---such as400weather forecasts or stock charts---before using [Google Search](https://ai.google.dev/gemini-api/docs/google-search) grounding before generating high-fidelity401images.402403**New \& improved capabilities:**404405- **4K \& text rendering:** Generate sharp, legible text and diagrams with up to 2K and 4K resolutions.406- **Grounded generation:** Use the `google_search` tool to verify facts and generate imagery based on real-world information. Grounding with Google *Image* Search available for Gemini 3.1 Flash Image.407- **Conversational editing:** Multi-turn image editing by simply asking for changes (e.g., "Make the background a sunset"). This workflow relies on **Thought Signatures** to preserve visual context between turns.408409For complete details on aspect ratios, editing workflows, and configuration410options, see the [Image Generation guide](https://ai.google.dev/gemini-api/docs/image-generation).411412### Python413414 from google import genai415 import base64416417 client = genai.Client()418419 interaction = client.interactions.create(420 model="gemini-3-pro-image-preview",421 input="Generate an infographic of the current weather in Tokyo.",422 tools=[{"type": "google_search"}],423 response_format={424 "type": "image",425 "aspect_ratio": "16:9",426 "image_size": "4K"427 }428 )429430 from PIL import Image431 import io432433 generated_image = interaction.output_image434 if generated_image:435 image_data = base64.b64decode(generated_image.data)436 image = Image.open(io.BytesIO(image_data))437 image.save('weather_tokyo.png')438 image.show()439440### JavaScript441442 import { GoogleGenAI } from "@google/genai";443 import * as fs from "node:fs";444445 const client = new GoogleGenAI({});446447 async function run() {448 const interaction = await client.interactions.create({449 model: "gemini-3-pro-image-preview",450 input: "Generate a visualization of the current weather in Tokyo.",451 tools: [{ type: "google_search" }],452 response_format: {453 type: "image",454 aspect_ratio: "16:9",455 image_size: "4K"456 }457 });458459 const buffer = Buffer.from(interaction.output_image.data, 'base64');460461 fs.writeFileSync('weather_tokyo.png', buffer);462 }463464 run();465466### Java467468 import com.google.genai.Client;469 import com.google.genai.gaos.models.interactions.CreateModelInteraction;470 import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;471 import com.google.genai.gaos.models.interactions.GoogleSearch;472 import com.google.genai.gaos.models.interactions.ImageContent;473 import com.google.genai.gaos.models.interactions.ImageResponseFormat;474 import com.google.genai.gaos.models.interactions.ImageResponseFormatAspectRatio;475 import com.google.genai.gaos.models.interactions.ImageResponseFormatImageSize;476 import com.google.genai.gaos.models.interactions.Interaction;477 import com.google.genai.gaos.models.interactions.InteractionsInput;478 import com.google.genai.gaos.models.interactions.Model;479 import com.google.genai.gaos.models.interactions.ResponseFormat;480 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;481 import java.nio.file.Files;482 import java.nio.file.Paths;483 import java.util.Arrays;484 import java.util.Base64;485 import java.util.Optional;486487 Client client = new Client();488489 CreateModelInteraction request =490 CreateModelInteraction.builder()491 .model(Model.of("gemini-3-pro-image-preview"))492 .input(InteractionsInput.of("Generate an infographic of the current weather in Tokyo."))493 .tools(Arrays.asList(GoogleSearch.builder().build()))494 .responseFormat(495 CreateModelInteractionResponseFormat.of(496 ResponseFormat.of(497 ImageResponseFormat.builder()498 .aspectRatio(ImageResponseFormatAspectRatio.ONE_HUNDRED_AND_SIXTY_NINE)499 .imageSize(ImageResponseFormatImageSize.FOUR_K)500 .build())))501 .build();502503 Interaction interaction =504 client.interactions.create(CreateInteractionRequestBody.of(request)).interaction().get();505506 Optional<ImageContent> generatedImage = interaction.outputImage();507 if (generatedImage.isPresent() && generatedImage.get().data().isPresent()) {508 byte[] imageBytes = Base64.getDecoder().decode(generatedImage.get().data().get());509 Files.write(Paths.get("weather_tokyo.png"), imageBytes);510 }511512### REST513514 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \515 -H "x-goog-api-key: $GEMINI_API_KEY" \516 -H 'Content-Type: application/json' \517 -d '{518 "model": "gemini-3-pro-image-preview",519 "input": "Generate a visualization of the current weather in Tokyo.",520 "tools": [{"type": "google_search"}],521 "response_format": {522 "type": "image",523 "aspect_ratio": "16:9",524 "image_size": "4K"525 }526 }'527528**Example Response**529530531532### Code Execution with images533534Gemini 3 Flash can treat vision as an active investigation, not just a static535glance. By combining reasoning with [code execution](https://ai.google.dev/gemini-api/docs/code-execution), the model formulates a plan, then writes and536executes Python code to zoom in, crop, annotate, or otherwise manipulate images537step-by-step to visually ground its answers.538539**Use cases:**540541- **Zoom and inspect:** The model implicitly detects when details are too small (e.g., reading a distant gauge or serial number) and writes code to crop and re-examine the area at higher resolution.542- **Visual math and plotting:** The model can run multi-step calculations using code (e.g., summing line items on a receipt, or generating a Matplotlib chart from extracted data).543- **Image annotation:** The model can draw arrows, bounding boxes, or other annotations directly onto images to answer spatial questions like "Where should this item go?".544545To enable visual thinking, configure [Code Execution](https://ai.google.dev/gemini-api/docs/code-execution) as a tool. The model will automatically use546code to manipulate images when needed.547548### Python549550 from google import genai551 from google.genai import types552 import requests553 from PIL import Image554 import io555 import base64556557 image_path = "https://goo.gle/instrument-img"558 image_bytes = requests.get(image_path).content559 image = types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg")560561 client = genai.Client()562563 interaction = client.interactions.create(564 model="gemini-3-flash-preview",565 input=[566 image,567 "Zoom into the expression pedals and tell me how many pedals are there?"568 ],569 tools=[{"type": "code_execution"}],570 )571572 from IPython.display import display573 from PIL import Image574 import io575576 for step in interaction.steps:577 if step.type == "model_output":578 for content_block in step.content:579 if content_block.type == "text":580 print(content_block.text)581 elif content_block.type == "image":582 display(Image.open(io.BytesIO(base64.b64decode(content_block.data))))583 elif step.type == "code_execution_call":584 print(step.code)585 elif step.type == "code_execution_result":586 print(step.output)587588### JavaScript589590 import { GoogleGenAI } from "@google/genai";591592 const client = new GoogleGenAI({});593594 async function main() {595 const imageUrl = "https://goo.gle/instrument-img";596 const response = await fetch(imageUrl);597 const imageArrayBuffer = await response.arrayBuffer();598 const base64ImageData = Buffer.from(imageArrayBuffer).toString("base64");599600 const interaction = await client.interactions.create({601 model: "gemini-3-flash-preview",602 input: [603 {604 type: "image",605 mime_type: "image/jpeg",606 data: base64ImageData,607 },608 {609 type: "text",610 text: "Zoom into the expression pedals and tell me how many pedals are there?",611 },612 ],613 tools: [{ type: "code_execution" }],614 });615616 for (const step of interaction.steps) {617 if (step.type === "model_output") {618 for (const contentBlock of step.content) {619 if (contentBlock.type === "text") {620 console.log("Text:", contentBlock.text);621 }622 }623 } else if (step.type === "code_execution_call") {624 console.log("Code:", step.code);625 } else if (step.type === "code_execution_result") {626 console.log("Output:", step.output);627 }628 }629 }630631 main();632633### Java634635 import com.google.genai.Client;636 import com.google.genai.gaos.models.interactions.CodeExecution;637 import com.google.genai.gaos.models.interactions.CodeExecutionCallStep;638 import com.google.genai.gaos.models.interactions.CodeExecutionResultStep;639 import com.google.genai.gaos.models.interactions.Content;640 import com.google.genai.gaos.models.interactions.CreateModelInteraction;641 import com.google.genai.gaos.models.interactions.ImageContent;642 import com.google.genai.gaos.models.interactions.ImageContentMimeType;643 import com.google.genai.gaos.models.interactions.Interaction;644 import com.google.genai.gaos.models.interactions.InteractionsInput;645 import com.google.genai.gaos.models.interactions.Model;646 import com.google.genai.gaos.models.interactions.ModelOutputStep;647 import com.google.genai.gaos.models.interactions.Step;648 import com.google.genai.gaos.models.interactions.TextContent;649 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;650 import java.io.InputStream;651 import java.net.URL;652 import java.util.Arrays;653 import java.util.Base64;654 import java.util.Collections;655656 Client client = new Client();657658 URL url = new URL("https://goo.gle/instrument-img");659 byte[] imageBytes;660 try (InputStream is = url.openStream()) {661 imageBytes = is.readAllBytes();662 }663 String base64ImageData = Base64.getEncoder().encodeToString(imageBytes);664665 CreateModelInteraction request =666 CreateModelInteraction.builder()667 .model(Model.of("gemini-3-flash-preview"))668 .input(669 InteractionsInput.ofContent(670 Arrays.asList(671 ImageContent.builder()672 .mimeType(ImageContentMimeType.IMAGE_JPEG)673 .data(base64ImageData)674 .build(),675 TextContent.builder()676 .text("Zoom into the expression pedals and tell me how many pedals are there?")677 .build())))678 .tools(Arrays.asList(CodeExecution.builder().build()))679 .build();680681 Interaction interaction =682 client.interactions.create(CreateInteractionRequestBody.of(request)).interaction().get();683684 for (Step step : interaction.steps().orElse(Collections.emptyList())) {685 if (step instanceof ModelOutputStep) {686 ModelOutputStep modelOutput = (ModelOutputStep) step;687 for (Content contentBlock : modelOutput.content().orElse(Collections.emptyList())) {688 if (contentBlock instanceof TextContent) {689 System.out.println("Text: " + ((TextContent) contentBlock).text().orElse(""));690 }691 }692 } else if (step instanceof CodeExecutionCallStep) {693 CodeExecutionCallStep callStep = (CodeExecutionCallStep) step;694 callStep.arguments().flatMap(args -> args.code()).ifPresent(code -> System.out.println("Code: " + code));695 } else if (step instanceof CodeExecutionResultStep) {696 CodeExecutionResultStep resultStep = (CodeExecutionResultStep) step;697 System.out.println("Output: " + resultStep.result().orElse(""));698 }699 }700701### REST702703 IMG_URL="https://goo.gle/instrument-img"704 MODEL="gemini-3-flash-preview"705706 MIME_TYPE=$(curl -sIL "$IMG_URL" | grep -i '^content-type:' | awk -F ': ' '{print $2}' | sed 's/\r$//' | head -n 1)707 if [[ -z "$MIME_TYPE" || ! "$MIME_TYPE" == image/* ]]; then708 MIME_TYPE="image/jpeg"709 fi710711 if [[ "$(uname)" == "Darwin" ]]; then712 IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -b 0)713 elif [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then714 IMAGE_B64=$(curl -sL "$IMG_URL" | base64)715 else716 IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -w0)717 fi718719 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \720 -H "x-goog-api-key: $GEMINI_API_KEY" \721 -H 'Content-Type: application/json' \722 -d '{723 "model": "'$MODEL'",724 "input": [725 {726 "type": "image",727 "mime_type":"'"$MIME_TYPE"'",728 "data": "'"$IMAGE_B64"'"729 },730 {"type": "text", "text": "Zoom into the expression pedals and tell me how many pedals are there?"}731 ],732 "tools": [{"type": "code_execution"}]733 }'734735For more details on code execution with images, see [Code Execution](https://ai.google.dev/gemini-api/docs/code-execution#images).736737### Multimodal function responses738739[Multimodal function calling](https://ai.google.dev/gemini-api/docs/function-calling#multimodal)740allows users to have function responses containing741multimodal objects allowing for improved utilization of function calling742capabilities of the model. Standard function calling only supports text-based743function responses:744745### Python746747 # This will only work for SDK newer than 2.0.0748 from google import genai749 import requests750 import base64751752 client = genai.Client()753754 # 1. Define the tool755 get_image_tool = {756 "type": "function",757 "name": "get_image",758 "description": "Retrieves the image file reference for a specific order item.",759 "parameters": {760 "type": "object",761 "properties": {762 "item_name": {763 "type": "string",764 "description": "The name or description of the item ordered (e.g., 'instrument')."765 }766 },767 "required": ["item_name"],768 },769 }770771 # 2. Send the request with tools772 interaction_1 = client.interactions.create(773 model="gemini-3-flash-preview",774 input="Show me the instrument I ordered last month.",775 tools=[get_image_tool],776 )777778 # 3. Find the function call step779 fc_step = next(s for s in interaction_1.steps if s.type == "function_call")780 print(f"Tool Call: {fc_step.name}({fc_step.arguments})")781782 # Execute tool (fetch image)783 image_path = "https://goo.gle/instrument-img"784 image_bytes = requests.get(image_path).content785 image_b64 = base64.b64encode(image_bytes).decode("utf-8")786787 # 4. Send multimodal function result back788 interaction_2 = client.interactions.create(789 model="gemini-3-flash-preview",790 previous_interaction_id=interaction_1.id,791 input=[{792 "type": "function_result",793 "name": fc_step.name,794 "call_id": fc_step.id,795 "result": [796 {"type": "text", "text": "instrument.jpg"},797 {798 "type": "image",799 "mime_type": "image/jpeg",800 "data": image_b64,801 }802 ]803 }],804 tools=[get_image_tool]805 )806807 print(f"\nFinal model response: {interaction_2.output_text}")808809### JavaScript810811 import { GoogleGenAI } from '@google/genai';812813 const client = new GoogleGenAI({});814815 const getImageTool = {816 type: 'function',817 name: 'get_image',818 description: 'Retrieves the image file reference for a specific order item.',819 parameters: {820 type: 'object',821 properties: {822 item_name: {823 type: 'string',824 description: "The name or description of the item ordered (e.g., 'instrument').",825 },826 },827 required: ['item_name'],828 },829 };830831 const interaction1 = await client.interactions.create({832 model: 'gemini-3-flash-preview',833 input: 'Use the get_image tool to show me the instrument I ordered last month.',834 tools: [getImageTool],835 });836837 const fcStep = interaction1.steps.find(s => s.type === 'function_call');838 console.log(`Tool Call: ${fcStep.name}(${JSON.stringify(fcStep.arguments)})`);839840 const imageUrl = 'https://goo.gle/instrument-img';841 const response = await fetch(imageUrl);842 const imageArrayBuffer = await response.arrayBuffer();843 const base64ImageData = Buffer.from(imageArrayBuffer).toString('base64');844845 const interaction2 = await client.interactions.create({846 model: 'gemini-3-flash-preview',847 previous_interaction_id: interaction1.id,848 input: [{849 type: 'function_result',850 name: fcStep.name,851 call_id: fcStep.id,852 result: [853 { type: 'text', text: 'instrument.jpg' },854 {855 type: 'image',856 mime_type: 'image/jpeg',857 data: base64ImageData,858 }859 ]860 }],861 tools: [getImageTool]862 });863864 console.log(`\nFinal model response: ${interaction2.output_text}`);865866### Java867868 import com.google.genai.Client;869 import com.google.genai.gaos.models.interactions.CreateModelInteraction;870 import com.google.genai.gaos.models.interactions.Function;871 import com.google.genai.gaos.models.interactions.FunctionCallStep;872 import com.google.genai.gaos.models.interactions.FunctionResultStep;873 import com.google.genai.gaos.models.interactions.FunctionResultStepResultUnion;874 import com.google.genai.gaos.models.interactions.FunctionResultSubcontent;875 import com.google.genai.gaos.models.interactions.ImageContent;876 import com.google.genai.gaos.models.interactions.ImageContentMimeType;877 import com.google.genai.gaos.models.interactions.Interaction;878 import com.google.genai.gaos.models.interactions.InteractionsInput;879 import com.google.genai.gaos.models.interactions.Model;880 import com.google.genai.gaos.models.interactions.Step;881 import com.google.genai.gaos.models.interactions.TextContent;882 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;883 import java.io.InputStream;884 import java.net.URL;885 import java.util.ArrayList;886 import java.util.Arrays;887 import java.util.Base64;888 import java.util.Collections;889 import java.util.HashMap;890 import java.util.List;891 import java.util.Map;892893 Client client = new Client();894895 Map<String, Object> itemProp = new HashMap<>();896 itemProp.put("type", "string");897 itemProp.put("description", "The name or description of the item ordered (e.g., 'instrument').");898899 Map<String, Object> properties = new HashMap<>();900 properties.put("item_name", itemProp);901902 Map<String, Object> parameters = new HashMap<>();903 parameters.put("type", "object");904 parameters.put("properties", properties);905 parameters.put("required", Arrays.asList("item_name"));906907 Function getImageTool =908 Function.builder()909 .name("get_image")910 .description("Retrieves the image file reference for a specific order item.")911 .parameters(parameters)912 .build();913914 CreateModelInteraction req1 =915 CreateModelInteraction.builder()916 .model(Model.of("gemini-3-flash-preview"))917 .input(918 InteractionsInput.of(919 "Use the get_image tool to show me the instrument I ordered last month."))920 .tools(Arrays.asList(getImageTool))921 .build();922923 Interaction interaction1 =924 client.interactions.create(CreateInteractionRequestBody.of(req1)).interaction().get();925926 FunctionCallStep fcStep = null;927 for (Step step : interaction1.steps().orElse(Collections.emptyList())) {928 if (step instanceof FunctionCallStep) {929 fcStep = (FunctionCallStep) step;930 break;931 }932 }933934 if (fcStep != null) {935 System.out.println("Tool Call: " + fcStep.name().orElse(""));936937 URL url = new URL("https://goo.gle/instrument-img");938 byte[] imageBytes;939 try (InputStream is = url.openStream()) {940 imageBytes = is.readAllBytes();941 }942 String base64ImageData = Base64.getEncoder().encodeToString(imageBytes);943944 List<FunctionResultSubcontent> subcontents = new ArrayList<>();945 subcontents.add(TextContent.builder().text("instrument.jpg").build());946 subcontents.add(947 ImageContent.builder()948 .mimeType(ImageContentMimeType.IMAGE_JPEG)949 .data(base64ImageData)950 .build());951952 FunctionResultStep funcResult =953 FunctionResultStep.builder()954 .name(fcStep.name().orElse(""))955 .callId(fcStep.id().orElse(""))956 .result(FunctionResultStepResultUnion.of(subcontents))957 .build();958959 CreateModelInteraction req2 =960 CreateModelInteraction.builder()961 .model(Model.of("gemini-3-flash-preview"))962 .input(InteractionsInput.ofStep(Arrays.asList(funcResult)))963 .tools(Arrays.asList(getImageTool))964 .previousInteractionId(interaction1.id().orElse(""))965 .build();966967 Interaction interaction2 =968 client.interactions.create(CreateInteractionRequestBody.of(req2)).interaction().get();969 System.out.println("Final model response: " + interaction2.outputText().orElse(""));970 }971972### REST973974 IMG_URL="https://goo.gle/instrument-img"975976 MIME_TYPE=$(curl -sIL "$IMG_URL" | grep -i '^content-type:' | awk -F ': ' '{print $2}' | sed 's/\r$//' | head -n 1)977 if [[ -z "$MIME_TYPE" || ! "$MIME_TYPE" == image/* ]]; then978 MIME_TYPE="image/jpeg"979 fi980981 # Check for macOS982 if [[ "$(uname)" == "Darwin" ]]; then983 IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -b 0)984 elif [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then985 IMAGE_B64=$(curl -sL "$IMG_URL" | base64)986 else987 IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -w0)988 fi989990 # 1. First interaction (triggers function call)991 # curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \992 # -H "x-goog-api-key: $GEMINI_API_KEY" \993 # -H 'Content-Type: application/json' \994 # -d '{ "model": "gemini-3-flash-preview", "input": "Show me the instrument I ordered last month.", "tools": [...] }'995996 # 2. Send multimodal function result back (Replace INTERACTION_ID and CALL_ID)997 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \998 -H "x-goog-api-key: $GEMINI_API_KEY" \999 -H 'Content-Type: application/json' \1000 -d '{1001 "model": "gemini-3-flash-preview",1002 "previous_interaction_id": "INTERACTION_ID",1003 "input": [{1004 "type": "function_result",1005 "name": "get_image",1006 "call_id": "CALL_ID",1007 "result": [1008 { "type": "text", "text": "instrument.jpg" },1009 {1010 "type": "image",1011 "mime_type": "'"$MIME_TYPE"'",1012 "data": "'"$IMAGE_B64"'"1013 }1014 ]1015 }]1016 }'10171018### Combine built-in tools and function calling10191020Gemini 3 allows the use of built-in tools (like Google Search, URL1021context, and [more](https://ai.google.dev/gemini-api/docs/tools)) and custom [function calling](https://ai.google.dev/gemini-api/docs/function-calling) tools in the same API call, allowing for1022more complex workflows.10231024### Python10251026 from google import genai1027 from google.genai import types10281029 client = genai.Client()10301031 getWeather = {1032 "type": "function",1033 "name": "getWeather",1034 "description": "Gets the weather for a requested city.",1035 "parameters": {1036 "type": "object",1037 "properties": {1038 "city": {1039 "type": "string",1040 "description": "The city and state, e.g. Utqiaġvik, Alaska",1041 },1042 },1043 "required": ["city"],1044 },1045 }10461047 interaction = client.interactions.create(1048 model="gemini-3-flash-preview",1049 input="What is the northernmost city in the United States? What's the weather like there today?",1050 tools=[1051 {"type": "google_search"},1052 getWeather1053 ],1054 )10551056 fc_step = next((s for s in interaction.steps if s.type == "function_call"), None)10571058 if fc_step:1059 result = {"response": "Very cold. 22 degrees Fahrenheit."}10601061 final_interaction = client.interactions.create(1062 model="gemini-3-flash-preview",1063 input=[1064 {"type": "function_result", "name": fc_step.name, "call_id": fc_step.id, "result": result}1065 ],1066 tools=[1067 {"type": "google_search"},1068 getWeather1069 ],1070 previous_interaction_id=interaction.id,1071 )10721073 print(final_interaction.output_text)10741075### JavaScript10761077 import { GoogleGenAI, Type } from '@google/genai';10781079 const client = new GoogleGenAI({});10801081 const getWeatherDeclaration = {1082 type: 'function',1083 name: 'getWeather',1084 description: 'Gets the weather for a requested city.',1085 parameters: {1086 type: Type.OBJECT,1087 properties: {1088 city: {1089 type: Type.STRING,1090 description: 'The city and state, e.g. Utqiaġvik, Alaska',1091 },1092 },1093 required: ['city'],1094 },1095 };10961097 const interaction = await client.interactions.create({1098 model: 'gemini-3-flash-preview',1099 input: "What is the northernmost city in the United States? What's the weather like there today?",1100 tools: [1101 { type: "google_search" },1102 getWeatherDeclaration1103 ],1104 });11051106 const fcStep = interaction.steps.find(s => s.type === 'function_call');11071108 if (fcStep) {1109 const result = { response: "Very cold. 22 degrees Fahrenheit." };11101111 const finalInteraction = await client.interactions.create({1112 model: 'gemini-3-flash-preview',1113 input: [1114 { type: 'function_result', name: fcStep.name, call_id: fcStep.id, result: result }1115 ],1116 tools: [1117 { type: "google_search" },1118 getWeatherDeclaration1119 ],1120 previous_interaction_id: interaction.id,1121 });11221123 console.log(finalInteraction.output_text);1124 }11251126### Java11271128 import com.google.genai.Client;1129 import com.google.genai.gaos.models.interactions.CreateModelInteraction;1130 import com.google.genai.gaos.models.interactions.Function;1131 import com.google.genai.gaos.models.interactions.FunctionCallStep;1132 import com.google.genai.gaos.models.interactions.FunctionResultStep;1133 import com.google.genai.gaos.models.interactions.FunctionResultStepResultUnion;1134 import com.google.genai.gaos.models.interactions.GoogleSearch;1135 import com.google.genai.gaos.models.interactions.Interaction;1136 import com.google.genai.gaos.models.interactions.InteractionsInput;1137 import com.google.genai.gaos.models.interactions.Model;1138 import com.google.genai.gaos.models.interactions.Step;1139 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;1140 import java.util.Arrays;1141 import java.util.Collections;1142 import java.util.HashMap;1143 import java.util.Map;11441145 Client client = new Client();11461147 Map<String, Object> cityProp = new HashMap<>();1148 cityProp.put("type", "string");1149 cityProp.put("description", "The city and state, e.g. Utqiaġvik, Alaska");11501151 Map<String, Object> properties = new HashMap<>();1152 properties.put("city", cityProp);11531154 Map<String, Object> parameters = new HashMap<>();1155 parameters.put("type", "object");1156 parameters.put("properties", properties);1157 parameters.put("required", Arrays.asList("city"));11581159 Function getWeather =1160 Function.builder()1161 .name("getWeather")1162 .description("Gets the weather for a requested city.")1163 .parameters(parameters)1164 .build();11651166 CreateModelInteraction request =1167 CreateModelInteraction.builder()1168 .model(Model.of("gemini-3-flash-preview"))1169 .input(1170 InteractionsInput.of(1171 "What is the northernmost city in the United States? What's the weather like there today?"))1172 .tools(Arrays.asList(GoogleSearch.builder().build(), getWeather))1173 .build();11741175 Interaction interaction =1176 client.interactions.create(CreateInteractionRequestBody.of(request)).interaction().get();11771178 FunctionCallStep fcStep = null;1179 for (Step step : interaction.steps().orElse(Collections.emptyList())) {1180 if (step instanceof FunctionCallStep) {1181 fcStep = (FunctionCallStep) step;1182 break;1183 }1184 }11851186 if (fcStep != null) {1187 FunctionResultStep funcResult =1188 FunctionResultStep.builder()1189 .name(fcStep.name().orElse(""))1190 .callId(fcStep.id().orElse(""))1191 .result(1192 FunctionResultStepResultUnion.of(1193 "{\"response\": \"Very cold. 22 degrees Fahrenheit.\"}"))1194 .build();11951196 CreateModelInteraction finalRequest =1197 CreateModelInteraction.builder()1198 .model(Model.of("gemini-3-flash-preview"))1199 .input(InteractionsInput.ofStep(Arrays.asList(funcResult)))1200 .tools(Arrays.asList(GoogleSearch.builder().build(), getWeather))1201 .previousInteractionId(interaction.id().orElse(""))1202 .build();12031204 Interaction finalInteraction =1205 client.interactions.create(CreateInteractionRequestBody.of(finalRequest)).interaction().get();1206 System.out.println(finalInteraction.outputText().orElse(""));1207 }12081209## Migration from Gemini 2.512101211Gemini 3 is our most capable model family to date and offers a stepwise1212improvement over Gemini 2.5. When migrating, consider the following:12131214- **Thinking:** If you were previously using complex prompt engineering (like chain of thought) to force Gemini 2.5 to reason, try Gemini 3 with `thinking_level: "high"` and simplified prompts.1215- **Temperature settings:** If your existing code explicitly sets temperature (especially to low values for deterministic outputs), we recommend removing this parameter and using the Gemini 3 default of 1.0 to avoid potential looping issues or performance degradation on complex tasks.1216- **PDF \& document understanding:** If you relied on specific behavior for dense document parsing, test the new `media_resolution_high` setting to ensure continued accuracy.1217- **Token consumption:** Migrating to Gemini 3 defaults may **increase** token usage for PDFs but **decrease** token usage for video. If requests now exceed the context window due to higher default resolutions, we recommend explicitly reducing the media resolution.1218- **Image segmentation:** Image segmentation capabilities (returning pixel-level masks for objects) are not supported in Gemini 3 Pro or Gemini 3 Flash. For workloads requiring built-in image segmentation, we recommend continuing to use Gemini 2.5 Flash with thinking turned off.1219- **Computer Use:** Gemini 3 Pro and Gemini 3 Flash support [Computer1220 Use](https://ai.google.dev/gemini-api/docs/computer-use). Unlike the 2.5 series, you don't need to use a separate model to access the Computer Use tool.1221- **Tool support** : [Combining built-in tools with function calling](https://ai.google.dev/gemini-api/docs/tool-combination) is now supported for Gemini 3 models. [Maps1222 grounding](https://ai.google.dev/gemini-api/docs/maps-grounding) is also now supported for Gemini 3 models.12231224## OpenAI compatibility12251226For users utilizing the [OpenAI compatibility layer](https://ai.google.dev/gemini-api/docs/openai),1227standard parameters (OpenAI's `reasoning_effort`) are automatically mapped to1228Gemini (`thinking_level`) equivalents.12291230## Prompting best practices12311232Gemini 3 is a reasoning model, which changes how you should prompt.12331234- **Precise instructions:** Be concise in your input prompts. Gemini 3 responds best to direct, clear instructions. It may over-analyze verbose or overly complex prompt engineering techniques used for older models.1235- **Output verbosity:** By default, Gemini 3 is less verbose and prefers providing direct, efficient answers. If your use case requires a more conversational or "chatty" persona, you must explicitly steer the model in the prompt (e.g., "Explain this as a friendly, talkative assistant").1236- **Context management:** When working with large datasets (e.g., entire books, codebases, or long videos), place your specific instructions or questions at the end of the prompt, after the data context. Anchor the model's reasoning to the provided data by starting your question with a phrase like, "Based on the preceding information...".12371238Learn more about prompt design strategies in the [prompt engineering guide](https://ai.google.dev/gemini-api/docs/prompting-strategies).12391240## FAQ124112421. **What is the knowledge cutoff for Gemini 3?** Gemini 3 models have a1243 knowledge cutoff of January 2025. For more recent information, use the1244 [Search Grounding](https://ai.google.dev/gemini-api/docs/google-search) tool.124512462. **What are the context window limits?** Gemini 3 models support a 1 million1247 token input context window and up to 64k tokens of output.124812493. **Is there a free tier for Gemini 3?** Gemini 3 Flash1250 `gemini-3-flash-preview` has a free tier in the Gemini API. You can try1251 Gemini 3.1 Pro and 3 Flash at no cost in Google AI Studio, but there1252 is no free tier available for `gemini-3.1-pro-preview` in the Gemini API.125312544. **Will my old `thinking_budget` code still work?** Yes, `thinking_budget` is1255 still supported for backward compatibility, but we recommend migrating to1256 `thinking_level` for more predictable performance. Don't use both in the same1257 request.125812595. **Does Gemini 3 support the Batch API?** Yes, Gemini 3 supports the1260 [Batch API](https://ai.google.dev/gemini-api/docs/batch-api).126112626. **Is Context Caching supported?** Yes, [Context Caching](https://ai.google.dev/gemini-api/docs/caching) is supported for Gemini 3.126312647. **Which tools are supported in Gemini 3?** Gemini 3 supports1265 [Google Search](https://ai.google.dev/gemini-api/docs/google-search),1266 [Grounding with Google Maps](https://ai.google.dev/gemini-api/docs/maps-grounding),1267 [File Search](https://ai.google.dev/gemini-api/docs/file-search),1268 [Code Execution](https://ai.google.dev/gemini-api/docs/code-execution), and1269 [URL Context](https://ai.google.dev/gemini-api/docs/url-context). It also supports1270 standard [Function Calling](https://ai.google.dev/gemini-api/docs/function-calling) for1271 your own custom tools, and in1272 [combination with built-in tools](https://ai.google.dev/gemini-api/docs/tool-combination).127312748. **What is `gemini-3.1-pro-preview-customtools`?** If you are using1275 `gemini-3.1-pro-preview` and the model ignores your custom tools in favor of1276 bash commands, try the `gemini-3.1-pro-preview-customtools` model instead.1277 More info \[here\]\[customtools-model\].