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-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.45> [!NOTE]6> **Building with an AI coding agent?** Install the skill and then paste the prompt to get started with the Gemini API using Interactions:7>8> ```9> npx skills add google-gemini/gemini-skills --skill gemini-api-dev10> ```1112The 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.1314## 1. Get an API key1516To use the Gemini API, you need to have an API key to authenticate your requests, enforce security limits, and track usage to your account.1718- Google AI Studio automatically creates a project and API key for new users. You can copy it from the [API keys page](https://aistudio.google.com/api-keys).19- If you need a new key, click **Create API key** in AI Studio and follow the dialog to add a new key-project pair.2021[Create a Gemini API Key](https://aistudio.google.com/apikey)2223Set your key as an environment variable:2425 export GEMINI_API_KEY="YOUR_API_KEY"2627### Upgrade to the paid tier2829Upgrading to the paid tier increases your rate limits and requires setting up30Cloud Billing.3132- Click **Set up billing** on the AI Studio [API keys](https://aistudio.google.com/api-keys) or [Projects](https://aistudio.google.com/projects) pages.33- Follow the Cloud Billing dialog to create or link a billing account, add a payment method, and prepay a minimum of $5 (or currency equivalent) in paid credits.34- View your API usage in [Google AI Studio](https://aistudio.google.com/usage) under **Dashboard** \> **Usage**.3536See the [Billing page](https://ai.google.dev/gemini-api/docs/billing) for more information.3738## 2. Install the SDK and make your first call3940Install the SDK and generate text with a single API call.4142### Python4344Install the SDK:4546 pip install -U google-genai4748Initialize the client and make a request:4950 from google import genai5152 client = genai.Client()5354 interaction = client.interactions.create(55 model="gemini-3.8-flash",56 input="Explain how AI works in a few words"57 )58 print(interaction.output_text)5960### JavaScript6162Install the SDK:6364 npm install @google/genai6566Initialize the client and make a request:6768 import { GoogleGenAI } from "@google/genai";6970 const ai = new GoogleGenAI({});7172 const interaction = await ai.interactions.create({73 model: "gemini-3.8-flash",74 input: "Explain how AI works in a few words",75 });76 console.log(interaction.output_text);7778### Java7980 import com.google.genai.Client;81 import com.google.genai.gaos.models.interactions.CreateModelInteraction;82 import com.google.genai.gaos.models.interactions.Interaction;83 import com.google.genai.gaos.models.interactions.InteractionsInput;84 import com.google.genai.gaos.models.interactions.Model;85 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;8687 Client client = new Client();8889 CreateModelInteraction params =90 CreateModelInteraction.builder()91 .model(Model.of("gemini-3.8-flash"))92 .input(InteractionsInput.of("Explain how AI works in a few words"))93 .build();9495 Interaction interaction =96 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();9798 System.out.println(interaction.outputText().orElse(""));99100### REST101102 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \103 -H "x-goog-api-key: $GEMINI_API_KEY" \104 -H 'Content-Type: application/json' \105 -d '{106 "model": "gemini-3.8-flash",107 "input": "Explain how AI works in a few words"108 }'109110**Response:**111112 {113 "id": "v1_ChdpQUFvYXI...",114 "status": "completed",115 "usage": {116 "total_tokens": 197,117 "total_input_tokens": 8,118 "total_output_tokens": 12119 },120 "created": "2026-06-09T12:01:25Z",121 "steps": [122 {123 "type": "thought",124 "signature": "EvEFCu4FAQw..."125 },126 {127 "type": "model_output",128 "content": [129 {130 "type": "text",131 "text": "AI learns patterns from data, then uses those patterns to make predictions or decisions on new data."132 }133 ]134 }135 ],136 "object": "interaction",137 "model": "gemini-3.8-flash",138 }139140When using REST, the API returns the full `Interaction` resource containing metadata, usage statistics, and the step-by-step history of the turn.141142While 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.143144## 3. Stream the response145146For more fluid interactions, stream the response as it's generated. Each `step.delta` event delivers a chunk of text you can display immediately.147148### Python149150 from google import genai151152 client = genai.Client()153154 stream = client.interactions.create(155 model="gemini-3.8-flash",156 input="Explain how AI works",157 stream=True158 )159 for event in stream:160 print(event)161162### JavaScript163164 import { GoogleGenAI } from "@google/genai";165166 const ai = new GoogleGenAI({});167168 const stream = await ai.interactions.create({169 model: "gemini-3.8-flash",170 input: "Explain how AI works",171 stream: true,172 });173174 for await (const event of stream) {175 console.log(event);176 }177178### Java179180 import com.google.genai.Client;181 import com.google.genai.gaos.models.interactions.CreateModelInteraction;182 import com.google.genai.gaos.models.interactions.InteractionSSEStreamEvent;183 import com.google.genai.gaos.models.interactions.InteractionsInput;184 import com.google.genai.gaos.models.interactions.Model;185 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;186 import com.google.genai.gaos.models.operations.CreateInteractionResponse;187 import com.google.genai.gaos.utils.EventStream;188189 Client client = new Client();190191 CreateModelInteraction params =192 CreateModelInteraction.builder()193 .model(Model.of("gemini-3.8-flash"))194 .input(InteractionsInput.of("Explain how AI works"))195 .stream(true)196 .build();197198 CreateInteractionResponse response =199 client.interactions.create(CreateInteractionRequestBody.of(params));200201 try (EventStream<InteractionSSEStreamEvent> stream = response.events()) {202 for (InteractionSSEStreamEvent event : stream) {203 System.out.println(event);204 }205 }206207### REST208209 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse" \210 -H "x-goog-api-key: $GEMINI_API_KEY" \211 -H 'Content-Type: application/json' \212 --no-buffer \213 -d '{214 "model": "gemini-3.8-flash",215 "input": "Explain how AI works",216 "stream": true217 }'218219When streaming, the server responds with a stream of server-sent events (SSE). Each event includes a type and JSON data.220221**Response:**222223 event: interaction.created224 data: {"interaction":{"id":"v1_Chd...","status":"in_progress","model":"gemini-3.8-flash"},"event_type":"interaction.created"}225226 event: step.start227 data: {"index":0,"step":{"type":"thought"},"event_type":"step.start"}228229 event: step.delta230 data: {"index":0,"delta":{"signature":"EvEFCu4F...","type":"thought_signature"},"event_type":"step.delta"}231232 event: step.stop233 data: {"index":0,"event_type":"step.stop"}234235 event: step.start236 data: {"index":1,"step":{"type":"model_output"},"event_type":"step.start"}237238 event: step.delta239 data: {"index":1,"delta":{"text":"AI ","type":"text"},"event_type":"step.delta"}240241 event: step.delta242 data: {"index":1,"delta":{"text":"works ","type":"text"},"event_type":"step.delta"}243244 event: step.stop245 data: {"index":1,"event_type":"step.stop"}246247 event: interaction.completed248 data: {"interaction":{"id":"v1_Chd...","status":"completed","usage":{"total_tokens":197}},"event_type":"interaction.completed"}249250For a detailed look at handling streaming events and delta types, see the [streaming interactions guide](https://ai.google.dev/gemini-api/docs/streaming).251252## 4. Multi-turn conversations253254The Interactions API supports multi-turn conversations with two approaches:255256- **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.257- **Stateless**: Manage the conversation history on the client by passing all previous turns (including intermediate model thought and tool steps) in each request.258259### Stateful (recommended)260261Chain interactions by passing `previous_interaction_id`. The server manages the full conversation history for you.262263### Python264265 from google import genai266267 client = genai.Client()268269 # Server-side state (recommended)270 interaction1 = client.interactions.create(271 model="gemini-3.8-flash",272 input="I have 2 dogs in my house.",273 )274 print("Response 1:", interaction1.output_text)275276 interaction2 = client.interactions.create(277 model="gemini-3.8-flash",278 input="How many paws are in my house?",279 previous_interaction_id=interaction1.id,280 )281 print("Response 2:", interaction2.output_text)282283### JavaScript284285 import { GoogleGenAI } from "@google/genai";286287 const ai = new GoogleGenAI({});288289 // Server-side state (recommended)290 const interaction1 = await ai.interactions.create({291 model: "gemini-3.8-flash",292 input: "I have 2 dogs in my house.",293 });294 console.log("Response 1:", interaction1.output_text);295296 const interaction2 = await ai.interactions.create({297 model: "gemini-3.8-flash",298 input: "How many paws are in my house?",299 previous_interaction_id: interaction1.id,300 });301 console.log("Response 2:", interaction2.output_text);302303### Java304305 import com.google.genai.Client;306 import com.google.genai.gaos.models.interactions.CreateModelInteraction;307 import com.google.genai.gaos.models.interactions.Interaction;308 import com.google.genai.gaos.models.interactions.InteractionsInput;309 import com.google.genai.gaos.models.interactions.Model;310 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;311312 Client client = new Client();313314 // Server-side state (recommended)315 CreateModelInteraction params1 =316 CreateModelInteraction.builder()317 .model(Model.of("gemini-3.8-flash"))318 .input(InteractionsInput.of("I have 2 dogs in my house."))319 .build();320321 Interaction interaction1 =322 client.interactions.create(CreateInteractionRequestBody.of(params1)).interaction().get();323 System.out.println("Response 1: " + interaction1.outputText().orElse(""));324325 CreateModelInteraction params2 =326 CreateModelInteraction.builder()327 .model(Model.of("gemini-3.8-flash"))328 .input(InteractionsInput.of("How many paws are in my house?"))329 .previousInteractionId(interaction1.id().orElse(""))330 .build();331332 Interaction interaction2 =333 client.interactions.create(CreateInteractionRequestBody.of(params2)).interaction().get();334 System.out.println("Response 2: " + interaction2.outputText().orElse(""));335336### REST337338 RESPONSE1=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \339 -H "x-goog-api-key: $GEMINI_API_KEY" \340 -H 'Content-Type: application/json' \341 -d '{342 "model": "gemini-3.8-flash",343 "input": "I have 2 dogs in my house."344 }')345346 INTERACTION_ID=$(echo "$RESPONSE1" | jq -r '.id')347 echo "Interaction 1 ID: $INTERACTION_ID"348349 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \350 -H "x-goog-api-key: $GEMINI_API_KEY" \351 -H 'Content-Type: application/json' \352 -d '{353 "model": "gemini-3.8-flash",354 "input": "How many paws are in my house?",355 "previous_interaction_id": "'$INTERACTION_ID'"356 }'357358### Stateless359360Set `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.361362### Python363364 from google import genai365366 client = genai.Client()367368 history = [369 {370 "type": "user_input",371 "content": [{"type": "text", "text": "I have 2 dogs in my house."}]372 }373 ]374375 interaction1 = client.interactions.create(376 model="gemini-3.8-flash",377 store=False,378 input=history379 )380 print("Response 1:", interaction1.steps[-1].content[0].text)381382 for step in interaction1.steps:383 history.append(step.model_dump())384385 history.append({386 "type": "user_input",387 "content": [{"type": "text", "text": "How many paws are in my house?"}]388 })389390 interaction2 = client.interactions.create(391 model="gemini-3.8-flash",392 store=False,393 input=history394 )395 print("Response 2:", interaction2.steps[-1].content[0].text)396397### JavaScript398399 import { GoogleGenAI } from "@google/genai";400401 const ai = new GoogleGenAI({});402403 const history = [404 {405 type: "user_input",406 content: [{ type: "text", text: "I have 2 dogs in my house." }]407 }408 ];409410 const interaction1 = await ai.interactions.create({411 model: "gemini-3.8-flash",412 store: false,413 input: history414 });415 console.log("Response 1:", interaction1.steps.at(-1).content[0].text);416417 history.push(...interaction1.steps);418419 history.push({420 type: "user_input",421 content: [{ type: "text", text: "How many paws are in my house?" }]422 });423424 const interaction2 = await ai.interactions.create({425 model: "gemini-3.8-flash",426 store: false,427 input: history428 });429 console.log("Response 2:", interaction2.steps.at(-1).content[0].text);430431### Java432433 import com.google.genai.Client;434 import com.google.genai.gaos.models.interactions.CreateModelInteraction;435 import com.google.genai.gaos.models.interactions.Interaction;436 import com.google.genai.gaos.models.interactions.InteractionsInput;437 import com.google.genai.gaos.models.interactions.Model;438 import com.google.genai.gaos.models.interactions.Step;439 import com.google.genai.gaos.models.interactions.TextContent;440 import com.google.genai.gaos.models.interactions.UserInputStep;441 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;442 import java.util.ArrayList;443 import java.util.Arrays;444 import java.util.List;445446 Client client = new Client();447448 List<Step> history = new ArrayList<>();449 history.add(450 UserInputStep.builder()451 .content(Arrays.asList(TextContent.builder().text("I have 2 dogs in my house.").build()))452 .build());453454 CreateModelInteraction params1 =455 CreateModelInteraction.builder()456 .model(Model.of("gemini-3.8-flash"))457 .store(false)458 .input(InteractionsInput.ofStep(history))459 .build();460461 Interaction interaction1 =462 client.interactions.create(CreateInteractionRequestBody.of(params1)).interaction().get();463 System.out.println("Response 1: " + interaction1.outputText().orElse(""));464465 interaction1.steps().ifPresent(history::addAll);466467 history.add(468 UserInputStep.builder()469 .content(Arrays.asList(TextContent.builder().text("How many paws are in my house?").build()))470 .build());471472 CreateModelInteraction params2 =473 CreateModelInteraction.builder()474 .model(Model.of("gemini-3.8-flash"))475 .store(false)476 .input(InteractionsInput.ofStep(history))477 .build();478479 Interaction interaction2 =480 client.interactions.create(CreateInteractionRequestBody.of(params2)).interaction().get();481 System.out.println("Response 2: " + interaction2.outputText().orElse(""));482483### REST484485 # Turn 1: Send with store: false486 RESPONSE1=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \487 -H "x-goog-api-key: $GEMINI_API_KEY" \488 -H 'Content-Type: application/json' \489 -d '{490 "model": "gemini-3.8-flash",491 "store": false,492 "input": [493 {494 "type": "user_input",495 "content": "I have 2 dogs in my house."496 }497 ]498 }')499500 MODEL_STEPS=$(echo "$RESPONSE1" | jq '.steps')501502 # Turn 2: Build full history503 HISTORY=$(jq -n \504 --argjson first_input '[{"type": "user_input", "content": "I have 2 dogs in my house."}]' \505 --argjson model_steps "$MODEL_STEPS" \506 --argjson second_input '[{"type": "user_input", "content": "How many paws are in my house?"}]' \507 '$first_input + $model_steps + $second_input')508509 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \510 -H "x-goog-api-key: $GEMINI_API_KEY" \511 -H 'Content-Type: application/json' \512 -d "{513 \"model\": \"gemini-3.8-flash\",514 \"store\": false,515 \"input\": $HISTORY516 }"517518**Response:**519520 {521 "id": "v2_Chd...",522 "status": "completed",523 "usage": {524 "total_tokens": 240,525 "total_input_tokens": 60,526 "total_output_tokens": 20527 },528 "steps": [529 {530 "type": "model_output",531 "content": [532 {533 "type": "text",534 "text": "There are 8 paws in your house. 2 dogs \u00d7 4 paws = 8 paws."535 }536 ]537 }538 ],539 "object": "interaction",540 "model": "gemini-3.8-flash"541 }542543The 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.544545## 5. Multimodal understanding546547Gemini models understand images, audio, video, and documents natively. Pass media alongside text in a single request.548549### Python550551 import base64552 from google import genai553554 client = genai.Client()555556 # Load a local image557 with open("sample.jpg", "rb") as f:558 image_bytes = f.read()559 image_b64 = base64.b64encode(image_bytes).decode("utf-8")560561 interaction = client.interactions.create(562 model="gemini-3.8-flash",563 input=[564 {"type": "text", "text": "Compare this local image and this remote audio file."},565 {566 "type": "image",567 "data": image_b64,568 "mime_type": "image/jpeg"569 },570 {571 "type": "audio",572 "uri": "https://storage.googleapis.com/generativeai-downloads/data/sample.mp3",573 "mime_type": "audio/mp3"574 }575 ]576 )577 print(interaction.output_text)578579### JavaScript580581 import fs from "fs";582 import { GoogleGenAI } from "@google/genai";583584 const ai = new GoogleGenAI({});585586 // Load a local image587 const imageBytes = fs.readFileSync("sample.jpg");588 const imageB64 = imageBytes.toString("base64");589590 const interaction = await ai.interactions.create({591 model: "gemini-3.8-flash",592 input: [593 { type: "text", text: "Compare this local image and this remote audio file." },594 {595 type: "image",596 data: imageB64,597 mime_type: "image/jpeg"598 },599 {600 type: "audio",601 uri: "https://storage.googleapis.com/generativeai-downloads/data/sample.mp3",602 mime_type: "audio/mp3"603 }604 ],605 });606 console.log(interaction.output_text);607608### Java609610 import com.google.genai.Client;611 import com.google.genai.gaos.models.interactions.AudioContent;612 import com.google.genai.gaos.models.interactions.AudioContentMimeType;613 import com.google.genai.gaos.models.interactions.CreateModelInteraction;614 import com.google.genai.gaos.models.interactions.ImageContent;615 import com.google.genai.gaos.models.interactions.ImageContentMimeType;616 import com.google.genai.gaos.models.interactions.Interaction;617 import com.google.genai.gaos.models.interactions.InteractionsInput;618 import com.google.genai.gaos.models.interactions.Model;619 import com.google.genai.gaos.models.interactions.TextContent;620 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;621 import java.nio.file.Files;622 import java.nio.file.Path;623 import java.util.Arrays;624 import java.util.Base64;625626 Client client = new Client();627628 // Load a local image629 byte[] imageBytes = Files.readAllBytes(Path.of("sample.jpg"));630 String imageB64 = Base64.getEncoder().encodeToString(imageBytes);631632 CreateModelInteraction params =633 CreateModelInteraction.builder()634 .model(Model.of("gemini-3.8-flash"))635 .input(636 InteractionsInput.ofContent(637 Arrays.asList(638 TextContent.builder()639 .text("Compare this local image and this remote audio file.")640 .build(),641 ImageContent.builder()642 .data(imageB64)643 .mimeType(ImageContentMimeType.IMAGE_JPEG)644 .build(),645 AudioContent.builder()646 .uri("https://storage.googleapis.com/generativeai-downloads/data/sample.mp3")647 .mimeType(AudioContentMimeType.AUDIO_MP3)648 .build())))649 .build();650651 Interaction interaction =652 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();653 System.out.println(interaction.outputText().orElse(""));654655### REST656657 # Base64-encode local image658 BASE64_IMAGE=$(base64 -w 0 sample.jpg)659660 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 '{661 "model": "gemini-3.8-flash",662 "input": [663 {664 "type": "text",665 "text": "Compare this local image and this remote audio file."666 },667 {668 "type": "image",669 "data": "'$BASE64_IMAGE'",670 "mime_type": "image/jpeg"671 },672 {673 "type": "audio",674 "uri": "https://storage.googleapis.com/generativeai-downloads/data/sample.mp3",675 "mime_type": "audio/mp3"676 }677 ]678 }'679680**Response:**681682 {683 "id": "v1_Chd...",684 "status": "completed",685 "usage": {686 "total_tokens": 300687 },688 "steps": [689 {690 "type": "model_output",691 "content": [692 {693 "type": "text",694 "text": "The local image displays a pipe organ while the remote audio file is a sample MP3 clip..."695 }696 ]697 }698 ],699 "object": "interaction",700 "model": "gemini-3.8-flash",701 }702703Explore how to pass images, video, and audio files in the [image understanding guide](https://ai.google.dev/gemini-api/docs/image-understanding).704[Audio understanding705Transcribe, summarize, or answer questions about audio files.](https://ai.google.dev/gemini-api/docs/audio) [Video understanding706Analyze video content, locate events, and describe actions.](https://ai.google.dev/gemini-api/docs/video-understanding) [Document processing707Extract information from PDFs and other document formats.](https://ai.google.dev/gemini-api/docs/document-processing)708709## 6. Multimodal generation710711Gemini can generate images natively using the [Nano Banana](https://ai.google.dev/gemini-api/docs/image-generation) image models.712713### Python714715 import base64716 from google import genai717718 client = genai.Client()719720 interaction = client.interactions.create(721 model="gemini-3.1-flash-image",722 input="Generate an image of a futuristic city skyline at sunset",723 )724725 with open("generated_image.png", "wb") as f:726 f.write(base64.b64decode(interaction.output_image.data))727728### JavaScript729730 import { GoogleGenAI } from "@google/genai";731 import * as fs from "node:fs";732733 const ai = new GoogleGenAI({});734735 const interaction = await ai.interactions.create({736 model: "gemini-3.1-flash-image",737 input: "Generate an image of a futuristic city skyline at sunset",738 });739740 const generatedImage = interaction.output_image;741 if (generatedImage) {742 const buffer = Buffer.from(generatedImage.data, "base64");743 fs.writeFileSync("generated_image.png", buffer);744 }745746### Java747748 import com.google.genai.Client;749 import com.google.genai.gaos.models.interactions.CreateModelInteraction;750 import com.google.genai.gaos.models.interactions.ImageContent;751 import com.google.genai.gaos.models.interactions.Interaction;752 import com.google.genai.gaos.models.interactions.InteractionsInput;753 import com.google.genai.gaos.models.interactions.Model;754 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;755 import java.nio.file.Files;756 import java.nio.file.Path;757 import java.util.Base64;758759 Client client = new Client();760761 CreateModelInteraction params =762 CreateModelInteraction.builder()763 .model(Model.of("gemini-3.1-flash-image"))764 .input(InteractionsInput.of("Generate an image of a futuristic city skyline at sunset"))765 .build();766767 Interaction interaction =768 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();769770 if (interaction.outputImage().isPresent()) {771 ImageContent generatedImage = interaction.outputImage().get();772 if (generatedImage.data().isPresent()) {773 byte[] imageBytes = Base64.getDecoder().decode(generatedImage.data().get());774 Files.write(Path.of("generated_image.png"), imageBytes);775 }776 }777778### REST779780 curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \781 -H "x-goog-api-key: $GEMINI_API_KEY" \782 -H 'Content-Type: application/json' \783 -d '{784 "model": "gemini-3.1-flash-image",785 "input": [786 {"type": "text", "text": "Generate an image of a futuristic city skyline at sunset"}787 ]788 }'789790**Response:**791792 {793 "id": "v1_Chd...",794 "status": "completed",795 "steps": [796 {797 "type": "model_output",798 "content": [799 {800 "type": "image",801 "data": "BASE64_ENCODED_IMAGE",802 "mime_type": "image/png"803 }804 ]805 }806 ],807 "object": "interaction",808 "model": "gemini-3.1-flash-image",809 }810811When 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.812[Speech generation813Generate expressive, multi-speaker speech with Gemini 3.1 Flash TTS.](https://ai.google.dev/gemini-api/docs/speech-generation) [Music generation814Create clips and full-length songs with Lyria 3.5.](https://ai.google.dev/gemini-api/docs/music-generation)815816## 7. Use structured output817818Configure 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).819820### Python821822 from google import genai823 from pydantic import BaseModel, Field824 from typing import List, Optional825826 class Recipe(BaseModel):827 recipe_name: str = Field(description="Name of the recipe.")828 ingredients: List[str] = Field(description="List of ingredients.")829 prep_time_minutes: Optional[int] = Field(description="Prep time in minutes.")830831 client = genai.Client()832833 interaction = client.interactions.create(834 model="gemini-3.8-flash",835 input="Give me a recipe for banana bread",836 response_format={837 "type": "text",838 "mime_type": "application/json",839 "schema": Recipe.model_json_schema()840 },841 )842843 recipe = Recipe.model_validate_json(interaction.output_text)844 print(recipe)845846### JavaScript847848 import { GoogleGenAI } from "@google/genai";849 import * as z from "zod";850851 const ai = new GoogleGenAI({});852853 const recipeJsonSchema = {854 type: "object",855 properties: {856 recipe_name: { type: "string", description: "Name of the recipe." },857 ingredients: {858 type: "array",859 items: { type: "string" },860 description: "List of ingredients."861 },862 prep_time_minutes: {863 type: "integer",864 description: "Prep time in minutes."865 }866 },867 required: ["recipe_name", "ingredients"]868 };869870 const recipeSchema = z.fromJSONSchema(recipeJsonSchema);871872 const interaction = await ai.interactions.create({873 model: "gemini-3.8-flash",874 input: "Give me a recipe for banana bread",875 response_format: {876 type: "text",877 mime_type: "application/json",878 schema: recipeJsonSchema879 },880 });881882 const recipe = recipeSchema.parse(JSON.parse(interaction.output_text));883 console.log(recipe);884885### Java886887 import com.google.genai.Client;888 import com.google.genai.gaos.models.interactions.CreateModelInteraction;889 import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;890 import com.google.genai.gaos.models.interactions.Interaction;891 import com.google.genai.gaos.models.interactions.InteractionsInput;892 import com.google.genai.gaos.models.interactions.Model;893 import com.google.genai.gaos.models.interactions.ResponseFormat;894 import com.google.genai.gaos.models.interactions.TextResponseFormat;895 import com.google.genai.gaos.models.interactions.TextResponseFormatMimeType;896 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;897 import java.util.Arrays;898 import java.util.HashMap;899 import java.util.Map;900901 Client client = new Client();902903 Map<String, Object> recipeNameProp = new HashMap<>();904 recipeNameProp.put("type", "string");905 recipeNameProp.put("description", "Name of the recipe.");906907 Map<String, Object> itemsProp = new HashMap<>();908 itemsProp.put("type", "string");909910 Map<String, Object> ingredientsProp = new HashMap<>();911 ingredientsProp.put("type", "array");912 ingredientsProp.put("items", itemsProp);913 ingredientsProp.put("description", "List of ingredients.");914915 Map<String, Object> prepTimeProp = new HashMap<>();916 prepTimeProp.put("type", "integer");917 prepTimeProp.put("description", "Prep time in minutes.");918919 Map<String, Object> properties = new HashMap<>();920 properties.put("recipe_name", recipeNameProp);921 properties.put("ingredients", ingredientsProp);922 properties.put("prep_time_minutes", prepTimeProp);923924 Map<String, Object> recipeJsonSchema = new HashMap<>();925 recipeJsonSchema.put("type", "object");926 recipeJsonSchema.put("properties", properties);927 recipeJsonSchema.put("required", Arrays.asList("recipe_name", "ingredients"));928929 CreateModelInteractionResponseFormat format =930 CreateModelInteractionResponseFormat.of(931 ResponseFormat.of(932 TextResponseFormat.builder()933 .mimeType(TextResponseFormatMimeType.APPLICATION_JSON)934 .schema(recipeJsonSchema)935 .build()));936937 CreateModelInteraction params =938 CreateModelInteraction.builder()939 .model(Model.of("gemini-3.8-flash"))940 .input(InteractionsInput.of("Give me a recipe for banana bread"))941 .responseFormat(format)942 .build();943944 Interaction interaction =945 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();946 System.out.println(interaction.outputText().orElse(""));947948### REST949950 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \951 -H "x-goog-api-key: $GEMINI_API_KEY" \952 -H 'Content-Type: application/json' \953 -d '{954 "model": "gemini-3.8-flash",955 "input": "Give me a recipe for banana bread",956 "response_format": {957 "type": "text",958 "mime_type": "application/json",959 "schema": {960 "type": "object",961 "properties": {962 "recipe_name": { "type": "string", "description": "Name of the recipe." },963 "ingredients": {964 "type": "array",965 "items": { "type": "string" },966 "description": "List of ingredients."967 },968 "prep_time_minutes": {969 "type": "integer",970 "description": "Prep time in minutes."971 }972 },973 "required": ["recipe_name", "ingredients"]974 }975 }976 }'977978**Response:**979980 {981 "id": "v1_Chd...",982 "status": "completed",983 "steps": [984 {985 "type": "model_output",986 "content": [987 {988 "type": "text",989 "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}"990 }991 ]992 }993 ],994 "object": "interaction",995 "model": "gemini-3.8-flash",996 }997998The 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).9991000## 8. Use tools10011002Ground the model's response in real-time information with Google Search. The API automatically searches, processes results, and returns citations.10031004### Python10051006 from google import genai10071008 client = genai.Client()10091010 interaction = client.interactions.create(1011 model="gemini-3.8-flash",1012 input="Who won the euro 2024?",1013 tools=[{"type": "google_search"}]1014 )10151016 print(interaction.output_text)10171018 # Print citations1019 for step in interaction.steps:1020 if step.type == "model_output":1021 for content_block in step.content:1022 if content_block.type == "text" and content_block.annotations:1023 print("\nCitations:")1024 for annotation in content_block.annotations:1025 if annotation.type == "url_citation":1026 print(f" [{annotation.title}]({annotation.url})")10271028### JavaScript10291030 import { GoogleGenAI } from "@google/genai";10311032 const ai = new GoogleGenAI({});10331034 const interaction = await ai.interactions.create({1035 model: "gemini-3.8-flash",1036 input: "Who won the euro 2024?",1037 tools: [{ type: "google_search" }]1038 });10391040 console.log(interaction.output_text);10411042 // Print citations1043 for (const step of interaction.steps) {1044 if (step.type === "model_output") {1045 for (const contentBlock of step.content) {1046 if (contentBlock.type === "text" && contentBlock.annotations) {1047 console.log("\nCitations:");1048 for (const annotation of contentBlock.annotations) {1049 if (annotation.type === "url_citation") {1050 console.log(` [${annotation.title}](${annotation.url})`);1051 }1052 }1053 }1054 }1055 }1056 }10571058### Java10591060 import com.google.genai.Client;1061 import com.google.genai.gaos.models.interactions.Annotation;1062 import com.google.genai.gaos.models.interactions.Content;1063 import com.google.genai.gaos.models.interactions.CreateModelInteraction;1064 import com.google.genai.gaos.models.interactions.GoogleSearch;1065 import com.google.genai.gaos.models.interactions.Interaction;1066 import com.google.genai.gaos.models.interactions.InteractionsInput;1067 import com.google.genai.gaos.models.interactions.Model;1068 import com.google.genai.gaos.models.interactions.ModelOutputStep;1069 import com.google.genai.gaos.models.interactions.Step;1070 import com.google.genai.gaos.models.interactions.TextContent;1071 import com.google.genai.gaos.models.interactions.URLCitation;1072 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;1073 import java.util.Arrays;1074 import java.util.Collections;10751076 Client client = new Client();10771078 CreateModelInteraction params =1079 CreateModelInteraction.builder()1080 .model(Model.of("gemini-3.8-flash"))1081 .input(InteractionsInput.of("Who won the euro 2024?"))1082 .tools(Arrays.asList(new GoogleSearch()))1083 .build();10841085 Interaction interaction =1086 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();10871088 System.out.println(interaction.outputText().orElse(""));10891090 // Print citations1091 for (Step step : interaction.steps().orElse(Collections.emptyList())) {1092 if (step instanceof ModelOutputStep outputStep) {1093 for (Content contentBlock : outputStep.content().orElse(Collections.emptyList())) {1094 if (contentBlock instanceof TextContent textContent && textContent.annotations().isPresent()) {1095 System.out.println("\nCitations:");1096 for (Annotation annotation : textContent.annotations().get()) {1097 if (annotation instanceof URLCitation citation) {1098 System.out.printf(" [%s](%s)%n", citation.title().orElse(""), citation.url().orElse(""));1099 }1100 }1101 }1102 }1103 }1104 }11051106### REST11071108 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \1109 -H "x-goog-api-key: $GEMINI_API_KEY" \1110 -H 'Content-Type: application/json' \1111 -d '{1112 "model": "gemini-3.8-flash",1113 "input": "Who won the euro 2024?",1114 "tools": [{"type": "google_search"}]1115 }'11161117**Response:**11181119 {1120 "id": "v1_Chd...",1121 "status": "completed",1122 "steps": [1123 {1124 "type": "thought",1125 "signature": "EvEFCu4F..."1126 },1127 {1128 "type": "google_search_call",1129 "arguments": {1130 "queries": ["UEFA Euro 2024 winner"]1131 }1132 },1133 {1134 "type": "google_search_result",1135 "call_id": "search_001",1136 "result": [1137 {1138 "search_suggestions": "<!-- HTML and CSS search widget -->"1139 }1140 ]1141 },1142 {1143 "type": "model_output",1144 "content": [1145 {1146 "type": "text",1147 "text": "Spain won Euro 2024, defeating England 2-1 in the final.",1148 "annotations": [1149 {1150 "type": "url_citation",1151 "url": "https://www.uefa.com/euro2024",1152 "title": "uefa.com",1153 "start_index": 0,1154 "end_index": 561155 }1156 ]1157 }1158 ]1159 }1160 ],1161 "object": "interaction",1162 "model": "gemini-3.8-flash",1163 }11641165The search steps are detailed within the interaction history, and the final output includes inline citations pointing to web sources.11661167You 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).1168[Code execution1169Run Python code in a secure sandboxed Borg environment.](https://ai.google.dev/gemini-api/docs/code-execution) [URL context1170Pass public web URLs directly to ground responses in webpage content.](https://ai.google.dev/gemini-api/docs/url-context) [File search1171Index and search across uploaded documents and media files.](https://ai.google.dev/gemini-api/docs/file-search) [Google Maps1172Ground responses in real-world geospatial and location data.](https://ai.google.dev/gemini-api/docs/maps-grounding) [Computer use1173Browser automation and screen interaction.](https://ai.google.dev/gemini-api/docs/computer-use)11741175## 9. Call your own functions11761177Function 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.11781179### Stateful (recommended)11801181### Python11821183 import json1184 from google import genai11851186 client = genai.Client()11871188 weather_tool = {1189 "type": "function",1190 "name": "get_current_temperature",1191 "description": "Gets the current temperature for a given location.",1192 "parameters": {1193 "type": "object",1194 "properties": {1195 "location": {1196 "type": "string",1197 "description": "The city name, e.g. San Francisco",1198 },1199 },1200 "required": ["location"],1201 },1202 }12031204 available_functions = {1205 "get_current_temperature": lambda location: {1206 "location": location, "temperature": "22", "unit": "celsius"1207 },1208 }12091210 user_input = "What is the temperature in London?"1211 previous_id = None12121213 while True:1214 interaction = client.interactions.create(1215 model="gemini-3.8-flash",1216 input=user_input,1217 tools=[weather_tool],1218 previous_interaction_id=previous_id,1219 )12201221 function_results = []1222 for step in interaction.steps:1223 if step.type == "function_call":1224 result = available_functions[step.name](**step.arguments)1225 print(f"Called {step.name}({step.arguments}) → {result}")1226 function_results.append({1227 "type": "function_result",1228 "name": step.name,1229 "call_id": step.id,1230 "result": [{"type": "text", "text": json.dumps(result)}],1231 })12321233 if not function_results:1234 break12351236 user_input = function_results1237 previous_id = interaction.id12381239 print(interaction.output_text)12401241### JavaScript12421243 import { GoogleGenAI } from "@google/genai";12441245 const ai = new GoogleGenAI({});12461247 const weatherTool = {1248 type: "function",1249 name: "get_current_temperature",1250 description: "Gets the current temperature for a given location.",1251 parameters: {1252 type: "object",1253 properties: {1254 location: {1255 type: "string",1256 description: "The city name, e.g. San Francisco",1257 },1258 },1259 required: ["location"],1260 },1261 };12621263 const availableFunctions = {1264 get_current_temperature: ({ location }) => ({1265 location, temperature: "22", unit: "celsius"1266 }),1267 };12681269 let input = "What is the temperature in London?";1270 let previousId = null;1271 let interaction;12721273 while (true) {1274 interaction = await ai.interactions.create({1275 model: "gemini-3.8-flash",1276 input,1277 tools: [weatherTool],1278 previous_interaction_id: previousId,1279 });12801281 const functionResults = [];1282 for (const step of interaction.steps) {1283 if (step.type === "function_call") {1284 const result = availableFunctions[step.name](step.arguments);1285 console.log(`Called ${step.name}(${JSON.stringify(step.arguments)}) →`, result);1286 functionResults.push({1287 type: "function_result",1288 name: step.name,1289 call_id: step.id,1290 result: [{ type: "text", text: JSON.stringify(result) }],1291 });1292 }1293 }12941295 if (functionResults.length === 0) break;12961297 input = functionResults;1298 previousId = interaction.id;1299 }13001301 console.log(interaction.output_text);13021303### Java13041305 import com.google.genai.Client;1306 import com.google.genai.gaos.models.interactions.CreateModelInteraction;1307 import com.google.genai.gaos.models.interactions.Function;1308 import com.google.genai.gaos.models.interactions.FunctionCallStep;1309 import com.google.genai.gaos.models.interactions.FunctionResultStep;1310 import com.google.genai.gaos.models.interactions.FunctionResultStepResultUnion;1311 import com.google.genai.gaos.models.interactions.Interaction;1312 import com.google.genai.gaos.models.interactions.InteractionsInput;1313 import com.google.genai.gaos.models.interactions.Model;1314 import com.google.genai.gaos.models.interactions.Step;1315 import com.google.genai.gaos.models.interactions.TextContent;1316 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;1317 import java.util.ArrayList;1318 import java.util.Arrays;1319 import java.util.Collections;1320 import java.util.HashMap;1321 import java.util.List;1322 import java.util.Map;13231324 Client client = new Client();13251326 Map<String, Object> locationProp = new HashMap<>();1327 locationProp.put("type", "string");1328 locationProp.put("description", "The city name, e.g. San Francisco");13291330 Map<String, Object> properties = new HashMap<>();1331 properties.put("location", locationProp);13321333 Map<String, Object> parameters = new HashMap<>();1334 parameters.put("type", "object");1335 parameters.put("properties", properties);1336 parameters.put("required", Arrays.asList("location"));13371338 Function weatherTool =1339 Function.builder()1340 .name("get_current_temperature")1341 .description("Gets the current temperature for a given location.")1342 .parameters(parameters)1343 .build();13441345 InteractionsInput userInput = InteractionsInput.of("What is the temperature in London?");1346 String previousId = null;1347 Interaction interaction = null;13481349 while (true) {1350 CreateModelInteraction.Builder paramsBuilder =1351 CreateModelInteraction.builder()1352 .model(Model.of("gemini-3.8-flash"))1353 .input(userInput)1354 .tools(Arrays.asList(weatherTool));1355 if (previousId != null) {1356 paramsBuilder.previousInteractionId(previousId);1357 }13581359 interaction =1360 client.interactions.create(CreateInteractionRequestBody.of(paramsBuilder.build())).interaction().get();13611362 List<Step> functionResults = new ArrayList<>();1363 for (Step step : interaction.steps().orElse(Collections.emptyList())) {1364 if (step instanceof FunctionCallStep fcStep) {1365 String resultJson = "{\"location\": \"London\", \"temperature\": \"22\", \"unit\": \"celsius\"}";1366 System.out.printf(1367 "Called %s(%s) -> %s%n",1368 fcStep.name().orElse(""), fcStep.arguments().orElse(Collections.emptyMap()), resultJson);1369 functionResults.add(1370 FunctionResultStep.builder()1371 .name(fcStep.name().orElse(""))1372 .callId(fcStep.id().orElse(""))1373 .result(1374 FunctionResultStepResultUnion.of(1375 Arrays.asList(TextContent.builder().text(resultJson).build())))1376 .build());1377 }1378 }13791380 if (functionResults.isEmpty()) {1381 break;1382 }13831384 userInput = InteractionsInput.ofStep(functionResults);1385 previousId = interaction.id().orElse(null);1386 }13871388 System.out.println(interaction.outputText().orElse(""));13891390### REST13911392 # Turn 1: Send prompt with function declaration1393 RESPONSE1=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \1394 -H "x-goog-api-key: $GEMINI_API_KEY" \1395 -H 'Content-Type: application/json' \1396 -d '{1397 "model": "gemini-3.8-flash",1398 "input": "What is the temperature in London?",1399 "tools": [{1400 "type": "function",1401 "name": "get_current_temperature",1402 "description": "Gets the current temperature for a given location.",1403 "parameters": {1404 "type": "object",1405 "properties": {1406 "location": {"type": "string", "description": "The city name"}1407 },1408 "required": ["location"]1409 }1410 }]1411 }')14121413 INTERACTION_ID=$(echo "$RESPONSE1" | jq -r '.id')1414 FC_NAME=$(echo "$RESPONSE1" | jq -r '.steps[] | select(.type=="function_call") | .name')1415 FC_ID=$(echo "$RESPONSE1" | jq -r '.steps[] | select(.type=="function_call") | .id')1416 echo "Function: $FC_NAME, Call ID: $FC_ID"14171418 # Turn 2: Send function result back1419 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \1420 -H "x-goog-api-key: $GEMINI_API_KEY" \1421 -H 'Content-Type: application/json' \1422 -d '{1423 "model": "gemini-3.8-flash",1424 "previous_interaction_id": "'$INTERACTION_ID'",1425 "input": [{1426 "type": "function_result",1427 "name": "'$FC_NAME'",1428 "call_id": "'$FC_ID'",1429 "result": [{"type": "text", "text": "{\"location\": \"London\", \"temperature\": \"22\", \"unit\": \"celsius\"}"}]1430 }],1431 "tools": [{1432 "type": "function",1433 "name": "get_current_temperature",1434 "description": "Gets the current temperature for a given location.",1435 "parameters": {1436 "type": "object",1437 "properties": {1438 "location": {"type": "string", "description": "The city name"}1439 },1440 "required": ["location"]1441 }1442 }]1443 }'14441445### Stateless14461447You 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:144814491. The initial `user_input` step.14502. All model-generated steps returned in Turn 1 (including `thought` and `function_call` steps) exactly as received.14513. The `function_result` step containing the output of your executed function.14521453### Python14541455 import json1456 from google import genai14571458 client = genai.Client()14591460 weather_tool = {1461 "type": "function",1462 "name": "get_current_temperature",1463 "description": "Gets the current temperature for a given location.",1464 "parameters": {1465 "type": "object",1466 "properties": {1467 "location": {1468 "type": "string",1469 "description": "The city name, e.g. San Francisco",1470 },1471 },1472 "required": ["location"],1473 },1474 }14751476 available_functions = {1477 "get_current_temperature": lambda location: {1478 "location": location, "temperature": "22", "unit": "celsius"1479 },1480 }14811482 history = [1483 {1484 "type": "user_input",1485 "content": [{"type": "text", "text": "What is the temperature in London?"}]1486 }1487 ]14881489 while True:1490 interaction = client.interactions.create(1491 model="gemini-3.8-flash",1492 store=False,1493 input=history,1494 tools=[weather_tool],1495 )14961497 function_results = []1498 for step in interaction.steps:1499 history.append(step.model_dump())1500 if step.type == "function_call":1501 result = available_functions[step.name](**step.arguments)1502 print(f"Called {step.name}({step.arguments}) → {result}")1503 fn_result = {1504 "type": "function_result",1505 "name": step.name,1506 "call_id": step.id,1507 "result": [{"type": "text", "text": json.dumps(result)}],1508 }1509 function_results.append(fn_result)1510 history.append(fn_result)15111512 if not function_results:1513 break15141515 print(interaction.output_text)15161517### JavaScript15181519 import { GoogleGenAI } from "@google/genai";15201521 const ai = new GoogleGenAI({});15221523 const weatherTool = {1524 type: "function",1525 name: "get_current_temperature",1526 description: "Gets the current temperature for a given location.",1527 parameters: {1528 type: "object",1529 properties: {1530 location: {1531 type: "string",1532 description: "The city name, e.g. San Francisco",1533 },1534 },1535 required: ["location"],1536 },1537 };15381539 const availableFunctions = {1540 get_current_temperature: ({ location }) => ({1541 location, temperature: "22", unit: "celsius"1542 }),1543 };15441545 const history = [1546 {1547 type: "user_input",1548 content: [{ type: "text", text: "What is the temperature in London?" }]1549 }1550 ];15511552 let interaction;15531554 while (true) {1555 interaction = await ai.interactions.create({1556 model: "gemini-3.8-flash",1557 store: false,1558 input: history,1559 tools: [weatherTool],1560 });15611562 const functionResults = [];1563 for (const step of interaction.steps) {1564 history.push(step);1565 if (step.type === "function_call") {1566 const result = availableFunctions[step.name](step.arguments);1567 console.log(`Called ${step.name}(${JSON.stringify(step.arguments)}) →`, result);1568 const fnResult = {1569 type: "function_result",1570 name: step.name,1571 call_id: step.id,1572 result: [{ type: "text", text: JSON.stringify(result) }],1573 };1574 functionResults.push(fnResult);1575 history.push(fnResult);1576 }1577 }15781579 if (functionResults.length === 0) break;1580 }15811582 console.log(interaction.output_text);15831584### Java15851586 import com.google.genai.Client;1587 import com.google.genai.gaos.models.interactions.CreateModelInteraction;1588 import com.google.genai.gaos.models.interactions.Function;1589 import com.google.genai.gaos.models.interactions.FunctionCallStep;1590 import com.google.genai.gaos.models.interactions.FunctionResultStep;1591 import com.google.genai.gaos.models.interactions.FunctionResultStepResultUnion;1592 import com.google.genai.gaos.models.interactions.Interaction;1593 import com.google.genai.gaos.models.interactions.InteractionsInput;1594 import com.google.genai.gaos.models.interactions.Model;1595 import com.google.genai.gaos.models.interactions.Step;1596 import com.google.genai.gaos.models.interactions.TextContent;1597 import com.google.genai.gaos.models.interactions.UserInputStep;1598 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;1599 import java.util.ArrayList;1600 import java.util.Arrays;1601 import java.util.Collections;1602 import java.util.HashMap;1603 import java.util.List;1604 import java.util.Map;16051606 Client client = new Client();16071608 Map<String, Object> locationProp = new HashMap<>();1609 locationProp.put("type", "string");1610 locationProp.put("description", "The city name, e.g. San Francisco");16111612 Map<String, Object> properties = new HashMap<>();1613 properties.put("location", locationProp);16141615 Map<String, Object> parameters = new HashMap<>();1616 parameters.put("type", "object");1617 parameters.put("properties", properties);1618 parameters.put("required", Arrays.asList("location"));16191620 Function weatherTool =1621 Function.builder()1622 .name("get_current_temperature")1623 .description("Gets the current temperature for a given location.")1624 .parameters(parameters)1625 .build();16261627 List<Step> history = new ArrayList<>();1628 history.add(1629 UserInputStep.builder()1630 .content(Arrays.asList(TextContent.builder().text("What is the temperature in London?").build()))1631 .build());16321633 Interaction interaction = null;16341635 while (true) {1636 CreateModelInteraction params =1637 CreateModelInteraction.builder()1638 .model(Model.of("gemini-3.8-flash"))1639 .store(false)1640 .input(InteractionsInput.ofStep(history))1641 .tools(Arrays.asList(weatherTool))1642 .build();16431644 interaction =1645 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();16461647 List<Step> functionResults = new ArrayList<>();1648 for (Step step : interaction.steps().orElse(Collections.emptyList())) {1649 history.add(step);1650 if (step instanceof FunctionCallStep fcStep) {1651 String resultJson = "{\"location\": \"London\", \"temperature\": \"22\", \"unit\": \"celsius\"}";1652 System.out.printf(1653 "Called %s(%s) -> %s%n",1654 fcStep.name().orElse(""), fcStep.arguments().orElse(Collections.emptyMap()), resultJson);1655 FunctionResultStep fnResult =1656 FunctionResultStep.builder()1657 .name(fcStep.name().orElse(""))1658 .callId(fcStep.id().orElse(""))1659 .result(1660 FunctionResultStepResultUnion.of(1661 Arrays.asList(TextContent.builder().text(resultJson).build())))1662 .build();1663 functionResults.add(fnResult);1664 history.add(fnResult);1665 }1666 }16671668 if (functionResults.isEmpty()) {1669 break;1670 }1671 }16721673 System.out.println(interaction.outputText().orElse(""));16741675### REST16761677 # Turn 1: Send request with tools and store: false1678 RESPONSE1=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \1679 -H "x-goog-api-key: $GEMINI_API_KEY" \1680 -H 'Content-Type: application/json' \1681 -d '{1682 "model": "gemini-3.8-flash",1683 "store": false,1684 "input": [1685 {1686 "type": "user_input",1687 "content": "What is the temperature in London?"1688 }1689 ],1690 "tools": [{1691 "type": "function",1692 "name": "get_current_temperature",1693 "description": "Gets the current temperature for a given location.",1694 "parameters": {1695 "type": "object",1696 "properties": {1697 "location": {"type": "string", "description": "The city name"}1698 },1699 "required": ["location"]1700 }1701 }]1702 }')17031704 # Extract model steps (thought, function_call)1705 MODEL_STEPS=$(echo "$RESPONSE1" | jq '.steps')1706 FC_NAME=$(echo "$RESPONSE1" | jq -r '.steps[] | select(.type=="function_call") | .name')1707 FC_ID=$(echo "$RESPONSE1" | jq -r '.steps[] | select(.type=="function_call") | .id')1708 echo "Function: $FC_NAME, Call ID: $FC_ID"17091710 # Assume local execution returns:1711 RESULT="{\"location\": \"London\", \"temperature\": \"22\", \"unit\": \"celsius\"}"17121713 # Reconstruct history for Turn 21714 HISTORY=$(jq -n \1715 --argjson first_input '[{"type": "user_input", "content": "What is the temperature in London?"}]' \1716 --argjson model_steps "$MODEL_STEPS" \1717 --arg fc_name "$FC_NAME" \1718 --arg fc_id "$FC_ID" \1719 --arg result "$RESULT" \1720 '$first_input + $model_steps + [{"type": "function_result", "name": $fc_name, "call_id": $fc_id, "result": [{"type": "text", "text": $result}]}]')17211722 # Turn 2: Send the full history1723 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \1724 -H "x-goog-api-key: $GEMINI_API_KEY" \1725 -H 'Content-Type: application/json' \1726 -d "{1727 \"model\": \"gemini-3.8-flash\",1728 \"store\": false,1729 \"input\": $HISTORY,1730 \"tools\": [{1731 \"type\": \"function\",1732 \"name\": \"get_current_temperature\",1733 \"description\": \"Gets the current temperature for a given location.\",1734 \"parameters\": {1735 \"type\": \"object\",1736 \"properties\": {1737 \"location\": {\"type\": \"string\", \"description\": \"The city name\"}1738 },1739 \"required\": [\"location\"]1740 }1741 }]1742 }"17431744**Response:**17451746During Turn 1, the model returns a response with status `requires_action` and the `function_call` step:17471748 {1749 "id": "v1_Chd...",1750 "status": "requires_action",1751 "steps": [1752 {1753 "type": "function_call",1754 "id": "call_abc123",1755 "name": "get_current_temperature",1756 "arguments": {1757 "location": "London"1758 }1759 }1760 ],1761 "object": "interaction",1762 "model": "gemini-3.8-flash"1763 }17641765After you run the function locally and submit the result (Turn 2), the final completed interaction returns:17661767 {1768 "id": "v1_Chd...",1769 "status": "completed",1770 "steps": [1771 {1772 "type": "function_call",1773 "id": "call_abc123",1774 "name": "get_current_temperature",1775 "arguments": {1776 "location": "London"1777 }1778 },1779 {1780 "type": "model_output",1781 "content": [1782 {1783 "type": "text",1784 "text": "The temperature in London is currently 22°C."1785 }1786 ]1787 }1788 ],1789 "object": "interaction",1790 "model": "gemini-3.8-flash",1791 }17921793For advanced features like parallel function calling or function choice modes, see the [function calling guide](https://ai.google.dev/gemini-api/docs/function-calling).17941795## 10. Run a managed agent17961797Managed 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"`.17981799### Python18001801 from google import genai18021803 client = genai.Client()18041805 interaction = client.interactions.create(1806 agent="antigravity-preview-09-2026",1807 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.",1808 environment="remote",1809 )1810 print(f"Environment: {interaction.environment_id}")1811 print(interaction.output_text)18121813### JavaScript18141815 import { GoogleGenAI } from "@google/genai";18161817 const ai = new GoogleGenAI({});18181819 const interaction = await ai.interactions.create({1820 agent: "antigravity-preview-09-2026",1821 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.",1822 environment: "remote",1823 });1824 console.log(`Environment: ${interaction.environment_id}`);1825 console.log(interaction.output_text);18261827### Java18281829 import com.google.genai.Client;1830 import com.google.genai.gaos.models.interactions.CreateAgentInteraction;1831 import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;1832 import com.google.genai.gaos.models.interactions.Interaction;1833 import com.google.genai.gaos.models.interactions.InteractionsInput;1834 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;18351836 Client client = new Client();18371838 CreateAgentInteraction params =1839 CreateAgentInteraction.builder()1840 .agent("antigravity-preview-09-2026")1841 .input(1842 InteractionsInput.of(1843 "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."))1844 .environment(CreateAgentInteractionEnvironment.of("remote"))1845 .build();18461847 Interaction interaction =1848 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();1849 System.out.println("Environment: " + interaction.environmentId().orElse(""));1850 System.out.println(interaction.outputText().orElse(""));18511852### REST18531854 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \1855 -H "x-goog-api-key: $GEMINI_API_KEY" \1856 -H 'Content-Type: application/json' \1857 -d '{1858 "agent": "antigravity-preview-09-2026",1859 "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.",1860 "environment": "remote"1861 }'18621863You can also define and save [custom agents](https://ai.google.dev/gemini-api/docs/custom-agents) with your own instructions, skills, and data sources.1864[Quickstart1865Make your first agent call, stream responses, and build a custom agent.](https://ai.google.dev/gemini-api/docs/managed-agents-quickstart) [Antigravity Agent1866Capabilities, tools, multimodal input, and pricing for the default agent.](https://ai.google.dev/gemini-api/docs/antigravity-agent) [Agents in AI Studio1867Visual playground for prototyping agents without writing code.](https://ai.google.dev/gemini-api/docs/aistudio-agents)18681869## 11. Run tasks in the background18701871Set `background=True` to run long tasks asynchronously. Poll for results with `interactions.get()`. For more details, see the [Background execution guide](https://ai.google.dev/gemini-api/docs/background-execution).18721873### Python18741875 import time1876 from google import genai18771878 client = genai.Client()18791880 interaction = client.interactions.create(1881 model="gemini-3.8-flash",1882 input="Write a detailed analysis of the impact of artificial intelligence on modern healthcare.",1883 background=True,1884 )1885 print(f"Started background task: {interaction.id}")1886 print(f"Status: {interaction.status}")18871888 # Poll for completion1889 while True:1890 result = client.interactions.get(interaction.id)1891 print(f"Status: {result.status}")1892 if result.status == "completed":1893 print(f"\nResult:\n{result.output_text}")1894 break1895 elif result.status == "failed":1896 print(f"Failed: {result.error}")1897 break1898 time.sleep(5)18991900### JavaScript19011902 import { GoogleGenAI } from "@google/genai";19031904 const ai = new GoogleGenAI({});19051906 const interaction = await ai.interactions.create({1907 model: "gemini-3.8-flash",1908 input: "Write a detailed analysis of the impact of artificial intelligence on modern healthcare.",1909 background: true,1910 });1911 console.log(`Started background task: ${interaction.id}`);1912 console.log(`Status: ${interaction.status}`);19131914 // Poll for completion1915 while (true) {1916 const result = await ai.interactions.get(interaction.id);1917 console.log(`Status: ${result.status}`);1918 if (result.status === "completed") {1919 console.log(`\nResult:\n${result.output_text}`);1920 break;1921 } else if (result.status === "failed") {1922 console.log(`Failed: ${result.error}`);1923 break;1924 }1925 await new Promise(r => setTimeout(r, 5000));1926 }19271928### Java19291930 import com.google.genai.Client;1931 import com.google.genai.gaos.models.interactions.CreateModelInteraction;1932 import com.google.genai.gaos.models.interactions.Interaction;1933 import com.google.genai.gaos.models.interactions.InteractionStatus;1934 import com.google.genai.gaos.models.interactions.InteractionsInput;1935 import com.google.genai.gaos.models.interactions.Model;1936 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;1937 import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;19381939 Client client = new Client();19401941 CreateModelInteraction params =1942 CreateModelInteraction.builder()1943 .model(Model.of("gemini-3.8-flash"))1944 .input(1945 InteractionsInput.of(1946 "Write a detailed analysis of the impact of artificial intelligence on modern healthcare."))1947 .background(true)1948 .build();19491950 Interaction interaction =1951 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();1952 String interactionId = interaction.id().orElse("");1953 System.out.println("Started background task: " + interactionId);1954 System.out.println("Status: " + interaction.status().map(InteractionStatus::value).orElse(""));19551956 // Poll for completion1957 while (true) {1958 Interaction result =1959 client.interactions.get(new GetInteractionByIdRequest(interactionId)).interaction().get();1960 String status = result.status().map(InteractionStatus::value).orElse("");1961 System.out.println("Status: " + status);1962 if ("completed".equals(status)) {1963 System.out.println("\nResult:\n" + result.outputText().orElse(""));1964 break;1965 } else if ("failed".equals(status)) {1966 System.out.println("Failed: " + result.errors().orElse(null));1967 break;1968 }1969 Thread.sleep(5000);1970 }19711972### REST19731974 # Start a background task1975 RESPONSE=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \1976 -H "x-goog-api-key: $GEMINI_API_KEY" \1977 -H 'Content-Type: application/json' \1978 -d '{1979 "model": "gemini-3.8-flash",1980 "input": "Write a detailed analysis of the impact of artificial intelligence on modern healthcare.",1981 "background": true1982 }')19831984 INTERACTION_ID=$(echo "$RESPONSE" | jq -r '.id')1985 echo "Started background task: $INTERACTION_ID"19861987 # Poll for completion1988 while true; do1989 RESULT=$(curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/$INTERACTION_ID" \1990 -H "x-goog-api-key: $GEMINI_API_KEY" \1991 -H "Api-Revision: 2026-05-20")1992 STATUS=$(echo "$RESULT" | jq -r '.status')1993 echo "Status: $STATUS"1994 if [ "$STATUS" = "completed" ]; then1995 echo "$RESULT" | jq -r '.steps[] | select(.type=="model_output") | .content[] | select(.type=="text") | .text'1996 break1997 elif [ "$STATUS" = "failed" ]; then1998 echo "Failed"1999 break2000 fi2001 sleep 52002 done20032004**Response:**20052006The initial response returns immediately with status `in_progress`:20072008 {2009 "id": "v1_abc123",2010 "status": "in_progress",2011 "object": "interaction",2012 "model": "gemini-3.8-flash"2013 }20142015Once the background task is fully executed, checking the interaction state returns:20162017 {2018 "id": "v1_abc123",2019 "status": "completed",2020 "steps": [2021 {2022 "type": "model_output",2023 "content": [2024 {2025 "type": "text",2026 "text": "Artificial intelligence has transformed modern healthcare in several..."2027 }2028 ]2029 }2030 ],2031 "object": "interaction",2032 "model": "gemini-3.8-flash",2033 }20342035Read about running models and agents asynchronously in the [background execution guide](https://ai.google.dev/gemini-api/docs/background-execution).20362037## What's next20382039- [Background execution](https://ai.google.dev/gemini-api/docs/background-execution): Run long-running tasks asynchronously and manage state.2040- [Text generation](https://ai.google.dev/gemini-api/docs/text-generation): System instructions, generation config, and advanced text patterns.2041- [Image generation](https://ai.google.dev/gemini-api/docs/image-generation): Aspect ratios, image editing, and style references.2042- [Image understanding](https://ai.google.dev/gemini-api/docs/image-understanding): Classification, object detection, and visual Q\&A.2043- [Thinking](https://ai.google.dev/gemini-api/docs/thinking): Use chain-of-thought reasoning for complex tasks.2044- [Function calling](https://ai.google.dev/gemini-api/docs/function-calling): Parallel, compositional, and constrained function modes.2045- [Google Search](https://ai.google.dev/gemini-api/docs/google-search): Grounding, citations, and search suggestions.2046- [Managed Agents](https://ai.google.dev/gemini-api/docs/managed-agents-quickstart): Pre-built agents with code execution and file management.2047- [Deep Research](https://ai.google.dev/gemini-api/docs/deep-research): Autonomous multi-step research with planning and synthesis.2048- [Structured output](https://ai.google.dev/gemini-api/docs/structured-output): JSON schemas, enums, and recursive type definitions.