Repository Public
1<br />23> [!NOTE]4> **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](https://ai.google.dev/gemini-api/docs/generate-content/quickstart).56This guide gets you started with the Gemini API using the [Interactions API](https://ai.google.dev/gemini-api/docs/interactions-overview). You'll make your first API call in under a minute and explore text generation, multimodal understanding, image generation, structured output, tools, function calling, agents, and background execution.78The Interactions API is available through the [Python](https://github.com/googleapis/python-genai) and [JavaScript](https://github.com/googleapis/js-genai) SDKs, as well as through REST.910## 1. Get an API key1112To use the Gemini API, you need an [API key](https://ai.google.dev/gemini-api/docs/api-key). Create one for free to get started:1314[Create a Gemini API Key](https://aistudio.google.com/apikey)1516Then set it as an environment variable:1718 export GEMINI_API_KEY="YOUR_API_KEY"1920## 2. Install the SDK and make your first call2122Install the SDK and generate text with a single API call.2324### Python2526Install the SDK:2728 pip install -U google-genai2930Initialize the client and make a request:3132 from google import genai3334 client = genai.Client()3536 interaction = client.interactions.create(37 model="gemini-3.5-flash",38 input="Explain how AI works in a few words"39 )40 print(interaction.output_text)4142### JavaScript4344Install the SDK:4546 npm install @google/genai4748Initialize the client and make a request:4950 import { GoogleGenAI } from "@google/genai";5152 const ai = new GoogleGenAI({});5354 const interaction = await ai.interactions.create({55 model: "gemini-3.5-flash",56 input: "Explain how AI works in a few words",57 });58 console.log(interaction.output_text);5960### REST6162 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \63 -H "x-goog-api-key: $GEMINI_API_KEY" \64 -H 'Content-Type: application/json' \65 -H "Api-Revision: 2026-05-20" \66 -d '{67 "model": "gemini-3.5-flash",68 "input": "Explain how AI works in a few words"69 }'7071**Response:**7273 {74 "id": "v1_ChdpQUFvYXI...",75 "status": "completed",76 "usage": {77 "total_tokens": 197,78 "total_input_tokens": 8,79 "total_output_tokens": 1280 },81 "created": "2026-06-09T12:01:25Z",82 "steps": [83 {84 "type": "thought",85 "signature": "EvEFCu4FAQw..."86 },87 {88 "type": "model_output",89 "content": [90 {91 "type": "text",92 "text": "AI learns patterns from data, then uses those patterns to make predictions or decisions on new data."93 }94 ]95 }96 ],97 "object": "interaction",98 "model": "gemini-3.5-flash",99 }100101When using REST, the API returns the full `Interaction` resource containing metadata, usage statistics, and the step-by-step history of the turn.102103While the SDKs expose the full response, they also provide convenience properties like `interaction.output_text` and `interaction.output_image` to access final outputs directly. Learn more about the response structure in the [Interactions overview](https://ai.google.dev/gemini-api/docs/interactions-overview) or read the [text generation guide](https://ai.google.dev/gemini-api/docs/text-generation) for details on system instructions and generation config.104105## 3. Stream the response106107For more fluid interactions, stream the response as it's generated. Each `step.delta` event delivers a chunk of text you can display immediately.108109### Python110111 from google import genai112113 client = genai.Client()114115 stream = client.interactions.create(116 model="gemini-3.5-flash",117 input="Explain how AI works",118 stream=True119 )120 for event in stream:121 print(event)122123### JavaScript124125 import { GoogleGenAI } from "@google/genai";126127 const ai = new GoogleGenAI({});128129 const stream = await ai.interactions.create({130 model: "gemini-3.5-flash",131 input: "Explain how AI works",132 stream: true,133 });134135 for await (const event of stream) {136 console.log(event);137 }138139### REST140141 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse" \142 -H "x-goog-api-key: $GEMINI_API_KEY" \143 -H 'Content-Type: application/json' \144 -H "Api-Revision: 2026-05-20" \145 --no-buffer \146 -d '{147 "model": "gemini-3.5-flash",148 "input": "Explain how AI works",149 "stream": true150 }'151152When streaming, the server responds with a stream of server-sent events (SSE). Each event includes a type and JSON data.153154**Response:**155156 event: interaction.created157 data: {"interaction":{"id":"v1_Chd...","status":"in_progress","model":"gemini-3.5-flash"},"event_type":"interaction.created"}158159 event: step.start160 data: {"index":0,"step":{"type":"thought"},"event_type":"step.start"}161162 event: step.delta163 data: {"index":0,"delta":{"signature":"EvEFCu4F...","type":"thought_signature"},"event_type":"step.delta"}164165 event: step.stop166 data: {"index":0,"event_type":"step.stop"}167168 event: step.start169 data: {"index":1,"step":{"type":"model_output"},"event_type":"step.start"}170171 event: step.delta172 data: {"index":1,"delta":{"text":"AI ","type":"text"},"event_type":"step.delta"}173174 event: step.delta175 data: {"index":1,"delta":{"text":"works ","type":"text"},"event_type":"step.delta"}176177 event: step.stop178 data: {"index":1,"event_type":"step.stop"}179180 event: interaction.completed181 data: {"interaction":{"id":"v1_Chd...","status":"completed","usage":{"total_tokens":197}},"event_type":"interaction.completed"}182183For a detailed look at handling streaming events and delta types, see the [streaming interactions guide](https://ai.google.dev/gemini-api/docs/streaming).184185## 4. Multi-turn conversations186187The Interactions API supports multi-turn conversations with two approaches:188189- **Stateful (recommended)** : Continue a conversation on the server using `previous_interaction_id`. Ideal for most chat and agentic workflows where you want the server to manage history and optimize caching.190- **Stateless**: Manage the conversation history on the client by passing all previous turns (including intermediate model thought and tool steps) in each request.191192### Stateful (recommended)193194Chain interactions by passing `previous_interaction_id`. The server manages the full conversation history for you.195196### Python197198 from google import genai199200 client = genai.Client()201202 # Server-side state (recommended)203 interaction1 = client.interactions.create(204 model="gemini-3.5-flash",205 input="I have 2 dogs in my house.",206 )207 print("Response 1:", interaction1.output_text)208209 interaction2 = client.interactions.create(210 model="gemini-3.5-flash",211 input="How many paws are in my house?",212 previous_interaction_id=interaction1.id,213 )214 print("Response 2:", interaction2.output_text)215216### JavaScript217218 import { GoogleGenAI } from "@google/genai";219220 const ai = new GoogleGenAI({});221222 // Server-side state (recommended)223 const interaction1 = await ai.interactions.create({224 model: "gemini-3.5-flash",225 input: "I have 2 dogs in my house.",226 });227 console.log("Response 1:", interaction1.output_text);228229 const interaction2 = await ai.interactions.create({230 model: "gemini-3.5-flash",231 input: "How many paws are in my house?",232 previous_interaction_id: interaction1.id,233 });234 console.log("Response 2:", interaction2.output_text);235236### REST237238 RESPONSE1=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \239 -H "x-goog-api-key: $GEMINI_API_KEY" \240 -H 'Content-Type: application/json' \241 -H "Api-Revision: 2026-05-20" \242 -d '{243 "model": "gemini-3.5-flash",244 "input": "I have 2 dogs in my house."245 }')246247 INTERACTION_ID=$(echo "$RESPONSE1" | jq -r '.id')248 echo "Interaction 1 ID: $INTERACTION_ID"249250 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \251 -H "x-goog-api-key: $GEMINI_API_KEY" \252 -H 'Content-Type: application/json' \253 -H "Api-Revision: 2026-05-20" \254 -d '{255 "model": "gemini-3.5-flash",256 "input": "How many paws are in my house?",257 "previous_interaction_id": "'$INTERACTION_ID'"258 }'259260### Stateless261262Set `store=false` and manage conversation history on the client side. You must preserve and resend all model-generated steps (including `thought` and `function_call` steps) exactly as received.263264### Python265266 from google import genai267268 client = genai.Client()269270 history = [271 {272 "type": "user_input",273 "content": [{"type": "text", "text": "I have 2 dogs in my house."}]274 }275 ]276277 interaction1 = client.interactions.create(278 model="gemini-3.5-flash",279 store=False,280 input=history281 )282 print("Response 1:", interaction1.steps[-1].content[0].text)283284 for step in interaction1.steps:285 history.append(step.model_dump())286287 history.append({288 "type": "user_input",289 "content": [{"type": "text", "text": "How many paws are in my house?"}]290 })291292 interaction2 = client.interactions.create(293 model="gemini-3.5-flash",294 store=False,295 input=history296 )297 print("Response 2:", interaction2.steps[-1].content[0].text)298299### JavaScript300301 import { GoogleGenAI } from "@google/genai";302303 const ai = new GoogleGenAI({});304305 const history = [306 {307 type: "user_input",308 content: [{ type: "text", text: "I have 2 dogs in my house." }]309 }310 ];311312 const interaction1 = await ai.interactions.create({313 model: "gemini-3.5-flash",314 store: false,315 input: history316 });317 console.log("Response 1:", interaction1.steps.at(-1).content[0].text);318319 history.push(...interaction1.steps);320321 history.push({322 type: "user_input",323 content: [{ type: "text", text: "How many paws are in my house?" }]324 });325326 const interaction2 = await ai.interactions.create({327 model: "gemini-3.5-flash",328 store: false,329 input: history330 });331 console.log("Response 2:", interaction2.steps.at(-1).content[0].text);332333### REST334335 # Turn 1: Send with store: false336 RESPONSE1=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \337 -H "x-goog-api-key: $GEMINI_API_KEY" \338 -H 'Content-Type: application/json' \339 -H "Api-Revision: 2026-05-20" \340 -d '{341 "model": "gemini-3.5-flash",342 "store": false,343 "input": [344 {345 "type": "user_input",346 "content": "I have 2 dogs in my house."347 }348 ]349 }')350351 MODEL_STEPS=$(echo "$RESPONSE1" | jq '.steps')352353 # Turn 2: Build full history354 HISTORY=$(jq -n \355 --argjson first_input '[{"type": "user_input", "content": "I have 2 dogs in my house."}]' \356 --argjson model_steps "$MODEL_STEPS" \357 --argjson second_input '[{"type": "user_input", "content": "How many paws are in my house?"}]' \358 '$first_input + $model_steps + $second_input')359360 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \361 -H "x-goog-api-key: $GEMINI_API_KEY" \362 -H 'Content-Type: application/json' \363 -H "Api-Revision: 2026-05-20" \364 -d "{365 \"model\": \"gemini-3.5-flash\",366 \"store\": false,367 \"input\": $HISTORY368 }"369370**Response:**371372 {373 "id": "v2_Chd...",374 "status": "completed",375 "usage": {376 "total_tokens": 240,377 "total_input_tokens": 60,378 "total_output_tokens": 20379 },380 "steps": [381 {382 "type": "model_output",383 "content": [384 {385 "type": "text",386 "text": "There are 8 paws in your house. 2 dogs \u00d7 4 paws = 8 paws."387 }388 ]389 }390 ],391 "object": "interaction",392 "model": "gemini-3.5-flash"393 }394395The second interaction returns a complete response object that includes only the new steps, but is grounded in the previous turn's context. Learn more about maintaining state in the [multi-turn conversations guide](https://ai.google.dev/gemini-api/docs/text-generation#multi-turn-conversations), or explore [stateless mode](https://ai.google.dev/gemini-api/docs/text-generation#stateless-conversations) for client-side history management.396397## 5. Multimodal understanding398399Gemini models understand images, audio, video, and documents natively. Pass media alongside text in a single request.400401### Python402403 import base64404 from google import genai405406 client = genai.Client()407408 # Load a local image409 with open("sample.jpg", "rb") as f:410 image_bytes = f.read()411 image_b64 = base64.b64encode(image_bytes).decode("utf-8")412413 interaction = client.interactions.create(414 model="gemini-3.5-flash",415 input=[416 {"type": "text", "text": "Compare this local image and this remote audio file."},417 {418 "type": "image",419 "data": image_b64,420 "mime_type": "image/jpeg"421 },422 {423 "type": "audio",424 "uri": "https://storage.googleapis.com/generativeai-downloads/data/sample.mp3",425 "mime_type": "audio/mp3"426 }427 ]428 )429 print(interaction.output_text)430431### JavaScript432433 import fs from "fs";434 import { GoogleGenAI } from "@google/genai";435436 const ai = new GoogleGenAI({});437438 // Load a local image439 const imageBytes = fs.readFileSync("sample.jpg");440 const imageB64 = imageBytes.toString("base64");441442 const interaction = await ai.interactions.create({443 model: "gemini-3.5-flash",444 input: [445 { type: "text", text: "Compare this local image and this remote audio file." },446 {447 type: "image",448 data: imageB64,449 mime_type: "image/jpeg"450 },451 {452 type: "audio",453 uri: "https://storage.googleapis.com/generativeai-downloads/data/sample.mp3",454 mime_type: "audio/mp3"455 }456 ],457 });458 console.log(interaction.output_text);459460### REST461462 # Base64-encode local image463 BASE64_IMAGE=$(base64 -w 0 sample.jpg)464465 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" -H "x-goog-api-key: $GEMINI_API_KEY" -H 'Content-Type: application/json' -H "Api-Revision: 2026-05-20" -d '{466 "model": "gemini-3.5-flash",467 "input": [468 {469 "type": "text",470 "text": "Compare this local image and this remote audio file."471 },472 {473 "type": "image",474 "data": "'$BASE64_IMAGE'",475 "mime_type": "image/jpeg"476 },477 {478 "type": "audio",479 "uri": "https://storage.googleapis.com/generativeai-downloads/data/sample.mp3",480 "mime_type": "audio/mp3"481 }482 ]483 }'484485**Response:**486487 {488 "id": "v1_Chd...",489 "status": "completed",490 "usage": {491 "total_tokens": 300492 },493 "steps": [494 {495 "type": "model_output",496 "content": [497 {498 "type": "text",499 "text": "The local image displays a pipe organ while the remote audio file is a sample MP3 clip..."500 }501 ]502 }503 ],504 "object": "interaction",505 "model": "gemini-3.5-flash",506 }507508Explore how to pass images, video, and audio files in the [image understanding guide](https://ai.google.dev/gemini-api/docs/image-understanding).509[Audio understanding510Transcribe, summarize, or answer questions about audio files.](https://ai.google.dev/gemini-api/docs/audio) [Video understanding511Analyze video content, locate events, and describe actions.](https://ai.google.dev/gemini-api/docs/video-understanding) [Document processing512Extract information from PDFs and other document formats.](https://ai.google.dev/gemini-api/docs/document-processing)513514## 6. Multimodal generation515516Gemini can generate images natively using the [Nano Banana](https://ai.google.dev/gemini-api/docs/image-generation) image models.517518### Python519520 import base64521 from google import genai522523 client = genai.Client()524525 interaction = client.interactions.create(526 model="gemini-3.1-flash-image",527 input="Generate an image of a futuristic city skyline at sunset",528 )529530 with open("generated_image.png", "wb") as f:531 f.write(base64.b64decode(interaction.output_image.data))532533### JavaScript534535 import { GoogleGenAI } from "@google/genai";536 import * as fs from "node:fs";537538 const ai = new GoogleGenAI({});539540 const interaction = await ai.interactions.create({541 model: "gemini-3.1-flash-image",542 input: "Generate an image of a futuristic city skyline at sunset",543 });544545 const generatedImage = interaction.output_image;546 if (generatedImage) {547 const buffer = Buffer.from(generatedImage.data, "base64");548 fs.writeFileSync("generated_image.png", buffer);549 }550551### REST552553 curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \554 -H "x-goog-api-key: $GEMINI_API_KEY" \555 -H 'Content-Type: application/json' \556 -H "Api-Revision: 2026-05-20" \557 -d '{558 "model": "gemini-3.1-flash-image",559 "input": [560 {"type": "text", "text": "Generate an image of a futuristic city skyline at sunset"}561 ]562 }'563564**Response:**565566 {567 "id": "v1_Chd...",568 "status": "completed",569 "steps": [570 {571 "type": "model_output",572 "content": [573 {574 "type": "image",575 "data": "BASE64_ENCODED_IMAGE",576 "mime_type": "image/png"577 }578 ]579 }580 ],581 "object": "interaction",582 "model": "gemini-3.1-flash-image",583 }584585When the model generates an image, it returns the base64-encoded image data in a step within the `steps` array, as well as via the `output_image` convenience property. Check out the [image generation guide](https://ai.google.dev/gemini-api/docs/image-generation) to learn about aspect ratios, image editing, and references.586[Speech generation587Generate expressive, multi-speaker speech with Gemini 3.1 Flash TTS.](https://ai.google.dev/gemini-api/docs/speech-generation) [Music generation588Create clips and full-length songs with Lyria 3.](https://ai.google.dev/gemini-api/docs/music-generation)589590## 7. Use structured output591592Configure the model to return JSON that matches a schema you define. Structured output works with [Pydantic](https://docs.pydantic.dev/latest/) (Python) and [Zod](https://zod.dev/) (JavaScript).593594### Python595596 from google import genai597 from pydantic import BaseModel, Field598 from typing import List, Optional599600 class Recipe(BaseModel):601 recipe_name: str = Field(description="Name of the recipe.")602 ingredients: List[str] = Field(description="List of ingredients.")603 prep_time_minutes: Optional[int] = Field(description="Prep time in minutes.")604605 client = genai.Client()606607 interaction = client.interactions.create(608 model="gemini-3.5-flash",609 input="Give me a recipe for banana bread",610 response_format={611 "type": "text",612 "mime_type": "application/json",613 "schema": Recipe.model_json_schema()614 },615 )616617 recipe = Recipe.model_validate_json(interaction.output_text)618 print(recipe)619620### JavaScript621622 import { GoogleGenAI } from "@google/genai";623 import * as z from "zod";624625 const ai = new GoogleGenAI({});626627 const recipeJsonSchema = {628 type: "object",629 properties: {630 recipe_name: { type: "string", description: "Name of the recipe." },631 ingredients: {632 type: "array",633 items: { type: "string" },634 description: "List of ingredients."635 },636 prep_time_minutes: {637 type: "integer",638 description: "Prep time in minutes."639 }640 },641 required: ["recipe_name", "ingredients"]642 };643644 const recipeSchema = z.fromJSONSchema(recipeJsonSchema);645646 const interaction = await ai.interactions.create({647 model: "gemini-3.5-flash",648 input: "Give me a recipe for banana bread",649 response_format: {650 type: "text",651 mime_type: "application/json",652 schema: recipeJsonSchema653 },654 });655656 const recipe = recipeSchema.parse(JSON.parse(interaction.output_text));657 console.log(recipe);658659### REST660661 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \662 -H "x-goog-api-key: $GEMINI_API_KEY" \663 -H 'Content-Type: application/json' \664 -H "Api-Revision: 2026-05-20" \665 -d '{666 "model": "gemini-3.5-flash",667 "input": "Give me a recipe for banana bread",668 "response_format": {669 "type": "text",670 "mime_type": "application/json",671 "schema": {672 "type": "object",673 "properties": {674 "recipe_name": { "type": "string", "description": "Name of the recipe." },675 "ingredients": {676 "type": "array",677 "items": { "type": "string" },678 "description": "List of ingredients."679 },680 "prep_time_minutes": {681 "type": "integer",682 "description": "Prep time in minutes."683 }684 },685 "required": ["recipe_name", "ingredients"]686 }687 }688 }'689690**Response:**691692 {693 "id": "v1_Chd...",694 "status": "completed",695 "steps": [696 {697 "type": "model_output",698 "content": [699 {700 "type": "text",701 "text": "{\n \"recipe_name\": \"Classic Banana Bread\",\n \"ingredients\": [\n \"3 ripe bananas, mashed\",\n \"1/3 cup melted butter\",\n \"3/4 cup sugar\",\n \"1 egg, beaten\",\n \"1 teaspoon vanilla extract\",\n \"1 teaspoon baking soda\",\n \"Pinch of salt\",\n \"1.5 cups all-purpose flour\"\n ],\n \"prep_time_minutes\": 15\n}"702 }703 ]704 }705 ],706 "object": "interaction",707 "model": "gemini-3.5-flash",708 }709710The output text block contains a valid JSON string conforming exactly to the requested schema. To learn how to define more complex structures and recursive schemas, see the [structured output guide](https://ai.google.dev/gemini-api/docs/structured-output).711712## 8. Use tools713714Ground the model's response in real-time information with Google Search. The API automatically searches, processes results, and returns citations.715716### Python717718 from google import genai719720 client = genai.Client()721722 interaction = client.interactions.create(723 model="gemini-3.5-flash",724 input="Who won the euro 2024?",725 tools=[{"type": "google_search"}]726 )727728 print(interaction.output_text)729730 # Print citations731 for step in interaction.steps:732 if step.type == "model_output":733 for content_block in step.content:734 if content_block.type == "text" and content_block.annotations:735 print("\nCitations:")736 for annotation in content_block.annotations:737 if annotation.type == "url_citation":738 print(f" [{annotation.title}]({annotation.url})")739740### JavaScript741742 import { GoogleGenAI } from "@google/genai";743744 const ai = new GoogleGenAI({});745746 const interaction = await ai.interactions.create({747 model: "gemini-3.5-flash",748 input: "Who won the euro 2024?",749 tools: [{ type: "google_search" }]750 });751752 console.log(interaction.output_text);753754 // Print citations755 for (const step of interaction.steps) {756 if (step.type === "model_output") {757 for (const contentBlock of step.content) {758 if (contentBlock.type === "text" && contentBlock.annotations) {759 console.log("\nCitations:");760 for (const annotation of contentBlock.annotations) {761 if (annotation.type === "url_citation") {762 console.log(` [${annotation.title}](${annotation.url})`);763 }764 }765 }766 }767 }768 }769770### REST771772 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \773 -H "x-goog-api-key: $GEMINI_API_KEY" \774 -H 'Content-Type: application/json' \775 -H "Api-Revision: 2026-05-20" \776 -d '{777 "model": "gemini-3.5-flash",778 "input": "Who won the euro 2024?",779 "tools": [{"type": "google_search"}]780 }'781782**Response:**783784 {785 "id": "v1_Chd...",786 "status": "completed",787 "steps": [788 {789 "type": "thought",790 "signature": "EvEFCu4F..."791 },792 {793 "type": "google_search_call",794 "arguments": {795 "queries": ["UEFA Euro 2024 winner"]796 }797 },798 {799 "type": "google_search_result",800 "call_id": "search_001",801 "result": [802 {803 "search_suggestions": "<!-- HTML and CSS search widget -->"804 }805 ]806 },807 {808 "type": "model_output",809 "content": [810 {811 "type": "text",812 "text": "Spain won Euro 2024, defeating England 2-1 in the final.",813 "annotations": [814 {815 "type": "url_citation",816 "url": "https://www.uefa.com/euro2024",817 "title": "uefa.com",818 "start_index": 0,819 "end_index": 56820 }821 ]822 }823 ]824 }825 ],826 "object": "interaction",827 "model": "gemini-3.5-flash",828 }829830The search steps are detailed within the interaction history, and the final output includes inline citations pointing to web sources.831832You can learn how to extract search citations in the [Google Search grounding guide](https://ai.google.dev/gemini-api/docs/google-search), or see how to combine multiple tools in the [tool combination guide](https://ai.google.dev/gemini-api/docs/tool-combination).833[Code execution834Run Python code in a secure sandboxed Borg environment.](https://ai.google.dev/gemini-api/docs/code-execution) [URL context835Pass public web URLs directly to ground responses in webpage content.](https://ai.google.dev/gemini-api/docs/url-context) [File search836Index and search across uploaded documents and media files.](https://ai.google.dev/gemini-api/docs/file-search) [Google Maps837Ground responses in real-world geospatial and location data.](https://ai.google.dev/gemini-api/docs/maps-grounding) [Computer use838Browser automation and screen interaction.](https://ai.google.dev/gemini-api/docs/computer-use)839840## 9. Call your own functions841842Function calling lets you connect the model to your code. You declare a function's name and parameters, the model decides when to call it and returns structured arguments, and you execute it locally and send the result back.843844### Stateful (recommended)845846### Python847848 import json849 from google import genai850851 client = genai.Client()852853 weather_tool = {854 "type": "function",855 "name": "get_current_temperature",856 "description": "Gets the current temperature for a given location.",857 "parameters": {858 "type": "object",859 "properties": {860 "location": {861 "type": "string",862 "description": "The city name, e.g. San Francisco",863 },864 },865 "required": ["location"],866 },867 }868869 available_functions = {870 "get_current_temperature": lambda location: {871 "location": location, "temperature": "22", "unit": "celsius"872 },873 }874875 user_input = "What is the temperature in London?"876 previous_id = None877878 while True:879 interaction = client.interactions.create(880 model="gemini-3.5-flash",881 input=user_input,882 tools=[weather_tool],883 previous_interaction_id=previous_id,884 )885886 function_results = []887 for step in interaction.steps:888 if step.type == "function_call":889 result = available_functions[step.name](**step.arguments)890 print(f"Called {step.name}({step.arguments}) → {result}")891 function_results.append({892 "type": "function_result",893 "name": step.name,894 "call_id": step.id,895 "result": [{"type": "text", "text": json.dumps(result)}],896 })897898 if not function_results:899 break900901 user_input = function_results902 previous_id = interaction.id903904 print(interaction.output_text)905906### JavaScript907908 import { GoogleGenAI } from "@google/genai";909910 const ai = new GoogleGenAI({});911912 const weatherTool = {913 type: "function",914 name: "get_current_temperature",915 description: "Gets the current temperature for a given location.",916 parameters: {917 type: "object",918 properties: {919 location: {920 type: "string",921 description: "The city name, e.g. San Francisco",922 },923 },924 required: ["location"],925 },926 };927928 const availableFunctions = {929 get_current_temperature: ({ location }) => ({930 location, temperature: "22", unit: "celsius"931 }),932 };933934 let input = "What is the temperature in London?";935 let previousId = null;936 let interaction;937938 while (true) {939 interaction = await ai.interactions.create({940 model: "gemini-3.5-flash",941 input,942 tools: [weatherTool],943 previous_interaction_id: previousId,944 });945946 const functionResults = [];947 for (const step of interaction.steps) {948 if (step.type === "function_call") {949 const result = availableFunctions[step.name](step.arguments);950 console.log(`Called ${step.name}(${JSON.stringify(step.arguments)}) →`, result);951 functionResults.push({952 type: "function_result",953 name: step.name,954 call_id: step.id,955 result: [{ type: "text", text: JSON.stringify(result) }],956 });957 }958 }959960 if (functionResults.length === 0) break;961962 input = functionResults;963 previousId = interaction.id;964 }965966 console.log(interaction.output_text);967968### REST969970 # Turn 1: Send prompt with function declaration971 RESPONSE1=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \972 -H "x-goog-api-key: $GEMINI_API_KEY" \973 -H 'Content-Type: application/json' \974 -H "Api-Revision: 2026-05-20" \975 -d '{976 "model": "gemini-3.5-flash",977 "input": "What is the temperature in London?",978 "tools": [{979 "type": "function",980 "name": "get_current_temperature",981 "description": "Gets the current temperature for a given location.",982 "parameters": {983 "type": "object",984 "properties": {985 "location": {"type": "string", "description": "The city name"}986 },987 "required": ["location"]988 }989 }]990 }')991992 INTERACTION_ID=$(echo "$RESPONSE1" | jq -r '.id')993 FC_NAME=$(echo "$RESPONSE1" | jq -r '.steps[] | select(.type=="function_call") | .name')994 FC_ID=$(echo "$RESPONSE1" | jq -r '.steps[] | select(.type=="function_call") | .id')995 echo "Function: $FC_NAME, Call ID: $FC_ID"996997 # Turn 2: Send function result back998 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \999 -H "x-goog-api-key: $GEMINI_API_KEY" \1000 -H 'Content-Type: application/json' \1001 -H "Api-Revision: 2026-05-20" \1002 -d '{1003 "model": "gemini-3.5-flash",1004 "previous_interaction_id": "'$INTERACTION_ID'",1005 "input": [{1006 "type": "function_result",1007 "name": "'$FC_NAME'",1008 "call_id": "'$FC_ID'",1009 "result": [{"type": "text", "text": "{\"location\": \"London\", \"temperature\": \"22\", \"unit\": \"celsius\"}"}]1010 }],1011 "tools": [{1012 "type": "function",1013 "name": "get_current_temperature",1014 "description": "Gets the current temperature for a given location.",1015 "parameters": {1016 "type": "object",1017 "properties": {1018 "location": {"type": "string", "description": "The city name"}1019 },1020 "required": ["location"]1021 }1022 }]1023 }'10241025### Stateless10261027You can also use function calling in stateless mode by managing the conversation history on the client side and setting `store=false`. In stateless mode, you must pass the full history of the conversation in the `input` field of each subsequent request. This history must include:102810291. The initial `user_input` step.10302. All model-generated steps returned in Turn 1 (including `thought` and `function_call` steps) exactly as received.10313. The `function_result` step containing the output of your executed function.10321033### Python10341035 import json1036 from google import genai10371038 client = genai.Client()10391040 weather_tool = {1041 "type": "function",1042 "name": "get_current_temperature",1043 "description": "Gets the current temperature for a given location.",1044 "parameters": {1045 "type": "object",1046 "properties": {1047 "location": {1048 "type": "string",1049 "description": "The city name, e.g. San Francisco",1050 },1051 },1052 "required": ["location"],1053 },1054 }10551056 available_functions = {1057 "get_current_temperature": lambda location: {1058 "location": location, "temperature": "22", "unit": "celsius"1059 },1060 }10611062 history = [1063 {1064 "type": "user_input",1065 "content": [{"type": "text", "text": "What is the temperature in London?"}]1066 }1067 ]10681069 while True:1070 interaction = client.interactions.create(1071 model="gemini-3.5-flash",1072 store=False,1073 input=history,1074 tools=[weather_tool],1075 )10761077 function_results = []1078 for step in interaction.steps:1079 history.append(step.model_dump())1080 if step.type == "function_call":1081 result = available_functions[step.name](**step.arguments)1082 print(f"Called {step.name}({step.arguments}) → {result}")1083 fn_result = {1084 "type": "function_result",1085 "name": step.name,1086 "call_id": step.id,1087 "result": [{"type": "text", "text": json.dumps(result)}],1088 }1089 function_results.append(fn_result)1090 history.append(fn_result)10911092 if not function_results:1093 break10941095 print(interaction.output_text)10961097### JavaScript10981099 import { GoogleGenAI } from "@google/genai";11001101 const ai = new GoogleGenAI({});11021103 const weatherTool = {1104 type: "function",1105 name: "get_current_temperature",1106 description: "Gets the current temperature for a given location.",1107 parameters: {1108 type: "object",1109 properties: {1110 location: {1111 type: "string",1112 description: "The city name, e.g. San Francisco",1113 },1114 },1115 required: ["location"],1116 },1117 };11181119 const availableFunctions = {1120 get_current_temperature: ({ location }) => ({1121 location, temperature: "22", unit: "celsius"1122 }),1123 };11241125 const history = [1126 {1127 type: "user_input",1128 content: [{ type: "text", text: "What is the temperature in London?" }]1129 }1130 ];11311132 let interaction;11331134 while (true) {1135 interaction = await ai.interactions.create({1136 model: "gemini-3.5-flash",1137 store: false,1138 input: history,1139 tools: [weatherTool],1140 });11411142 const functionResults = [];1143 for (const step of interaction.steps) {1144 history.push(step);1145 if (step.type === "function_call") {1146 const result = availableFunctions[step.name](step.arguments);1147 console.log(`Called ${step.name}(${JSON.stringify(step.arguments)}) →`, result);1148 const fnResult = {1149 type: "function_result",1150 name: step.name,1151 call_id: step.id,1152 result: [{ type: "text", text: JSON.stringify(result) }],1153 };1154 functionResults.push(fnResult);1155 history.push(fnResult);1156 }1157 }11581159 if (functionResults.length === 0) break;1160 }11611162 console.log(interaction.output_text);11631164### REST11651166 # Turn 1: Send request with tools and store: false1167 RESPONSE1=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \1168 -H "x-goog-api-key: $GEMINI_API_KEY" \1169 -H 'Content-Type: application/json' \1170 -H "Api-Revision: 2026-05-20" \1171 -d '{1172 "model": "gemini-3.5-flash",1173 "store": false,1174 "input": [1175 {1176 "type": "user_input",1177 "content": "What is the temperature in London?"1178 }1179 ],1180 "tools": [{1181 "type": "function",1182 "name": "get_current_temperature",1183 "description": "Gets the current temperature for a given location.",1184 "parameters": {1185 "type": "object",1186 "properties": {1187 "location": {"type": "string", "description": "The city name"}1188 },1189 "required": ["location"]1190 }1191 }]1192 }')11931194 # Extract model steps (thought, function_call)1195 MODEL_STEPS=$(echo "$RESPONSE1" | jq '.steps')1196 FC_NAME=$(echo "$RESPONSE1" | jq -r '.steps[] | select(.type=="function_call") | .name')1197 FC_ID=$(echo "$RESPONSE1" | jq -r '.steps[] | select(.type=="function_call") | .id')1198 echo "Function: $FC_NAME, Call ID: $FC_ID"11991200 # Assume local execution returns:1201 RESULT="{\"location\": \"London\", \"temperature\": \"22\", \"unit\": \"celsius\"}"12021203 # Reconstruct history for Turn 21204 HISTORY=$(jq -n \1205 --argjson first_input '[{"type": "user_input", "content": "What is the temperature in London?"}]' \1206 --argjson model_steps "$MODEL_STEPS" \1207 --arg fc_name "$FC_NAME" \1208 --arg fc_id "$FC_ID" \1209 --arg result "$RESULT" \1210 '$first_input + $model_steps + [{"type": "function_result", "name": $fc_name, "call_id": $fc_id, "result": [{"type": "text", "text": $result}]}]')12111212 # Turn 2: Send the full history1213 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \1214 -H "x-goog-api-key: $GEMINI_API_KEY" \1215 -H 'Content-Type: application/json' \1216 -H "Api-Revision: 2026-05-20" \1217 -d "{1218 \"model\": \"gemini-3.5-flash\",1219 \"store\": false,1220 \"input\": $HISTORY,1221 \"tools\": [{1222 \"type\": \"function\",1223 \"name\": \"get_current_temperature\",1224 \"description\": \"Gets the current temperature for a given location.\",1225 \"parameters\": {1226 \"type\": \"object\",1227 \"properties\": {1228 \"location\": {\"type\": \"string\", \"description\": \"The city name\"}1229 },1230 \"required\": [\"location\"]1231 }1232 }]1233 }"12341235**Response:**12361237During Turn 1, the model returns a response with status `requires_action` and the `function_call` step:12381239 {1240 "id": "v1_Chd...",1241 "status": "requires_action",1242 "steps": [1243 {1244 "type": "function_call",1245 "id": "call_abc123",1246 "name": "get_current_temperature",1247 "arguments": {1248 "location": "London"1249 }1250 }1251 ],1252 "object": "interaction",1253 "model": "gemini-3.5-flash"1254 }12551256After you run the function locally and submit the result (Turn 2), the final completed interaction returns:12571258 {1259 "id": "v1_Chd...",1260 "status": "completed",1261 "steps": [1262 {1263 "type": "function_call",1264 "id": "call_abc123",1265 "name": "get_current_temperature",1266 "arguments": {1267 "location": "London"1268 }1269 },1270 {1271 "type": "model_output",1272 "content": [1273 {1274 "type": "text",1275 "text": "The temperature in London is currently 22°C."1276 }1277 ]1278 }1279 ],1280 "object": "interaction",1281 "model": "gemini-3.5-flash",1282 }12831284For advanced features like parallel function calling or function choice modes, see the [function calling guide](https://ai.google.dev/gemini-api/docs/function-calling).12851286## 10. Run a managed agent12871288Managed agents run in a remote sandbox with access to tools like code execution and file management. Pass an `agent` instead of a `model` and set `environment="remote"`.12891290### Python12911292 from google import genai12931294 client = genai.Client()12951296 interaction = client.interactions.create(1297 agent="antigravity-preview-05-2026",1298 input="Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents.",1299 environment="remote",1300 )1301 print(f"Environment: {interaction.environment_id}")1302 print(interaction.output_text)13031304### JavaScript13051306 import { GoogleGenAI } from "@google/genai";13071308 const ai = new GoogleGenAI({});13091310 const interaction = await ai.interactions.create({1311 agent: "antigravity-preview-05-2026",1312 input: "Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents.",1313 environment: "remote",1314 });1315 console.log(`Environment: ${interaction.environment_id}`);1316 console.log(interaction.output_text);13171318### REST13191320 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \1321 -H "x-goog-api-key: $GEMINI_API_KEY" \1322 -H 'Content-Type: application/json' \1323 -H "Api-Revision: 2026-05-20" \1324 -d '{1325 "agent": "antigravity-preview-05-2026",1326 "input": "Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents.",1327 "environment": "remote"1328 }'13291330You can also define and save [custom agents](https://ai.google.dev/gemini-api/docs/custom-agents) with your own instructions, skills, and data sources.1331[Quickstart1332Make your first agent call, stream responses, and build a custom agent.](https://ai.google.dev/gemini-api/docs/managed-agents-quickstart) [Antigravity Agent1333Capabilities, tools, multimodal input, and pricing for the default agent.](https://ai.google.dev/gemini-api/docs/antigravity-agent) [Agents in AI Studio1334Visual playground for prototyping agents without writing code.](https://ai.google.dev/gemini-api/docs/aistudio-agents)13351336## 11. Run tasks in the background13371338Set `background=True` to run long tasks asynchronously. Poll for results with `interactions.get()`.13391340### Python13411342 import time1343 from google import genai13441345 client = genai.Client()13461347 interaction = client.interactions.create(1348 model="gemini-3.5-flash",1349 input="Write a detailed analysis of the impact of artificial intelligence on modern healthcare.",1350 background=True,1351 )1352 print(f"Started background task: {interaction.id}")1353 print(f"Status: {interaction.status}")13541355 # Poll for completion1356 while True:1357 result = client.interactions.get(interaction.id)1358 print(f"Status: {result.status}")1359 if result.status == "completed":1360 print(f"\nResult:\n{result.output_text}")1361 break1362 elif result.status == "failed":1363 print(f"Failed: {result.error}")1364 break1365 time.sleep(5)13661367### JavaScript13681369 import { GoogleGenAI } from "@google/genai";13701371 const ai = new GoogleGenAI({});13721373 const interaction = await ai.interactions.create({1374 model: "gemini-3.5-flash",1375 input: "Write a detailed analysis of the impact of artificial intelligence on modern healthcare.",1376 background: true,1377 });1378 console.log(`Started background task: ${interaction.id}`);1379 console.log(`Status: ${interaction.status}`);13801381 // Poll for completion1382 while (true) {1383 const result = await ai.interactions.get(interaction.id);1384 console.log(`Status: ${result.status}`);1385 if (result.status === "completed") {1386 console.log(`\nResult:\n${result.output_text}`);1387 break;1388 } else if (result.status === "failed") {1389 console.log(`Failed: ${result.error}`);1390 break;1391 }1392 await new Promise(r => setTimeout(r, 5000));1393 }13941395### REST13961397 # Start a background task1398 RESPONSE=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \1399 -H "x-goog-api-key: $GEMINI_API_KEY" \1400 -H 'Content-Type: application/json' \1401 -H "Api-Revision: 2026-05-20" \1402 -d '{1403 "model": "gemini-3.5-flash",1404 "input": "Write a detailed analysis of the impact of artificial intelligence on modern healthcare.",1405 "background": true1406 }')14071408 INTERACTION_ID=$(echo "$RESPONSE" | jq -r '.id')1409 echo "Started background task: $INTERACTION_ID"14101411 # Poll for completion1412 while true; do1413 RESULT=$(curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/$INTERACTION_ID" \1414 -H "x-goog-api-key: $GEMINI_API_KEY" \1415 -H "Api-Revision: 2026-05-20")1416 STATUS=$(echo "$RESULT" | jq -r '.status')1417 echo "Status: $STATUS"1418 if [ "$STATUS" = "completed" ]; then1419 echo "$RESULT" | jq -r '.steps[] | select(.type=="model_output") | .content[] | select(.type=="text") | .text'1420 break1421 elif [ "$STATUS" = "failed" ]; then1422 echo "Failed"1423 break1424 fi1425 sleep 51426 done14271428**Response:**14291430The initial response returns immediately with status `in_progress`:14311432 {1433 "id": "v1_abc123",1434 "status": "in_progress",1435 "object": "interaction",1436 "model": "gemini-3.5-flash"1437 }14381439Once the background task is fully executed, checking the interaction state returns:14401441 {1442 "id": "v1_abc123",1443 "status": "completed",1444 "steps": [1445 {1446 "type": "model_output",1447 "content": [1448 {1449 "type": "text",1450 "text": "Artificial intelligence has transformed modern healthcare in several..."1451 }1452 ]1453 }1454 ],1455 "object": "interaction",1456 "model": "gemini-3.5-flash",1457 }14581459Read about running models and agents asynchronously in the [background execution guide](https://ai.google.dev/gemini-api/docs/interactions-overview#background-execution).14601461## What's next14621463- [Text generation](https://ai.google.dev/gemini-api/docs/text-generation): System instructions, generation config, and advanced text patterns.1464- [Image generation](https://ai.google.dev/gemini-api/docs/image-generation): Aspect ratios, image editing, and style references.1465- [Image understanding](https://ai.google.dev/gemini-api/docs/image-understanding): Classification, object detection, and visual Q\&A.1466- [Thinking](https://ai.google.dev/gemini-api/docs/thinking): Use chain-of-thought reasoning for complex tasks.1467- [Function calling](https://ai.google.dev/gemini-api/docs/function-calling): Parallel, compositional, and constrained function modes.1468- [Google Search](https://ai.google.dev/gemini-api/docs/google-search): Grounding, citations, and search suggestions.1469- [Managed Agents](https://ai.google.dev/gemini-api/docs/managed-agents-quickstart): Pre-built agents with code execution and file management.1470- [Deep Research](https://ai.google.dev/gemini-api/docs/deep-research): Autonomous multi-step research with planning and synthesis.1471- [Structured output](https://ai.google.dev/gemini-api/docs/structured-output): JSON schemas, enums, and recursive type definitions.