Repository Public
1# Gemini thinking23> [!NOTE]4> **Note** : This version of the page covers the new [Interactions API](https://ai.google.dev/gemini-api/docs/interactions/interactions-overview), which is currently in Beta. 5> For stable production deployments, we recommend you continue to use the `generateContent` API. You can use the toggle on this page to switch between the versions.67The [Gemini 3 and 2.5 series models](https://ai.google.dev/gemini-api/docs/models) use a8"thinking process" that significantly improves their reasoning and multi-step9planning abilities, making them highly effective for complex tasks such as10coding, advanced mathematics, and data analysis.1112When you use a thinking model, Gemini reasons internally before responding. The Interactions API surfaces this reasoning via `thought` steps, dedicated steps that appear chronologically alongside function calls, user inputs or model outputs in the `steps` array.1314Every thought step contains two fields:1516| Field | Required | Description |17|---|---|---|18| `signature` | ✅ Yes | An encrypted representation of the model's internal reasoning state. Always present, even when the model performs minimal reasoning. |19| `summary` | ❌ No | An array of content (text and/or images) summarizing the reasoning. May be empty depending on the [`thinking_summaries`](https://ai.google.dev/api/interactions-api) config, whether the model performed enough reasoning, or the content type (for example, image latents may not have text summaries). |2021> [!NOTE]22> **Note:** The Interactions API handles thoughts and signatures differently than the `generateContent` API: 23> - In the `generateContent` API, there are no dedicated thought blocks. Because of this, signatures are metadata that can be attached to any part, such as living inside `functionCall` parts or the final part of a response. 24> - In the Interactions API, thoughts are a first-class representation as dedicated `thought` steps. Because of this signatures are limited exclusively to two known locations, `thought` steps, or built-in tool steps (like `google_search_call`/ `google_search_result`). They never appear on user inputs, model outputs, or standard function calls.2526## Interactions with thinking2728Initiating an interaction with a thinking model is similar to any other interaction request. Specify one of the [models with thinking support](https://ai.google.dev/gemini-api/docs/interactions/thinking#thinking-levels) in the `model` field:2930### Python3132 from google import genai3334 client = genai.Client()3536 interaction = client.interactions.create(37 model="gemini-3-flash-preview",38 input="Explain the concept of Occam's Razor and provide a simple, everyday example."39 )40 print(interaction.output_text)4142### JavaScript4344 import { GoogleGenAI } from "@google/genai";4546 const client = new GoogleGenAI({});4748 const interaction = await client.interactions.create({49 model: "gemini-3-flash-preview",50 input: "Explain the concept of Occam's Razor and provide a simple, everyday example."51 });52 console.log(interaction.output_text);5354### REST5556 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \57 -H "x-goog-api-key: $GEMINI_API_KEY" \58 -H "Api-Revision: 2026-05-20" \59 -H 'Content-Type: application/json' \60 -d '{61 "model": "gemini-3-flash-preview",62 "input": "Explain the concept of Occam'\''s Razor and provide a simple example."63 }'6465## Thought summaries6667Thought summaries provide insights into the model's internal reasoning process.68By default, only the final output is returned. You can enable thought summaries69with `thinking_summaries`:7071### Python7273 from google import genai7475 client = genai.Client()7677 interaction = client.interactions.create(78 model="gemini-3-flash-preview",79 input="What is the sum of the first 50 prime numbers?",80 generation_config={81 "thinking_summaries": "auto"82 }83 )8485 for step in interaction.steps:86 if step.type == "thought":87 print("Thought summary:")88 if step.summary:89 for content_block in step.summary:90 if content_block.type == "text":91 print(content_block.text)92 print()93 elif step.type == "model_output":94 for content_block in step.content:95 if content_block.type == "text":96 print("Answer:")97 print(content_block.text)98 print()99100### JavaScript101102 import { GoogleGenAI } from "@google/genai";103104 const client = new GoogleGenAI({});105106 const interaction = await client.interactions.create({107 model: "gemini-3-flash-preview",108 input: "What is the sum of the first 50 prime numbers?",109 generation_config: {110 thinking_summaries: "auto"111 }112 });113114 for (const step of interaction.steps) {115 if (step.type === "thought") {116 console.log("Thought summary:");117 if (step.summary) {118 for (const contentBlock of step.summary) {119 if (contentBlock.type === "text") console.log(contentBlock.text);120 }121 }122 } else if (step.type === "model_output") {123 for (const contentBlock of step.content) {124 if (contentBlock.type === "text") {125 console.log("Answer:");126 console.log(contentBlock.text);127 }128 }129 }130 }131132### REST133134 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \135 -H "x-goog-api-key: $GEMINI_API_KEY" \136 -H "Api-Revision: 2026-05-20" \137 -H 'Content-Type: application/json' \138 -d '{139 "model": "gemini-3-flash-preview",140 "input": "What is the sum of the first 50 prime numbers?",141 "generation_config": {142 "thinking_summaries": "auto"143 }144 }'145146A thought block may contain **only a signature with no summary** in these cases:147148- Simple requests, where the model didn't reason enough to generate a summary149- `thinking_summaries: "none"`, where summaries are explicitly disabled150- Certain thought content types, such as images, may not have text summaries151152Your code should always handle thought blocks where `summary` is empty or absent.153154## Streaming with thinking155156Use streaming to receive incremental thought summaries during generation.157Thought blocks are delivered using Server-Sent Events (SSE) with two distinct158delta types:159160| Delta type | Contains | When sent |161|---|---|---|162| `thought_summary` | Text or image summary content | One or more deltas with incremental summary |163| `thought_signature` | The cryptographic signature | the last delta before `step.stop` |164165### Python166167 from google import genai168169 client = genai.Client()170171 prompt = """172 Alice, Bob, and Carol each live in a different house on the same street: red, green, and blue.173 Alice does not live in the red house.174 Bob does not live in the green house.175 Carol does not live in the red or green house.176 Which house does each person live in?177 """178179 thoughts = ""180 answer = ""181182 stream = client.interactions.create(183 model="gemini-3-flash-preview",184 input=prompt,185 generation_config={186 "thinking_summaries": "auto"187 },188 stream=True189 )190191 for event in stream:192 if event.event_type == "step.delta":193 if event.delta.type == "thought_summary":194 if not thoughts:195 print("Thinking...")196 summary_text = event.delta.content.text197 print(f"[Thought] {summary_text}", end="")198 thoughts += summary_text199 elif event.delta.type == "text" and event.delta.text:200 if not answer:201 print("\nAnswer:")202 print(event.delta.text, end="")203 answer += event.delta.text204205### JavaScript206207 import { GoogleGenAI } from "@google/genai";208209 const client = new GoogleGenAI({});210211 const prompt = `Alice, Bob, and Carol each live in a different house on the same212 street: red, green, and blue. Alice does not live in the red house.213 Bob does not live in the green house.214 Carol does not live in the red or green house.215 Which house does each person live in?`;216217 let thoughts = "";218 let answer = "";219220 const stream = await client.interactions.create({221 model: "gemini-3-flash-preview",222 input: prompt,223 generation_config: {224 thinking_summaries: "auto"225 },226 stream: true227 });228229 for await (const event of stream) {230 if (event.event_type === "step.delta") {231 if (event.delta.type === "thought_summary") {232 if (!thoughts) console.log("Thinking...");233 const text = event.delta.content?.text || "";234 process.stdout.write(`[Thought] ${text}`);235 thoughts += text;236 } else if (event.delta.type === "text" && event.delta.text) {237 if (!answer) console.log("\nAnswer:");238 process.stdout.write(event.delta.text);239 answer += event.delta.text;240 }241 }242 }243244### REST245246 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \247 -H "x-goog-api-key: $GEMINI_API_KEY" \248 -H "Api-Revision: 2026-05-20" \249 -H 'Content-Type: application/json' \250 --no-buffer \251 -d '{252 "model": "gemini-3-flash-preview",253 "input": "Alice, Bob, and Carol each live in a different house on the same street: red, green, and blue. Alice does not live in the red house. Bob does not live in the green house. Carol does not live in the red or green house. Which house does each person live in?",254 "generation_config": {255 "thinking_summaries": "auto"256 },257 "stream": true258 }'259260The streaming response uses Server-Sent Events (SSE) and is composed of steps261and events, for example:262263 event: interaction.created264 data: {"interaction":{"id":"v1_xxx","status":"in_progress","object":"interaction","model":"gemini-3-flash-preview"},"event_type":"interaction.created"}265266 event: step.start267 data: {"index":0,"step":{"signature":"","summary":[{"text":"**Evaluating the clues**\n\nI'm considering...","type":"text"}],"type":"thought"},"event_type":"step.start"}268269 event: step.delta270 data: {"index":0,"delta":{"signature":"EpoGCpcGAXLI2nx/...","type":"thought_signature"},"event_type":"step.delta"}271272 event: step.stop273 data: {"index":0,"event_type":"step.stop"}274275 event: step.start276 data: {"index":1,"step":{"content":[{"text":"Based on the clues provided, here","type":"text"}],"type":"model_output"},"event_type":"step.start"}277278 event: step.delta279 data: {"index":1,"delta":{"text":" is the answer to your question...","type":"text"},"event_type":"step.delta"}280281 event: step.stop282 data: {"index":1,"event_type":"step.stop"}283284 event: interaction.completed285 data: {"interaction":{"id":"v1_xxx","status":"completed","usage":{"total_tokens":530,"total_input_tokens":62,"total_output_tokens":171,"total_thought_tokens":297}},"event_type":"interaction.completed"}286287 event: done288 data: [DONE]289290## Controlling thinking291292Gemini models engage in dynamic thinking by default, automatically adjusting293the amount of reasoning effort based on the complexity of the request. You can control this behavior using the `thinking_level` parameter.294295| Model | Default Thinking | Levels Supported |296|---|---|---|297| gemini-3.1-pro-preview | On (high) | low, medium, high |298| gemini-3-flash-preview | On (high) | minimal, low, medium, high |299| gemini-3-pro-preview | On (high) | low, high |300| gemini-2.5-pro | On | low, medium, high |301| gemini-2.5-flash | On | low, medium, high |302| gemini-2.5-flash-lite | Off | low, medium, high |303304### Python305306 from google import genai307308 client = genai.Client()309310 interaction = client.interactions.create(311 model="gemini-3-flash-preview",312 input="Provide a list of 3 famous physicists and their key contributions",313 generation_config={314 "thinking_level": "low"315 }316 )317 print(interaction.output_text)318319### JavaScript320321 import { GoogleGenAI } from "@google/genai";322323 const client = new GoogleGenAI({});324325 const interaction = await client.interactions.create({326 model: "gemini-3-flash-preview",327 input: "Provide a list of 3 famous physicists and their key contributions",328 generation_config: {329 thinking_level: "low"330 }331 });332 console.log(interaction.output_text);333334### REST335336 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \337 -H "x-goog-api-key: $GEMINI_API_KEY" \338 -H "Api-Revision: 2026-05-20" \339 -H 'Content-Type: application/json' \340 -d '{341 "model": "gemini-3-flash-preview",342 "input": "Provide a list of 3 famous physicists and their key contributions",343 "generation_config": {344 "thinking_level": "low"345 }346 }'347348## Thought signatures349350Thought signatures are encrypted representations of the model's internal reasoning. They are required to maintain reasoning continuity across multi-turn interactions.351352The Interactions API makes handling thought signatures much simpler than the `generateContent` API.353354### Stateful mode (Recommended)355356By default, when you use the Interactions API in stateful mode (by setting `store: true` and passing the `previous_interaction_id` in subsequent turns), the server automatically manages the conversation state, including all thought blocks and signatures. In this mode, you do not need to do anything regarding signatures. They are handled entirely on the server side.357358### Stateless mode359360If you are managing the conversation state yourself (stateless mode) and passing the full history of inputs and outputs in each request:361362- You **MUST** always resend all `thought` blocks exactly as they were received from the model.363- You should **NOT** remove or modify thought blocks from the history, as they contain the signatures required for the model to continue its reasoning.364- When switching models within a session, you should still resend the previous model's thought blocks. The backend manages compatibility.365366> [!NOTE]367> **Note:** Built-in tools such as Google Search can carry their own distinct signatures on the call/result blocks. In stateless mode, you must also resend these tool result signatures in subsequent turns.368369## Pricing370371When thinking is turned on, response pricing is the sum of output372tokens and thinking tokens. You can get the total number of generated thinking373tokens from the `total_thought_tokens` field.374375### Python376377 print("Thoughts tokens:", interaction.usage.total_thought_tokens)378 print("Output tokens:", interaction.usage.total_output_tokens)379380### JavaScript381382 console.log(`Thoughts tokens: ${interaction.usage.total_thought_tokens}`);383 console.log(`Output tokens: ${interaction.usage.total_output_tokens}`);384385Thinking models generate full thoughts to improve the quality of the final386response, and then output [summaries](https://ai.google.dev/gemini-api/docs/interactions/thinking#summaries) to provide insight into the387thought process. Pricing is based on the full thought tokens the model needs to388generate, despite only the summary being output from the API.389390You can learn more about tokens in the [Token counting](https://ai.google.dev/gemini-api/docs/interactions/tokens) guide.391392## Best practices393394Use thinking models efficiently by following these guidelines.395396- **Review reasoning**: Analyze thought summaries to understand failures and improve prompts.397- **Control thinking budget**: Prompt the model to think less for lengthy outputs to save tokens.398- **Simple tasks**: Use minimal thinking for fact retrieval or classification (e.g., "Where was DeepMind founded?").399- **Moderate tasks**: Use default thinking for comparing concepts or creative reasoning (e.g., Compare electric and hybrid cars).400- **Complex tasks**: Use maximum thinking for advanced coding, math, or multi-step planning (e.g., Solve AIME math problems).401402## What's next403404- [Text generation](https://ai.google.dev/gemini-api/docs/interactions/text-generation): Basic text responses405- [Function calling](https://ai.google.dev/gemini-api/docs/interactions/function-calling): Connect to tools406- [Gemini 3 guide](https://ai.google.dev/gemini-api/docs/interactions/gemini-3): Model-specific features