Repository Public
1The [Gemini 3 and 2.5 series models](https://ai.google.dev/gemini-api/docs/models) use a2"thinking process" that significantly improves their reasoning and multi-step3planning abilities, making them highly effective for complex tasks such as4coding, advanced mathematics, and data analysis.56When 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.78Every thought step contains two fields:910| Field | Required | Description |11|---|---|---|12| `signature` | ✅ Yes | An encrypted representation of the model's internal reasoning state. Always present, even when the model performs minimal reasoning. |13| `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). |1415> [!NOTE]16> **Note:** The Interactions API handles thoughts and signatures differently than the `generateContent` API: - 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. - 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.1718## Interactions with thinking1920Initiating 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/thinking#thinking-levels) in the `model` field:2122### Python2324 from google import genai2526 client = genai.Client()2728 interaction = client.interactions.create(29 model="gemini-3.8-flash",30 input="Explain the concept of Occam's Razor and provide a simple, everyday example."31 )32 print(interaction.output_text)3334### JavaScript3536 import { GoogleGenAI } from "@google/genai";3738 const client = new GoogleGenAI({});3940 const interaction = await client.interactions.create({41 model: "gemini-3.8-flash",42 input: "Explain the concept of Occam's Razor and provide a simple, everyday example."43 });44 console.log(interaction.output_text);4546### Java4748 import com.google.genai.Client;49 import com.google.genai.gaos.models.interactions.CreateModelInteraction;50 import com.google.genai.gaos.models.interactions.Interaction;51 import com.google.genai.gaos.models.interactions.InteractionsInput;52 import com.google.genai.gaos.models.interactions.Model;53 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;5455 Client client = new Client();5657 CreateModelInteraction params =58 CreateModelInteraction.builder()59 .model(Model.of("gemini-3.8-flash"))60 .input(61 InteractionsInput.of(62 "Explain the concept of Occam's Razor and provide a simple, everyday example."))63 .build();6465 Interaction interaction =66 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();6768 System.out.println(interaction.outputText().orElse(""));6970### REST7172 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \73 -H "x-goog-api-key: $GEMINI_API_KEY" \74 -H 'Content-Type: application/json' \75 -d '{76 "model": "gemini-3.8-flash",77 "input": "Explain the concept of Occam'\''s Razor and provide a simple example."78 }'7980## Thought summaries8182Thought summaries provide insights into the model's internal reasoning process.83By default, only the final output is returned. You can enable thought summaries84with `thinking_summaries`:8586### Python8788 from google import genai8990 client = genai.Client()9192 interaction = client.interactions.create(93 model="gemini-3.8-flash",94 input="What is the sum of the first 50 prime numbers?",95 generation_config={96 "thinking_summaries": "auto"97 }98 )99100 for step in interaction.steps:101 if step.type == "thought":102 print("Thought summary:")103 if step.summary:104 for content_block in step.summary:105 if content_block.type == "text":106 print(content_block.text)107 print()108 elif step.type == "model_output":109 for content_block in step.content:110 if content_block.type == "text":111 print("Answer:")112 print(content_block.text)113 print()114115### JavaScript116117 import { GoogleGenAI } from "@google/genai";118119 const client = new GoogleGenAI({});120121 const interaction = await client.interactions.create({122 model: "gemini-3.8-flash",123 input: "What is the sum of the first 50 prime numbers?",124 generation_config: {125 thinking_summaries: "auto"126 }127 });128129 for (const step of interaction.steps) {130 if (step.type === "thought") {131 console.log("Thought summary:");132 if (step.summary) {133 for (const contentBlock of step.summary) {134 if (contentBlock.type === "text") console.log(contentBlock.text);135 }136 }137 } else if (step.type === "model_output") {138 for (const contentBlock of step.content) {139 if (contentBlock.type === "text") {140 console.log("Answer:");141 console.log(contentBlock.text);142 }143 }144 }145 }146147### Java148149 import com.google.genai.Client;150 import com.google.genai.gaos.models.interactions.Content;151 import com.google.genai.gaos.models.interactions.CreateModelInteraction;152 import com.google.genai.gaos.models.interactions.GenerationConfig;153 import com.google.genai.gaos.models.interactions.Interaction;154 import com.google.genai.gaos.models.interactions.InteractionsInput;155 import com.google.genai.gaos.models.interactions.Model;156 import com.google.genai.gaos.models.interactions.ModelOutputStep;157 import com.google.genai.gaos.models.interactions.Step;158 import com.google.genai.gaos.models.interactions.TextContent;159 import com.google.genai.gaos.models.interactions.ThinkingSummaries;160 import com.google.genai.gaos.models.interactions.ThoughtStep;161 import com.google.genai.gaos.models.interactions.ThoughtSummaryContent;162 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;163 import java.util.Collections;164165 Client client = new Client();166167 CreateModelInteraction params =168 CreateModelInteraction.builder()169 .model(Model.of("gemini-3.8-flash"))170 .input(InteractionsInput.of("What is the sum of the first 50 prime numbers?"))171 .generationConfig(172 GenerationConfig.builder().thinkingSummaries(ThinkingSummaries.AUTO).build())173 .build();174175 Interaction interaction =176 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();177178 for (Step step : interaction.steps().orElse(Collections.emptyList())) {179 if (step instanceof ThoughtStep thoughtStep) {180 System.out.println("Thought summary:");181 for (ThoughtSummaryContent contentBlock : thoughtStep.summary().orElse(Collections.emptyList())) {182 if (contentBlock instanceof TextContent textContent) {183 System.out.println(textContent.text().orElse(""));184 }185 }186 System.out.println();187 } else if (step instanceof ModelOutputStep outputStep) {188 for (Content contentBlock : outputStep.content().orElse(Collections.emptyList())) {189 if (contentBlock instanceof TextContent textContent) {190 System.out.println("Answer:");191 System.out.println(textContent.text().orElse(""));192 System.out.println();193 }194 }195 }196 }197198### REST199200 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \201 -H "x-goog-api-key: $GEMINI_API_KEY" \202 -H 'Content-Type: application/json' \203 -d '{204 "model": "gemini-3.8-flash",205 "input": "What is the sum of the first 50 prime numbers?",206 "generation_config": {207 "thinking_summaries": "auto"208 }209 }'210211A thought block may contain **only a signature with no summary** in these cases:212213- Simple requests, where the model didn't reason enough to generate a summary214- `thinking_summaries: "none"`, where summaries are explicitly disabled215- Certain thought content types, such as images, may not have text summaries216217Your code should always handle thought blocks where `summary` is empty or absent.218219## Streaming with thinking220221Use streaming to receive incremental thought summaries during generation.222Thought blocks are delivered using Server-Sent Events (SSE) with two distinct223delta types:224225| Delta type | Contains | When sent |226|---|---|---|227| `thought_summary` | Text or image summary content | One or more deltas with incremental summary |228| `thought_signature` | The cryptographic signature | the last delta before `step.stop` |229230### Python231232 from google import genai233234 client = genai.Client()235236 prompt = """237 Alice, Bob, and Carol each live in a different house on the same street: red, green, and blue.238 Alice does not live in the red house.239 Bob does not live in the green house.240 Carol does not live in the red or green house.241 Which house does each person live in?242 """243244 thoughts = ""245 answer = ""246247 stream = client.interactions.create(248 model="gemini-3.8-flash",249 input=prompt,250 generation_config={251 "thinking_summaries": "auto"252 },253 stream=True254 )255256 for event in stream:257 if event.event_type == "step.delta":258 if event.delta.type == "thought_summary":259 if not thoughts:260 print("Thinking...")261 summary_text = event.delta.content.text262 print(f"[Thought] {summary_text}", end="")263 thoughts += summary_text264 elif event.delta.type == "text" and event.delta.text:265 if not answer:266 print("\nAnswer:")267 print(event.delta.text, end="")268 answer += event.delta.text269270### JavaScript271272 import { GoogleGenAI } from "@google/genai";273274 const client = new GoogleGenAI({});275276 const prompt = `Alice, Bob, and Carol each live in a different house on the same277 street: red, green, and blue. Alice does not live in the red house.278 Bob does not live in the green house.279 Carol does not live in the red or green house.280 Which house does each person live in?`;281282 let thoughts = "";283 let answer = "";284285 const stream = await client.interactions.create({286 model: "gemini-3.8-flash",287 input: prompt,288 generation_config: {289 thinking_summaries: "auto"290 },291 stream: true292 });293294 for await (const event of stream) {295 if (event.event_type === "step.delta") {296 if (event.delta.type === "thought_summary") {297 if (!thoughts) console.log("Thinking...");298 const text = event.delta.content?.text || "";299 process.stdout.write(`[Thought] ${text}`);300 thoughts += text;301 } else if (event.delta.type === "text" && event.delta.text) {302 if (!answer) console.log("\nAnswer:");303 process.stdout.write(event.delta.text);304 answer += event.delta.text;305 }306 }307 }308309### Java310311 import com.google.genai.Client;312 import com.google.genai.gaos.models.interactions.Content;313 import com.google.genai.gaos.models.interactions.CreateModelInteraction;314 import com.google.genai.gaos.models.interactions.GenerationConfig;315 import com.google.genai.gaos.models.interactions.InteractionSSEEvent;316 import com.google.genai.gaos.models.interactions.InteractionSSEStreamEvent;317 import com.google.genai.gaos.models.interactions.InteractionsInput;318 import com.google.genai.gaos.models.interactions.Model;319 import com.google.genai.gaos.models.interactions.StepDelta;320 import com.google.genai.gaos.models.interactions.StepDeltaData;321 import com.google.genai.gaos.models.interactions.TextContent;322 import com.google.genai.gaos.models.interactions.TextDelta;323 import com.google.genai.gaos.models.interactions.ThinkingSummaries;324 import com.google.genai.gaos.models.interactions.ThoughtSummaryDelta;325 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;326 import com.google.genai.gaos.models.operations.CreateInteractionResponse;327 import com.google.genai.gaos.utils.EventStream;328329 Client client = new Client();330331 String prompt =332 "Alice, Bob, and Carol each live in a different house on the same street: red, green, and blue.\n"333 + "Alice does not live in the red house.\n"334 + "Bob does not live in the green house.\n"335 + "Carol does not live in the red or green house.\n"336 + "Which house does each person live in?";337338 StringBuilder thoughts = new StringBuilder();339 StringBuilder answer = new StringBuilder();340341 CreateModelInteraction params =342 CreateModelInteraction.builder()343 .model(Model.of("gemini-3.8-flash"))344 .input(InteractionsInput.of(prompt))345 .generationConfig(346 GenerationConfig.builder().thinkingSummaries(ThinkingSummaries.AUTO).build())347 .stream(true)348 .build();349350 CreateInteractionResponse response =351 client.interactions.create(CreateInteractionRequestBody.of(params));352353 try (EventStream<InteractionSSEStreamEvent> stream = response.events()) {354 for (InteractionSSEStreamEvent streamEvent : stream) {355 InteractionSSEEvent event = streamEvent.data().orElse(null);356 if (event instanceof StepDelta stepDelta) {357 StepDeltaData delta = stepDelta.delta().orElse(null);358 if (delta instanceof ThoughtSummaryDelta thoughtDelta) {359 Content content = thoughtDelta.content().orElse(null);360 if (content instanceof TextContent textContent) {361 if (thoughts.length() == 0) {362 System.out.println("Thinking...");363 }364 String summaryText = textContent.text().orElse("");365 System.out.print("[Thought] " + summaryText);366 thoughts.append(summaryText);367 }368 } else if (delta instanceof TextDelta textDelta) {369 String text = textDelta.text().orElse("");370 if (!text.isEmpty()) {371 if (answer.length() == 0) {372 System.out.println("\nAnswer:");373 }374 System.out.print(text);375 answer.append(text);376 }377 }378 }379 }380 }381382### REST383384 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \385 -H "x-goog-api-key: $GEMINI_API_KEY" \386 -H 'Content-Type: application/json' \387 --no-buffer \388 -d '{389 "model": "gemini-3.8-flash",390 "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?",391 "generation_config": {392 "thinking_summaries": "auto"393 },394 "stream": true395 }'396397The streaming response uses Server-Sent Events (SSE) and is composed of steps398and events, for example:399400 event: interaction.created401 data: {"interaction":{"id":"v1_xxx","status":"in_progress","object":"interaction","model":"gemini-3.8-flash"},"event_type":"interaction.created"}402403 event: step.start404 data: {"index":0,"step":{"signature":"","summary":[{"text":"**Evaluating the clues**\n\nI'm considering...","type":"text"}],"type":"thought"},"event_type":"step.start"}405406 event: step.delta407 data: {"index":0,"delta":{"signature":"EpoGCpcGAXLI2nx/...","type":"thought_signature"},"event_type":"step.delta"}408409 event: step.stop410 data: {"index":0,"event_type":"step.stop"}411412 event: step.start413 data: {"index":1,"step":{"content":[{"text":"Based on the clues provided, here","type":"text"}],"type":"model_output"},"event_type":"step.start"}414415 event: step.delta416 data: {"index":1,"delta":{"text":" is the answer to your question...","type":"text"},"event_type":"step.delta"}417418 event: step.stop419 data: {"index":1,"event_type":"step.stop"}420421 event: interaction.completed422 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"}423424 event: done425 data: [DONE]426427## Controlling thinking428429Gemini models engage in dynamic thinking by default, automatically adjusting430the amount of reasoning effort based on the complexity of the request. You can control this behavior using the `thinking_level` parameter.431432| Model | Default Thinking | Levels Supported |433|---|---|---|434| gemini-3.8-flash | On (medium) | low, medium, high |435| gemini-3.7-flash | On (medium) | low, medium, high |436| gemini-3.6-flash | On (medium) | minimal, low, medium, high |437| gemini-3.5-flash-lite | On (minimal) | minimal, low, medium, high |438| gemini-3.1-pro-preview | On (high) | low, medium, high |439| gemini-3.1-flash-lite-image | On (minimal) | minimal, high |440| gemini-3-flash-preview | On (high) | minimal, low, medium, high |441| gemini-3-pro-preview | On (high) | low, high |442| gemini-3.5-flash | On (medium) | minimal, low, medium, high |443| gemini-2.5-pro | On | low, medium, high |444| gemini-2.5-flash | On | low, medium, high |445| gemini-2.5-flash-lite | Off | low, medium, high |446447### Python448449 from google import genai450451 client = genai.Client()452453 interaction = client.interactions.create(454 model="gemini-3.8-flash",455 input="Provide a list of 3 famous physicists and their key contributions",456 generation_config={457 "thinking_level": "low"458 }459 )460 print(interaction.output_text)461462### JavaScript463464 import { GoogleGenAI } from "@google/genai";465466 const client = new GoogleGenAI({});467468 const interaction = await client.interactions.create({469 model: "gemini-3.8-flash",470 input: "Provide a list of 3 famous physicists and their key contributions",471 generation_config: {472 thinking_level: "low"473 }474 });475 console.log(interaction.output_text);476477### Java478479 import com.google.genai.Client;480 import com.google.genai.gaos.models.interactions.CreateModelInteraction;481 import com.google.genai.gaos.models.interactions.GenerationConfig;482 import com.google.genai.gaos.models.interactions.Interaction;483 import com.google.genai.gaos.models.interactions.InteractionsInput;484 import com.google.genai.gaos.models.interactions.Model;485 import com.google.genai.gaos.models.interactions.ThinkingLevel;486 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;487488 Client client = new Client();489490 CreateModelInteraction params =491 CreateModelInteraction.builder()492 .model(Model.of("gemini-3.8-flash"))493 .input(494 InteractionsInput.of(495 "Provide a list of 3 famous physicists and their key contributions"))496 .generationConfig(GenerationConfig.builder().thinkingLevel(ThinkingLevel.LOW).build())497 .build();498499 Interaction interaction =500 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();501502 System.out.println(interaction.outputText().orElse(""));503504### REST505506 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \507 -H "x-goog-api-key: $GEMINI_API_KEY" \508 -H 'Content-Type: application/json' \509 -d '{510 "model": "gemini-3.8-flash",511 "input": "Provide a list of 3 famous physicists and their key contributions",512 "generation_config": {513 "thinking_level": "low"514 }515 }'516517### Token limits and `max_output_tokens`518519The [`max_output_tokens`](https://ai.google.dev/api/interactions-api#request-body) generation520parameter sets the maximum number of tokens a response can generate, including521thought tokens.522523When set, this parameter acts as a hard cutoff enforced by the infrastructure524without changing how the model allocates its thinking budget525(`thinking_level`).526527If the model hits this limit while reasoning, it stops generating with status528`"incomplete"` and returns truncated or empty output (while still billing for529any thinking tokens generated). To reduce cost or latency without truncating530responses, lower `thinking_level` (`low` or `medium`) instead of setting a531small `max_output_tokens`.532533## Thought signatures534535Thought signatures are encrypted representations of the model's internal reasoning. They are required to maintain reasoning continuity across multi-turn interactions.536537The Interactions API makes handling thought signatures much simpler than the `generateContent` API.538539### Stateful mode (Recommended)540541By 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.542543### Stateless mode544545If you are managing the conversation state yourself (stateless mode) and passing the full history of inputs and outputs in each request:546547- You **MUST** always resend all `thought` blocks exactly as they were received from the model.548- You should **NOT** remove or modify thought blocks from the history, as they contain the signatures required for the model to continue its reasoning.549- When switching models within a session, you should still resend the previous model's thought blocks. The backend manages compatibility.550551> [!NOTE]552> **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.553554## Pricing555556When thinking is turned on, response pricing is the sum of output557tokens and thinking tokens. You can get the total number of generated thinking558tokens from the `total_thought_tokens` field.559560### Python561562 print("Thoughts tokens:", interaction.usage.total_thought_tokens)563 print("Output tokens:", interaction.usage.total_output_tokens)564565### JavaScript566567 console.log(`Thoughts tokens: ${interaction.usage.total_thought_tokens}`);568 console.log(`Output tokens: ${interaction.usage.total_output_tokens}`);569570### Java571572 import com.google.genai.Client;573 import com.google.genai.gaos.models.interactions.CreateModelInteraction;574 import com.google.genai.gaos.models.interactions.Interaction;575 import com.google.genai.gaos.models.interactions.InteractionsInput;576 import com.google.genai.gaos.models.interactions.Model;577 import com.google.genai.gaos.models.interactions.Usage;578 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;579580 Client client = new Client();581582 CreateModelInteraction params =583 CreateModelInteraction.builder()584 .model(Model.of("gemini-3.8-flash"))585 .input(InteractionsInput.of("Explain the concept of Occam's Razor."))586 .build();587588 Interaction interaction =589 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();590591 if (interaction.usage().isPresent()) {592 Usage usage = interaction.usage().get();593 System.out.println("Thoughts tokens: " + usage.totalThoughtTokens().orElse(0));594 System.out.println("Output tokens: " + usage.totalOutputTokens().orElse(0));595 }596597Thinking models generate full thoughts to improve the quality of the final598response, and then output [summaries](https://ai.google.dev/gemini-api/docs/thinking#summaries) to provide insight into the599thought process. Pricing is based on the full thought tokens the model needs to600generate, despite only the summary being output from the API.601602> [!NOTE]603> **Note:** Because `max_output_tokens` applies to the combined total of thinking tokens and output tokens, setting a low limit can truncate responses. See [Token limits and `max_output_tokens`](https://ai.google.dev/gemini-api/docs/thinking#token-limits) for details.604605You can learn more about tokens in the [Token counting](https://ai.google.dev/gemini-api/docs/tokens) guide.606607## Best practices608609Use thinking models efficiently by following these guidelines.610611- **Review reasoning**: Analyze thought summaries to understand failures and improve prompts.612- **Control thinking budget**: Prompt the model to think less for lengthy outputs to save tokens.613- **Simple tasks**: Use minimal or low thinking for fact retrieval or classification (e.g., "Where was DeepMind founded?").614- **Moderate tasks**: Use default thinking for comparing concepts or creative reasoning (e.g., Compare electric and hybrid cars).615- **Complex tasks**: Use maximum thinking for advanced coding, math, or multi-step planning (e.g., Solve AIME math problems).616617## What's next618619- [Text generation](https://ai.google.dev/gemini-api/docs/text-generation): Basic text responses620- [Function calling](https://ai.google.dev/gemini-api/docs/function-calling): Connect to tools621- [Gemini 3 guide](https://ai.google.dev/gemini-api/docs/gemini-3): Model-specific features