Repository Public
1<br />23This guide gets you started with the Gemini API using the [Interactions API](https://ai.google.dev/gemini-api/docs/interactions/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.45The 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.67## 1. Get an API key89To 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:1011[Create a Gemini API Key](https://aistudio.google.com/apikey)1213Then set it as an environment variable:1415 export GEMINI_API_KEY="YOUR_API_KEY"1617## 2. Install the SDK and make your first call1819Install the SDK and generate text with a single API call.2021### Python2223Install the SDK:2425 pip install -U google-genai2627Initialize the client and make a request:2829 from google import genai3031 client = genai.Client()3233 interaction = client.interactions.create(34 model="gemini-3.5-flash",35 input="Explain how AI works in a few words"36 )37 print(interaction.output_text)3839### JavaScript4041Install the SDK:4243 npm install @google/genai4445Initialize the client and make a request:4647 import { GoogleGenAI } from "@google/genai";4849 const ai = new GoogleGenAI({});5051 const interaction = await ai.interactions.create({52 model: "gemini-3.5-flash",53 input: "Explain how AI works in a few words",54 });55 console.log(interaction.output_text);5657### REST5859 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \60 -H "x-goog-api-key: $GEMINI_API_KEY" \61 -H 'Content-Type: application/json' \62 -H "Api-Revision: 2026-05-20" \63 -d '{64 "model": "gemini-3.5-flash",65 "input": "Explain how AI works in a few words"66 }'6768**Response:**6970 {71 "id": "v1_ChdpQUFvYXI...",72 "status": "completed",73 "usage": {74 "total_tokens": 197,75 "total_input_tokens": 8,76 "total_output_tokens": 1277 },78 "created": "2026-06-09T12:01:25Z",79 "steps": [80 {81 "type": "thought",82 "signature": "EvEFCu4FAQw..."83 },84 {85 "type": "model_output",86 "content": [87 {88 "type": "text",89 "text": "AI learns patterns from data, then uses those patterns to make predictions or decisions on new data."90 }91 ]92 }93 ],94 "object": "interaction",95 "model": "gemini-3.5-flash",96 }9798When using REST, the API returns the full `Interaction` resource containing metadata, usage statistics, and the step-by-step history of the turn.99100While 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/interactions-overview) or read the [text generation guide](https://ai.google.dev/gemini-api/docs/interactions/text-generation) for details on system instructions and generation config.101102## 3. Stream the response103104For more fluid interactions, stream the response as it's generated. Each `step.delta` event delivers a chunk of text you can display immediately.105106### Python107108 from google import genai109110 client = genai.Client()111112 stream = client.interactions.create(113 model="gemini-3.5-flash",114 input="Explain how AI works",115 stream=True116 )117 for event in stream:118 print(event)119120### JavaScript121122 import { GoogleGenAI } from "@google/genai";123124 const ai = new GoogleGenAI({});125126 const stream = await ai.interactions.create({127 model: "gemini-3.5-flash",128 input: "Explain how AI works",129 stream: true,130 });131132 for await (const event of stream) {133 console.log(event);134 }135136### REST137138 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse" \139 -H "x-goog-api-key: $GEMINI_API_KEY" \140 -H 'Content-Type: application/json' \141 -H "Api-Revision: 2026-05-20" \142 --no-buffer \143 -d '{144 "model": "gemini-3.5-flash",145 "input": "Explain how AI works",146 "stream": true147 }'148149When streaming, the server responds with a stream of server-sent events (SSE). Each event includes a type and JSON data.150151**Response:**152153 event: interaction.created154 data: {"interaction":{"id":"v1_Chd...","status":"in_progress","model":"gemini-3.5-flash"},"event_type":"interaction.created"}155156 event: step.start157 data: {"index":0,"step":{"type":"thought"},"event_type":"step.start"}158159 event: step.delta160 data: {"index":0,"delta":{"signature":"EvEFCu4F...","type":"thought_signature"},"event_type":"step.delta"}161162 event: step.stop163 data: {"index":0,"event_type":"step.stop"}164165 event: step.start166 data: {"index":1,"step":{"type":"model_output"},"event_type":"step.start"}167168 event: step.delta169 data: {"index":1,"delta":{"text":"AI ","type":"text"},"event_type":"step.delta"}170171 event: step.delta172 data: {"index":1,"delta":{"text":"works ","type":"text"},"event_type":"step.delta"}173174 event: step.stop175 data: {"index":1,"event_type":"step.stop"}176177 event: interaction.completed178 data: {"interaction":{"id":"v1_Chd...","status":"completed","usage":{"total_tokens":197}},"event_type":"interaction.completed"}179180For a detailed look at handling streaming events and delta types, see the [streaming interactions guide](https://ai.google.dev/gemini-api/docs/interactions/streaming).181182## 4. Multi-turn conversations183184The Interactions API supports multi-turn conversations with two approaches:185186- **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.187- **Stateless**: Manage the conversation history on the client by passing all previous turns (including intermediate model thought and tool steps) in each request.188189### Stateful (recommended)190191Chain interactions by passing `previous_interaction_id`. The server manages the full conversation history for you.192193### Python194195 from google import genai196197 client = genai.Client()198199 # Server-side state (recommended)200 interaction1 = client.interactions.create(201 model="gemini-3.5-flash",202 input="I have 2 dogs in my house.",203 )204 print("Response 1:", interaction1.output_text)205206 interaction2 = client.interactions.create(207 model="gemini-3.5-flash",208 input="How many paws are in my house?",209 previous_interaction_id=interaction1.id,210 )211 print("Response 2:", interaction2.output_text)212213### JavaScript214215 import { GoogleGenAI } from "@google/genai";216217 const ai = new GoogleGenAI({});218219 // Server-side state (recommended)220 const interaction1 = await ai.interactions.create({221 model: "gemini-3.5-flash",222 input: "I have 2 dogs in my house.",223 });224 console.log("Response 1:", interaction1.output_text);225226 const interaction2 = await ai.interactions.create({227 model: "gemini-3.5-flash",228 input: "How many paws are in my house?",229 previous_interaction_id: interaction1.id,230 });231 console.log("Response 2:", interaction2.output_text);232233### REST234235 RESPONSE1=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \236 -H "x-goog-api-key: $GEMINI_API_KEY" \237 -H 'Content-Type: application/json' \238 -H "Api-Revision: 2026-05-20" \239 -d '{240 "model": "gemini-3.5-flash",241 "input": "I have 2 dogs in my house."242 }')243244 INTERACTION_ID=$(echo "$RESPONSE1" | jq -r '.id')245 echo "Interaction 1 ID: $INTERACTION_ID"246247 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \248 -H "x-goog-api-key: $GEMINI_API_KEY" \249 -H 'Content-Type: application/json' \250 -H "Api-Revision: 2026-05-20" \251 -d '{252 "model": "gemini-3.5-flash",253 "input": "How many paws are in my house?",254 "previous_interaction_id": "'$INTERACTION_ID'"255 }'256257### Stateless258259Set `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.260261### Python262263 from google import genai264265 client = genai.Client()266267 history = [268 {269 "type": "user_input",270 "content": [{"type": "text", "text": "I have 2 dogs in my house."}]271 }272 ]273274 interaction1 = client.interactions.create(275 model="gemini-3.5-flash",276 store=False,277 input=history278 )279 print("Response 1:", interaction1.steps[-1].content[0].text)280281 for step in interaction1.steps:282 history.append(step.model_dump())283284 history.append({285 "type": "user_input",286 "content": [{"type": "text", "text": "How many paws are in my house?"}]287 })288289 interaction2 = client.interactions.create(290 model="gemini-3.5-flash",291 store=False,292 input=history293 )294 print("Response 2:", interaction2.steps[-1].content[0].text)295296### JavaScript297298 import { GoogleGenAI } from "@google/genai";299300 const ai = new GoogleGenAI({});301302 const history = [303 {304 type: "user_input",305 content: [{ type: "text", text: "I have 2 dogs in my house." }]306 }307 ];308309 const interaction1 = await ai.interactions.create({310 model: "gemini-3.5-flash",311 store: false,312 input: history313 });314 console.log("Response 1:", interaction1.steps.at(-1).content[0].text);315316 history.push(...interaction1.steps);317318 history.push({319 type: "user_input",320 content: [{ type: "text", text: "How many paws are in my house?" }]321 });322323 const interaction2 = await ai.interactions.create({324 model: "gemini-3.5-flash",325 store: false,326 input: history327 });328 console.log("Response 2:", interaction2.steps.at(-1).content[0].text);329330### REST331332 # Turn 1: Send with store: false333 RESPONSE1=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \334 -H "x-goog-api-key: $GEMINI_API_KEY" \335 -H 'Content-Type: application/json' \336 -H "Api-Revision: 2026-05-20" \337 -d '{338 "model": "gemini-3.5-flash",339 "store": false,340 "input": [341 {342 "type": "user_input",343 "content": "I have 2 dogs in my house."344 }345 ]346 }')347348 MODEL_STEPS=$(echo "$RESPONSE1" | jq '.steps')349350 # Turn 2: Build full history351 HISTORY=$(jq -n \352 --argjson first_input '[{"type": "user_input", "content": "I have 2 dogs in my house."}]' \353 --argjson model_steps "$MODEL_STEPS" \354 --argjson second_input '[{"type": "user_input", "content": "How many paws are in my house?"}]' \355 '$first_input + $model_steps + $second_input')356357 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \358 -H "x-goog-api-key: $GEMINI_API_KEY" \359 -H 'Content-Type: application/json' \360 -H "Api-Revision: 2026-05-20" \361 -d "{362 \"model\": \"gemini-3.5-flash\",363 \"store\": false,364 \"input\": $HISTORY365 }"366367**Response:**368369 {370 "id": "v2_Chd...",371 "status": "completed",372 "usage": {373 "total_tokens": 240,374 "total_input_tokens": 60,375 "total_output_tokens": 20376 },377 "steps": [378 {379 "type": "model_output",380 "content": [381 {382 "type": "text",383 "text": "There are 8 paws in your house. 2 dogs \u00d7 4 paws = 8 paws."384 }385 ]386 }387 ],388 "object": "interaction",389 "model": "gemini-3.5-flash"390 }391392The 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/interactions/text-generation#multi-turn-conversations), or explore [stateless mode](https://ai.google.dev/gemini-api/docs/interactions/text-generation#stateless-conversations) for client-side history management.393394## 5. Multimodal understanding395396Gemini models understand images, audio, video, and documents natively. Pass media alongside text in a single request.397398### Python399400 import base64401 from google import genai402403 client = genai.Client()404405 # Load a local image406 with open("sample.jpg", "rb") as f:407 image_bytes = f.read()408 image_b64 = base64.b64encode(image_bytes).decode("utf-8")409410 interaction = client.interactions.create(411 model="gemini-3.5-flash",412 input=[413 {"type": "text", "text": "Compare this local image and this remote audio file."},414 {415 "type": "image",416 "data": image_b64,417 "mime_type": "image/jpeg"418 },419 {420 "type": "audio",421 "uri": "https://storage.googleapis.com/generativeai-downloads/data/sample.mp3",422 "mime_type": "audio/mp3"423 }424 ]425 )426 print(interaction.output_text)427428### JavaScript429430 import fs from "fs";431 import { GoogleGenAI } from "@google/genai";432433 const ai = new GoogleGenAI({});434435 // Load a local image436 const imageBytes = fs.readFileSync("sample.jpg");437 const imageB64 = imageBytes.toString("base64");438439 const interaction = await ai.interactions.create({440 model: "gemini-3.5-flash",441 input: [442 { type: "text", text: "Compare this local image and this remote audio file." },443 {444 type: "image",445 data: imageB64,446 mime_type: "image/jpeg"447 },448 {449 type: "audio",450 uri: "https://storage.googleapis.com/generativeai-downloads/data/sample.mp3",451 mime_type: "audio/mp3"452 }453 ],454 });455 console.log(interaction.output_text);456457### REST458459 # Base64-encode local image460 BASE64_IMAGE=$(base64 -w 0 sample.jpg)461462 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 '{463 "model": "gemini-3.5-flash",464 "input": [465 {466 "type": "text",467 "text": "Compare this local image and this remote audio file."468 },469 {470 "type": "image",471 "data": "'$BASE64_IMAGE'",472 "mime_type": "image/jpeg"473 },474 {475 "type": "audio",476 "uri": "https://storage.googleapis.com/generativeai-downloads/data/sample.mp3",477 "mime_type": "audio/mp3"478 }479 ]480 }'481482**Response:**483484 {485 "id": "v1_Chd...",486 "status": "completed",487 "usage": {488 "total_tokens": 300489 },490 "steps": [491 {492 "type": "model_output",493 "content": [494 {495 "type": "text",496 "text": "The local image displays a pipe organ while the remote audio file is a sample MP3 clip..."497 }498 ]499 }500 ],501 "object": "interaction",502 "model": "gemini-3.5-flash",503 }504505Explore how to pass images, video, and audio files in the [image understanding guide](https://ai.google.dev/gemini-api/docs/interactions/image-understanding).506[Audio understanding507Transcribe, summarize, or answer questions about audio files.](https://ai.google.dev/gemini-api/docs/interactions/audio) [Video understanding508Analyze video content, locate events, and describe actions.](https://ai.google.dev/gemini-api/docs/interactions/video-understanding) [Document processing509Extract information from PDFs and other document formats.](https://ai.google.dev/gemini-api/docs/interactions/document-processing)510511## 6. Multimodal generation512513Gemini can generate images natively using the [Nano Banana](https://ai.google.dev/gemini-api/docs/interactions/image-generation) image models.514515### Python516517 import base64518 from google import genai519520 client = genai.Client()521522 interaction = client.interactions.create(523 model="gemini-3.1-flash-image",524 input="Generate an image of a futuristic city skyline at sunset",525 )526527 with open("generated_image.png", "wb") as f:528 f.write(base64.b64decode(interaction.output_image.data))529530### JavaScript531532 import { GoogleGenAI } from "@google/genai";533 import * as fs from "node:fs";534535 const ai = new GoogleGenAI({});536537 const interaction = await ai.interactions.create({538 model: "gemini-3.1-flash-image",539 input: "Generate an image of a futuristic city skyline at sunset",540 });541542 const generatedImage = interaction.output_image;543 if (generatedImage) {544 const buffer = Buffer.from(generatedImage.data, "base64");545 fs.writeFileSync("generated_image.png", buffer);546 }547548### REST549550 curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \551 -H "x-goog-api-key: $GEMINI_API_KEY" \552 -H 'Content-Type: application/json' \553 -H "Api-Revision: 2026-05-20" \554 -d '{555 "model": "gemini-3.1-flash-image",556 "input": [557 {"type": "text", "text": "Generate an image of a futuristic city skyline at sunset"}558 ]559 }'560561**Response:**562563 {564 "id": "v1_Chd...",565 "status": "completed",566 "steps": [567 {568 "type": "model_output",569 "content": [570 {571 "type": "image",572 "data": "BASE64_ENCODED_IMAGE",573 "mime_type": "image/png"574 }575 ]576 }577 ],578 "object": "interaction",579 "model": "gemini-3.1-flash-image",580 }581582When 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/interactions/image-generation) to learn about aspect ratios, image editing, and references.583[Speech generation584Generate expressive, multi-speaker speech with Gemini 3.1 Flash TTS.](https://ai.google.dev/gemini-api/docs/interactions/speech-generation) [Music generation585Create clips and full-length songs with Lyria 3.](https://ai.google.dev/gemini-api/docs/interactions/music-generation)586587## 7. Use structured output588589Configure 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).590591### Python592593 from google import genai594 from pydantic import BaseModel, Field595 from typing import List, Optional596597 class Recipe(BaseModel):598 recipe_name: str = Field(description="Name of the recipe.")599 ingredients: List[str] = Field(description="List of ingredients.")600 prep_time_minutes: Optional[int] = Field(description="Prep time in minutes.")601602 client = genai.Client()603604 interaction = client.interactions.create(605 model="gemini-3.5-flash",606 input="Give me a recipe for banana bread",607 response_format={608 "type": "text",609 "mime_type": "application/json",610 "schema": Recipe.model_json_schema()611 },612 )613614 recipe = Recipe.model_validate_json(interaction.output_text)615 print(recipe)616617### JavaScript618619 import { GoogleGenAI } from "@google/genai";620 import * as z from "zod";621622 const ai = new GoogleGenAI({});623624 const recipeJsonSchema = {625 type: "object",626 properties: {627 recipe_name: { type: "string", description: "Name of the recipe." },628 ingredients: {629 type: "array",630 items: { type: "string" },631 description: "List of ingredients."632 },633 prep_time_minutes: {634 type: "integer",635 description: "Prep time in minutes."636 }637 },638 required: ["recipe_name", "ingredients"]639 };640641 const recipeSchema = z.fromJSONSchema(recipeJsonSchema);642643 const interaction = await ai.interactions.create({644 model: "gemini-3.5-flash",645 input: "Give me a recipe for banana bread",646 response_format: {647 type: "text",648 mime_type: "application/json",649 schema: recipeJsonSchema650 },651 });652653 const recipe = recipeSchema.parse(JSON.parse(interaction.output_text));654 console.log(recipe);655656### REST657658 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \659 -H "x-goog-api-key: $GEMINI_API_KEY" \660 -H 'Content-Type: application/json' \661 -H "Api-Revision: 2026-05-20" \662 -d '{663 "model": "gemini-3.5-flash",664 "input": "Give me a recipe for banana bread",665 "response_format": {666 "type": "text",667 "mime_type": "application/json",668 "schema": {669 "type": "object",670 "properties": {671 "recipe_name": { "type": "string", "description": "Name of the recipe." },672 "ingredients": {673 "type": "array",674 "items": { "type": "string" },675 "description": "List of ingredients."676 },677 "prep_time_minutes": {678 "type": "integer",679 "description": "Prep time in minutes."680 }681 },682 "required": ["recipe_name", "ingredients"]683 }684 }685 }'686687**Response:**688689 {690 "id": "v1_Chd...",691 "status": "completed",692 "steps": [693 {694 "type": "model_output",695 "content": [696 {697 "type": "text",698 "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}"699 }700 ]701 }702 ],703 "object": "interaction",704 "model": "gemini-3.5-flash",705 }706707The 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/interactions/structured-output).708709## 8. Use tools710711Ground the model's response in real-time information with Google Search. The API automatically searches, processes results, and returns citations.712713### Python714715 from google import genai716717 client = genai.Client()718719 interaction = client.interactions.create(720 model="gemini-3.5-flash",721 input="Who won the euro 2024?",722 tools=[{"type": "google_search"}]723 )724725 print(interaction.output_text)726727 # Print citations728 for step in interaction.steps:729 if step.type == "model_output":730 for content_block in step.content:731 if content_block.type == "text" and content_block.annotations:732 print("\nCitations:")733 for annotation in content_block.annotations:734 if annotation.type == "url_citation":735 print(f" [{annotation.title}]({annotation.url})")736737### JavaScript738739 import { GoogleGenAI } from "@google/genai";740741 const ai = new GoogleGenAI({});742743 const interaction = await ai.interactions.create({744 model: "gemini-3.5-flash",745 input: "Who won the euro 2024?",746 tools: [{ type: "google_search" }]747 });748749 console.log(interaction.output_text);750751 // Print citations752 for (const step of interaction.steps) {753 if (step.type === "model_output") {754 for (const contentBlock of step.content) {755 if (contentBlock.type === "text" && contentBlock.annotations) {756 console.log("\nCitations:");757 for (const annotation of contentBlock.annotations) {758 if (annotation.type === "url_citation") {759 console.log(` [${annotation.title}](${annotation.url})`);760 }761 }762 }763 }764 }765 }766767### REST768769 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \770 -H "x-goog-api-key: $GEMINI_API_KEY" \771 -H 'Content-Type: application/json' \772 -H "Api-Revision: 2026-05-20" \773 -d '{774 "model": "gemini-3.5-flash",775 "input": "Who won the euro 2024?",776 "tools": [{"type": "google_search"}]777 }'778779**Response:**780781 {782 "id": "v1_Chd...",783 "status": "completed",784 "steps": [785 {786 "type": "thought",787 "signature": "EvEFCu4F..."788 },789 {790 "type": "google_search_call",791 "arguments": {792 "queries": ["UEFA Euro 2024 winner"]793 }794 },795 {796 "type": "google_search_result",797 "call_id": "search_001",798 "result": [799 {800 "search_suggestions": "<!-- HTML and CSS search widget -->"801 }802 ]803 },804 {805 "type": "model_output",806 "content": [807 {808 "type": "text",809 "text": "Spain won Euro 2024, defeating England 2-1 in the final.",810 "annotations": [811 {812 "type": "url_citation",813 "url": "https://www.uefa.com/euro2024",814 "title": "uefa.com",815 "start_index": 0,816 "end_index": 56817 }818 ]819 }820 ]821 }822 ],823 "object": "interaction",824 "model": "gemini-3.5-flash",825 }826827The search steps are detailed within the interaction history, and the final output includes inline citations pointing to web sources.828829You can learn how to extract search citations in the [Google Search grounding guide](https://ai.google.dev/gemini-api/docs/interactions/google-search), or see how to combine multiple tools in the [tool combination guide](https://ai.google.dev/gemini-api/docs/interactions/tool-combination).830[Code execution831Run Python code in a secure sandboxed Borg environment.](https://ai.google.dev/gemini-api/docs/interactions/code-execution) [URL context832Pass public web URLs directly to ground responses in webpage content.](https://ai.google.dev/gemini-api/docs/interactions/url-context) [File search833Index and search across uploaded documents and media files.](https://ai.google.dev/gemini-api/docs/interactions/file-search) [Google Maps834Ground responses in real-world geospatial and location data.](https://ai.google.dev/gemini-api/docs/interactions/maps-grounding) [Computer use835Browser automation and screen interaction.](https://ai.google.dev/gemini-api/docs/interactions/computer-use)836837## 9. Call your own functions838839Function 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.840841### Stateful (recommended)842843### Python844845 import json846 from google import genai847848 client = genai.Client()849850 weather_tool = {851 "type": "function",852 "name": "get_current_temperature",853 "description": "Gets the current temperature for a given location.",854 "parameters": {855 "type": "object",856 "properties": {857 "location": {858 "type": "string",859 "description": "The city name, e.g. San Francisco",860 },861 },862 "required": ["location"],863 },864 }865866 available_functions = {867 "get_current_temperature": lambda location: {868 "location": location, "temperature": "22", "unit": "celsius"869 },870 }871872 user_input = "What is the temperature in London?"873 previous_id = None874875 while True:876 interaction = client.interactions.create(877 model="gemini-3.5-flash",878 input=user_input,879 tools=[weather_tool],880 previous_interaction_id=previous_id,881 )882883 function_results = []884 for step in interaction.steps:885 if step.type == "function_call":886 result = available_functions[step.name](**step.arguments)887 print(f"Called {step.name}({step.arguments}) → {result}")888 function_results.append({889 "type": "function_result",890 "name": step.name,891 "call_id": step.id,892 "result": [{"type": "text", "text": json.dumps(result)}],893 })894895 if not function_results:896 break897898 user_input = function_results899 previous_id = interaction.id900901 print(interaction.output_text)902903### JavaScript904905 import { GoogleGenAI } from "@google/genai";906907 const ai = new GoogleGenAI({});908909 const weatherTool = {910 type: "function",911 name: "get_current_temperature",912 description: "Gets the current temperature for a given location.",913 parameters: {914 type: "object",915 properties: {916 location: {917 type: "string",918 description: "The city name, e.g. San Francisco",919 },920 },921 required: ["location"],922 },923 };924925 const availableFunctions = {926 get_current_temperature: ({ location }) => ({927 location, temperature: "22", unit: "celsius"928 }),929 };930931 let input = "What is the temperature in London?";932 let previousId = null;933 let interaction;934935 while (true) {936 interaction = await ai.interactions.create({937 model: "gemini-3.5-flash",938 input,939 tools: [weatherTool],940 previous_interaction_id: previousId,941 });942943 const functionResults = [];944 for (const step of interaction.steps) {945 if (step.type === "function_call") {946 const result = availableFunctions[step.name](step.arguments);947 console.log(`Called ${step.name}(${JSON.stringify(step.arguments)}) →`, result);948 functionResults.push({949 type: "function_result",950 name: step.name,951 call_id: step.id,952 result: [{ type: "text", text: JSON.stringify(result) }],953 });954 }955 }956957 if (functionResults.length === 0) break;958959 input = functionResults;960 previousId = interaction.id;961 }962963 console.log(interaction.output_text);964965### REST966967 # Turn 1: Send prompt with function declaration968 RESPONSE1=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \969 -H "x-goog-api-key: $GEMINI_API_KEY" \970 -H 'Content-Type: application/json' \971 -H "Api-Revision: 2026-05-20" \972 -d '{973 "model": "gemini-3.5-flash",974 "input": "What is the temperature in London?",975 "tools": [{976 "type": "function",977 "name": "get_current_temperature",978 "description": "Gets the current temperature for a given location.",979 "parameters": {980 "type": "object",981 "properties": {982 "location": {"type": "string", "description": "The city name"}983 },984 "required": ["location"]985 }986 }]987 }')988989 INTERACTION_ID=$(echo "$RESPONSE1" | jq -r '.id')990 FC_NAME=$(echo "$RESPONSE1" | jq -r '.steps[] | select(.type=="function_call") | .name')991 FC_ID=$(echo "$RESPONSE1" | jq -r '.steps[] | select(.type=="function_call") | .id')992 echo "Function: $FC_NAME, Call ID: $FC_ID"993994 # Turn 2: Send function result back995 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \996 -H "x-goog-api-key: $GEMINI_API_KEY" \997 -H 'Content-Type: application/json' \998 -H "Api-Revision: 2026-05-20" \999 -d '{1000 "model": "gemini-3.5-flash",1001 "previous_interaction_id": "'$INTERACTION_ID'",1002 "input": [{1003 "type": "function_result",1004 "name": "'$FC_NAME'",1005 "call_id": "'$FC_ID'",1006 "result": [{"type": "text", "text": "{\"location\": \"London\", \"temperature\": \"22\", \"unit\": \"celsius\"}"}]1007 }],1008 "tools": [{1009 "type": "function",1010 "name": "get_current_temperature",1011 "description": "Gets the current temperature for a given location.",1012 "parameters": {1013 "type": "object",1014 "properties": {1015 "location": {"type": "string", "description": "The city name"}1016 },1017 "required": ["location"]1018 }1019 }]1020 }'10211022### Stateless10231024You 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:102510261. The initial `user_input` step.10272. All model-generated steps returned in Turn 1 (including `thought` and `function_call` steps) exactly as received.10283. The `function_result` step containing the output of your executed function.10291030### Python10311032 import json1033 from google import genai10341035 client = genai.Client()10361037 weather_tool = {1038 "type": "function",1039 "name": "get_current_temperature",1040 "description": "Gets the current temperature for a given location.",1041 "parameters": {1042 "type": "object",1043 "properties": {1044 "location": {1045 "type": "string",1046 "description": "The city name, e.g. San Francisco",1047 },1048 },1049 "required": ["location"],1050 },1051 }10521053 available_functions = {1054 "get_current_temperature": lambda location: {1055 "location": location, "temperature": "22", "unit": "celsius"1056 },1057 }10581059 history = [1060 {1061 "type": "user_input",1062 "content": [{"type": "text", "text": "What is the temperature in London?"}]1063 }1064 ]10651066 while True:1067 interaction = client.interactions.create(1068 model="gemini-3.5-flash",1069 store=False,1070 input=history,1071 tools=[weather_tool],1072 )10731074 function_results = []1075 for step in interaction.steps:1076 history.append(step.model_dump())1077 if step.type == "function_call":1078 result = available_functions[step.name](**step.arguments)1079 print(f"Called {step.name}({step.arguments}) → {result}")1080 fn_result = {1081 "type": "function_result",1082 "name": step.name,1083 "call_id": step.id,1084 "result": [{"type": "text", "text": json.dumps(result)}],1085 }1086 function_results.append(fn_result)1087 history.append(fn_result)10881089 if not function_results:1090 break10911092 print(interaction.output_text)10931094### JavaScript10951096 import { GoogleGenAI } from "@google/genai";10971098 const ai = new GoogleGenAI({});10991100 const weatherTool = {1101 type: "function",1102 name: "get_current_temperature",1103 description: "Gets the current temperature for a given location.",1104 parameters: {1105 type: "object",1106 properties: {1107 location: {1108 type: "string",1109 description: "The city name, e.g. San Francisco",1110 },1111 },1112 required: ["location"],1113 },1114 };11151116 const availableFunctions = {1117 get_current_temperature: ({ location }) => ({1118 location, temperature: "22", unit: "celsius"1119 }),1120 };11211122 const history = [1123 {1124 type: "user_input",1125 content: [{ type: "text", text: "What is the temperature in London?" }]1126 }1127 ];11281129 let interaction;11301131 while (true) {1132 interaction = await ai.interactions.create({1133 model: "gemini-3.5-flash",1134 store: false,1135 input: history,1136 tools: [weatherTool],1137 });11381139 const functionResults = [];1140 for (const step of interaction.steps) {1141 history.push(step);1142 if (step.type === "function_call") {1143 const result = availableFunctions[step.name](step.arguments);1144 console.log(`Called ${step.name}(${JSON.stringify(step.arguments)}) →`, result);1145 const fnResult = {1146 type: "function_result",1147 name: step.name,1148 call_id: step.id,1149 result: [{ type: "text", text: JSON.stringify(result) }],1150 };1151 functionResults.push(fnResult);1152 history.push(fnResult);1153 }1154 }11551156 if (functionResults.length === 0) break;1157 }11581159 console.log(interaction.output_text);11601161### REST11621163 # Turn 1: Send request with tools and store: false1164 RESPONSE1=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \1165 -H "x-goog-api-key: $GEMINI_API_KEY" \1166 -H 'Content-Type: application/json' \1167 -H "Api-Revision: 2026-05-20" \1168 -d '{1169 "model": "gemini-3.5-flash",1170 "store": false,1171 "input": [1172 {1173 "type": "user_input",1174 "content": "What is the temperature in London?"1175 }1176 ],1177 "tools": [{1178 "type": "function",1179 "name": "get_current_temperature",1180 "description": "Gets the current temperature for a given location.",1181 "parameters": {1182 "type": "object",1183 "properties": {1184 "location": {"type": "string", "description": "The city name"}1185 },1186 "required": ["location"]1187 }1188 }]1189 }')11901191 # Extract model steps (thought, function_call)1192 MODEL_STEPS=$(echo "$RESPONSE1" | jq '.steps')1193 FC_NAME=$(echo "$RESPONSE1" | jq -r '.steps[] | select(.type=="function_call") | .name')1194 FC_ID=$(echo "$RESPONSE1" | jq -r '.steps[] | select(.type=="function_call") | .id')1195 echo "Function: $FC_NAME, Call ID: $FC_ID"11961197 # Assume local execution returns:1198 RESULT="{\"location\": \"London\", \"temperature\": \"22\", \"unit\": \"celsius\"}"11991200 # Reconstruct history for Turn 21201 HISTORY=$(jq -n \1202 --argjson first_input '[{"type": "user_input", "content": "What is the temperature in London?"}]' \1203 --argjson model_steps "$MODEL_STEPS" \1204 --arg fc_name "$FC_NAME" \1205 --arg fc_id "$FC_ID" \1206 --arg result "$RESULT" \1207 '$first_input + $model_steps + [{"type": "function_result", "name": $fc_name, "call_id": $fc_id, "result": [{"type": "text", "text": $result}]}]')12081209 # Turn 2: Send the full history1210 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \1211 -H "x-goog-api-key: $GEMINI_API_KEY" \1212 -H 'Content-Type: application/json' \1213 -H "Api-Revision: 2026-05-20" \1214 -d "{1215 \"model\": \"gemini-3.5-flash\",1216 \"store\": false,1217 \"input\": $HISTORY,1218 \"tools\": [{1219 \"type\": \"function\",1220 \"name\": \"get_current_temperature\",1221 \"description\": \"Gets the current temperature for a given location.\",1222 \"parameters\": {1223 \"type\": \"object\",1224 \"properties\": {1225 \"location\": {\"type\": \"string\", \"description\": \"The city name\"}1226 },1227 \"required\": [\"location\"]1228 }1229 }]1230 }"12311232**Response:**12331234During Turn 1, the model returns a response with status `requires_action` and the `function_call` step:12351236 {1237 "id": "v1_Chd...",1238 "status": "requires_action",1239 "steps": [1240 {1241 "type": "function_call",1242 "id": "call_abc123",1243 "name": "get_current_temperature",1244 "arguments": {1245 "location": "London"1246 }1247 }1248 ],1249 "object": "interaction",1250 "model": "gemini-3.5-flash"1251 }12521253After you run the function locally and submit the result (Turn 2), the final completed interaction returns:12541255 {1256 "id": "v1_Chd...",1257 "status": "completed",1258 "steps": [1259 {1260 "type": "function_call",1261 "id": "call_abc123",1262 "name": "get_current_temperature",1263 "arguments": {1264 "location": "London"1265 }1266 },1267 {1268 "type": "model_output",1269 "content": [1270 {1271 "type": "text",1272 "text": "The temperature in London is currently 22°C."1273 }1274 ]1275 }1276 ],1277 "object": "interaction",1278 "model": "gemini-3.5-flash",1279 }12801281For advanced features like parallel function calling or function choice modes, see the [function calling guide](https://ai.google.dev/gemini-api/docs/interactions/function-calling).12821283## 10. Run a managed agent12841285Managed 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"`.12861287### Python12881289 from google import genai12901291 client = genai.Client()12921293 interaction = client.interactions.create(1294 agent="antigravity-preview-05-2026",1295 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.",1296 environment="remote",1297 )1298 print(f"Environment: {interaction.environment_id}")1299 print(interaction.output_text)13001301### JavaScript13021303 import { GoogleGenAI } from "@google/genai";13041305 const ai = new GoogleGenAI({});13061307 const interaction = await ai.interactions.create({1308 agent: "antigravity-preview-05-2026",1309 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.",1310 environment: "remote",1311 });1312 console.log(`Environment: ${interaction.environment_id}`);1313 console.log(interaction.output_text);13141315### REST13161317 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \1318 -H "x-goog-api-key: $GEMINI_API_KEY" \1319 -H 'Content-Type: application/json' \1320 -H "Api-Revision: 2026-05-20" \1321 -d '{1322 "agent": "antigravity-preview-05-2026",1323 "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.",1324 "environment": "remote"1325 }'13261327You can also define and save [custom agents](https://ai.google.dev/gemini-api/docs/custom-agents) with your own instructions, skills, and data sources.1328[Quickstart1329Make your first agent call, stream responses, and build a custom agent.](https://ai.google.dev/gemini-api/docs/managed-agents-quickstart) [Antigravity Agent1330Capabilities, tools, multimodal input, and pricing for the default agent.](https://ai.google.dev/gemini-api/docs/antigravity-agent) [Agents in AI Studio1331Visual playground for prototyping agents without writing code.](https://ai.google.dev/gemini-api/docs/aistudio-agents)13321333## 11. Run tasks in the background13341335Set `background=True` to run long tasks asynchronously. Poll for results with `interactions.get()`.13361337### Python13381339 import time1340 from google import genai13411342 client = genai.Client()13431344 interaction = client.interactions.create(1345 model="gemini-3.5-flash",1346 input="Write a detailed analysis of the impact of artificial intelligence on modern healthcare.",1347 background=True,1348 )1349 print(f"Started background task: {interaction.id}")1350 print(f"Status: {interaction.status}")13511352 # Poll for completion1353 while True:1354 result = client.interactions.get(interaction.id)1355 print(f"Status: {result.status}")1356 if result.status == "completed":1357 print(f"\nResult:\n{result.output_text}")1358 break1359 elif result.status == "failed":1360 print(f"Failed: {result.error}")1361 break1362 time.sleep(5)13631364### JavaScript13651366 import { GoogleGenAI } from "@google/genai";13671368 const ai = new GoogleGenAI({});13691370 const interaction = await ai.interactions.create({1371 model: "gemini-3.5-flash",1372 input: "Write a detailed analysis of the impact of artificial intelligence on modern healthcare.",1373 background: true,1374 });1375 console.log(`Started background task: ${interaction.id}`);1376 console.log(`Status: ${interaction.status}`);13771378 // Poll for completion1379 while (true) {1380 const result = await ai.interactions.get(interaction.id);1381 console.log(`Status: ${result.status}`);1382 if (result.status === "completed") {1383 console.log(`\nResult:\n${result.output_text}`);1384 break;1385 } else if (result.status === "failed") {1386 console.log(`Failed: ${result.error}`);1387 break;1388 }1389 await new Promise(r => setTimeout(r, 5000));1390 }13911392### REST13931394 # Start a background task1395 RESPONSE=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \1396 -H "x-goog-api-key: $GEMINI_API_KEY" \1397 -H 'Content-Type: application/json' \1398 -H "Api-Revision: 2026-05-20" \1399 -d '{1400 "model": "gemini-3.5-flash",1401 "input": "Write a detailed analysis of the impact of artificial intelligence on modern healthcare.",1402 "background": true1403 }')14041405 INTERACTION_ID=$(echo "$RESPONSE" | jq -r '.id')1406 echo "Started background task: $INTERACTION_ID"14071408 # Poll for completion1409 while true; do1410 RESULT=$(curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/$INTERACTION_ID" \1411 -H "x-goog-api-key: $GEMINI_API_KEY" \1412 -H "Api-Revision: 2026-05-20")1413 STATUS=$(echo "$RESULT" | jq -r '.status')1414 echo "Status: $STATUS"1415 if [ "$STATUS" = "completed" ]; then1416 echo "$RESULT" | jq -r '.steps[] | select(.type=="model_output") | .content[] | select(.type=="text") | .text'1417 break1418 elif [ "$STATUS" = "failed" ]; then1419 echo "Failed"1420 break1421 fi1422 sleep 51423 done14241425**Response:**14261427The initial response returns immediately with status `in_progress`:14281429 {1430 "id": "v1_abc123",1431 "status": "in_progress",1432 "object": "interaction",1433 "model": "gemini-3.5-flash"1434 }14351436Once the background task is fully executed, checking the interaction state returns:14371438 {1439 "id": "v1_abc123",1440 "status": "completed",1441 "steps": [1442 {1443 "type": "model_output",1444 "content": [1445 {1446 "type": "text",1447 "text": "Artificial intelligence has transformed modern healthcare in several..."1448 }1449 ]1450 }1451 ],1452 "object": "interaction",1453 "model": "gemini-3.5-flash",1454 }14551456Read about running models and agents asynchronously in the [background execution guide](https://ai.google.dev/gemini-api/docs/interactions/interactions-overview#background-execution).14571458## What's next14591460- [Text generation](https://ai.google.dev/gemini-api/docs/interactions/text-generation): System instructions, generation config, and advanced text patterns.1461- [Image generation](https://ai.google.dev/gemini-api/docs/interactions/image-generation): Aspect ratios, image editing, and style references.1462- [Image understanding](https://ai.google.dev/gemini-api/docs/interactions/image-understanding): Classification, object detection, and visual Q\&A.1463- [Thinking](https://ai.google.dev/gemini-api/docs/interactions/thinking): Use chain-of-thought reasoning for complex tasks.1464- [Function calling](https://ai.google.dev/gemini-api/docs/interactions/function-calling): Parallel, compositional, and constrained function modes.1465- [Google Search](https://ai.google.dev/gemini-api/docs/interactions/google-search): Grounding, citations, and search suggestions.1466- [Managed Agents](https://ai.google.dev/gemini-api/docs/managed-agents-quickstart): Pre-built agents with code execution and file management.1467- [Deep Research](https://ai.google.dev/gemini-api/docs/interactions/deep-research): Autonomous multi-step research with planning and synthesis.1468- [Structured output](https://ai.google.dev/gemini-api/docs/interactions/structured-output): JSON schemas, enums, and recursive type definitions.