{ "@context": "https://schema.org", "@id": "https://aggr.aymericbeaumet.com/items/philschmid-de/2026-06-23-getting-started-with-the-gemini-interactions-api/#webpage", "@type": [ "WebPage", "ArchiveComponent" ], "articleBody": "The [Interactions API](https://ai.google.dev/gemini-api/docs/interactions) is Google's primary interface for Gemini models and agents. A single endpoint covers text generation, streaming, multi-turn chat, multimodal inputs, image generation, structured output, tool use, function calling, managed agents, and background execution.\n\nThis guide uses JavaScript. For Python and REST examples, see the [Interactions API quickstart](https://ai.google.dev/gemini-api/docs/interactions/quickstart).\n\n**Using a coding agent?** Install the skill so your agent stays current with Interactions API patterns:\n\nShell\n\n```shell\nnpx skills add google-gemini/gemini-skills --skill gemini-interactions-api\n```\n\n## Setup\n\nCreate a free API key at [Google AI Studio](https://aistudio.google.com/apikey), then set it as an environment variable:\n\nShell\n\n```shell\nexport GEMINI_API_KEY=\"YOUR_API_KEY\"\n```\n\nInstall the SDK:\n\nShell\n\n```shell\nnpm install @google/genai\n```\n\nSend your first request.\n\nJavaScript\n\n```javascript\nimport { GoogleGenAI } from \"@google/genai\";\n \nconst ai = new GoogleGenAI({});\n \nconst interaction = await ai.interactions.create({\n model: \"gemini-3.5-flash\",\n input: \"Explain how AI works in a few words\",\n});\nconsole.log(interaction.output_text);\n```\n\n`interaction.output_text` gives you the final text directly. See the [text generation guide](https://ai.google.dev/gemini-api/docs/interactions/text-generation) for system instructions and generation config.\n\n## Streaming\n\nAdd `stream: true` and iterate over events. Each `step.delta` with `type === \"text\"` is a chunk you can display immediately.\n\nJavaScript\n\n```javascript\nimport { GoogleGenAI } from \"@google/genai\";\n \nconst ai = new GoogleGenAI({});\n \nconst stream = await ai.interactions.create({\n model: \"gemini-3.5-flash\",\n input: \"Explain how AI works\",\n stream: true,\n});\n \nfor await (const event of stream) {\n if (event.event_type === \"step.delta\") {\n if (event.delta.type === \"text\") {\n process.stdout.write(event.delta.text);\n }\n }\n}\n```\n\nSee the [streaming guide](https://ai.google.dev/gemini-api/docs/interactions/streaming) for event types and delta handling.\n\n## Multi-turn conversations\n\nChain interactions by passing `previous_interaction_id`. The server manages history for you.\n\nJavaScript\n\n```javascript\nimport { GoogleGenAI } from \"@google/genai\";\n \nconst ai = new GoogleGenAI({});\n \nconst interaction1 = await ai.interactions.create({\n model: \"gemini-3.5-flash\",\n input: \"I have 2 dogs in my house.\",\n});\nconsole.log(\"Response 1:\", interaction1.output_text);\n \nconst interaction2 = await ai.interactions.create({\n model: \"gemini-3.5-flash\",\n input: \"How many paws are in my house?\",\n previous_interaction_id: interaction1.id,\n});\nconsole.log(\"Response 2:\", interaction2.output_text);\n```\n\nFor client-side history management, set `store: false`. See the [multi-turn guide](https://ai.google.dev/gemini-api/docs/interactions/text-generation#multi-turn-conversations).\n\n## Multimodal understanding\n\nGemini natively understands images, audio, video, and documents. Upload a file and pass it alongside text.\n\nJavaScript\n\n```javascript\nimport { GoogleGenAI } from \"@google/genai\";\n \nconst ai = new GoogleGenAI({});\n \nconst uploadedFile = await ai.files.upload({ file: \"photo.jpg\" });\n \nconst interaction = await ai.interactions.create({\n model: \"gemini-3.5-flash\",\n input: [\n { type: \"text\", text: \"What is in this image?\" },\n {\n type: \"image\",\n uri: uploadedFile.uri,\n mime_type: uploadedFile.mimeType,\n },\n ],\n});\nconsole.log(interaction.output_text);\n```\n\nAudio, video, and documents use the same structure. See the guides for [audio](https://ai.google.dev/gemini-api/docs/interactions/audio), [video](https://ai.google.dev/gemini-api/docs/interactions/video-understanding), and [document processing](https://ai.google.dev/gemini-api/docs/interactions/document-processing).\n\n## Image generation\n\nGenerate images with Nano Banana 2 using the `gemini-3.1-flash-image` model.\n\nJavaScript\n\n```javascript\nimport { GoogleGenAI } from \"@google/genai\";\nimport fs from \"node:fs\";\n \nconst ai = new GoogleGenAI({});\n \nconst interaction = await ai.interactions.create({\n model: \"gemini-3.1-flash-image\",\n input: \"Generate an image of a futuristic city skyline at sunset\",\n});\n \nfs.writeFileSync(\n \"generated_image.png\",\n Buffer.from(interaction.output_image.data, \"base64\")\n);\n```\n\n[Speech generation](https://ai.google.dev/gemini-api/docs/interactions/speech-generation) (multi-speaker TTS) and [music generation](https://ai.google.dev/gemini-api/docs/interactions/music-generation) (Lyria 3) work the same way. See the [image generation guide](https://ai.google.dev/gemini-api/docs/interactions/image-generation) for editing, aspect ratios, and style references.\n\n## Structured output\n\nGet JSON that matches a schema you define. Works with [Zod](https://zod.dev/).\n\nJavaScript\n\n```javascript\nimport { GoogleGenAI } from \"@google/genai\";\nimport * as z from \"zod\";\n \nconst ai = new GoogleGenAI({});\n \nconst recipeJsonSchema = {\n type: \"object\",\n properties: {\n recipe_name: { type: \"string\", description: \"Name of the recipe.\" },\n ingredients: {\n type: \"array\", items: { type: \"string\" }, description: \"List of ingredients.\"\n },\n prep_time_minutes: { type: \"integer\", description: \"Prep time in minutes.\" }\n },\n required: [\"recipe_name\", \"ingredients\"]\n};\n \nconst recipeSchema = z.fromJSONSchema(recipeJsonSchema);\n \nconst interaction = await ai.interactions.create({\n model: \"gemini-3.5-flash\",\n input: \"Give me a recipe for banana bread\",\n response_format: {\n type: \"text\",\n mime_type: \"application/json\",\n schema: recipeJsonSchema\n },\n});\n \nconst recipe = recipeSchema.parse(JSON.parse(interaction.output_text));\nconsole.log(recipe);\n```\n\nSee the [structured output guide](https://ai.google.dev/gemini-api/docs/interactions/structured-output) for recursive schemas and enums.\n\n## Tools (Google Search)\n\nGround responses in real-time data by passing `tools: [{ type: \"google_search\" }]`.\n\nJavaScript\n\n```javascript\nimport { GoogleGenAI } from \"@google/genai\";\n \nconst ai = new GoogleGenAI({});\n \nconst interaction = await ai.interactions.create({\n model: \"gemini-3.5-flash\",\n input: \"Who won the euro 2024?\",\n tools: [{ type: \"google_search\" }],\n});\nconsole.log(interaction.output_text);\n```\n\nOther built-in tools: [Code Execution](https://ai.google.dev/gemini-api/docs/interactions/code-execution), [URL Context](https://ai.google.dev/gemini-api/docs/interactions/url-context), [File Search](https://ai.google.dev/gemini-api/docs/interactions/file-search), [Google Maps](https://ai.google.dev/gemini-api/docs/interactions/maps-grounding), [Computer Use](https://ai.google.dev/gemini-api/docs/interactions/computer-use). Mix multiple tools in one request. See the [tool combination guide](https://ai.google.dev/gemini-api/docs/interactions/tool-combination).\n\n## Function calling\n\nDeclare functions, let the model decide when to call them, execute locally, and return results.\n\nJavaScript\n\n```javascript\nimport { GoogleGenAI } from \"@google/genai\";\n \nconst ai = new GoogleGenAI({});\n \nconst weatherTool = {\n type: \"function\",\n name: \"get_current_temperature\",\n description: \"Gets the current temperature for a given location.\",\n parameters: {\n type: \"object\",\n properties: {\n location: {\n type: \"string\",\n description: \"The city name, e.g. San Francisco\",\n },\n },\n required: [\"location\"],\n },\n};\n \nconst availableFunctions = {\n get_current_temperature: ({ location }) => ({\n location, temperature: \"22\", unit: \"celsius\"\n }),\n};\n \nlet input = \"What is the temperature in London?\";\nlet previousId = null;\nlet interaction;\n \nwhile (true) {\n interaction = await ai.interactions.create({\n model: \"gemini-3.5-flash\",\n input,\n tools: [weatherTool],\n previous_interaction_id: previousId,\n });\n \n const functionResults = [];\n for (const step of interaction.steps) {\n if (step.type === \"function_call\") {\n const result = availableFunctions[step.name](step.arguments);\n console.log(`Called ${step.name}(${JSON.stringify(step.arguments)}) →`, result);\n functionResults.push({\n type: \"function_result\",\n name: step.name,\n call_id: step.id,\n result: [{ type: \"text\", text: JSON.stringify(result) }],\n });\n }\n }\n \n if (functionResults.length === 0) break;\n \n input = functionResults;\n previousId = interaction.id;\n}\n \nconsole.log(interaction.output_text);\n```\n\nThe model returns `status: \"requires_action\"` with `function_call` steps. You execute locally and submit `function_result` steps back. See the [function calling guide](https://ai.google.dev/gemini-api/docs/interactions/function-calling) for parallel calls and function choice modes.\n\n## Managed agents\n\nRun an agent in a remote sandbox with code execution, web browsing, and file management. Pass `agent` instead of `model` and set `environment: \"remote\"`.\n\nJavaScript\n\n```javascript\nimport { GoogleGenAI } from \"@google/genai\";\n \nconst ai = new GoogleGenAI({});\n \nconst interaction = await ai.interactions.create({\n agent: \"antigravity-preview-05-2026\",\n input: \"Write a script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt.\",\n environment: \"remote\",\n});\nconsole.log(interaction.output_text);\n```\n\nDefine [custom agents](https://ai.google.dev/gemini-api/docs/custom-agents) with your own instructions, skills, and data sources. See the [Managed Agents quickstart](https://ai.google.dev/gemini-api/docs/managed-agents-quickstart).\n\n## Background execution\n\nSet `background: true` for long-running tasks. The call returns immediately and you poll for results.\n\nJavaScript\n\n```javascript\nimport { GoogleGenAI } from \"@google/genai\";\n \nconst ai = new GoogleGenAI({});\n \nconst interaction = await ai.interactions.create({\n model: \"gemini-3.5-flash\",\n input: \"Write a detailed analysis of AI in healthcare.\",\n background: true,\n});\nconsole.log(`Task started: ${interaction.id} (status: ${interaction.status})`);\n \nconst poll = setInterval(async () => {\n const result = await ai.interactions.get(interaction.id);\n if (result.status === \"completed\") {\n console.log(result.output_text);\n clearInterval(poll);\n } else if (result.status === \"failed\") {\n console.error(\"Failed:\", result.error);\n clearInterval(poll);\n }\n}, 5000);\n```\n\nSee the [background execution guide](https://ai.google.dev/gemini-api/docs/interactions/interactions-overview#background-execution).\n\n* * *\n\nThanks for reading! If you have any questions, feel free to contact me on [Twitter](https://twitter.com/_philschmid) or [LinkedIn](https://www.linkedin.com/in/philipp-schmid-a6a2bb196/).\n", "authors": [], "captured_at": "2026-09-27T19:29:15.293681927+00:00", "category": "programming", "content_html": "

The Interactions API is Google's primary interface for Gemini models and agents. A single endpoint covers text generation, streaming, multi-turn chat, multimodal inputs, image generation, structured output, tool use, function calling, managed agents, and background execution.

\n

This guide uses JavaScript. For Python and REST examples, see the Interactions API quickstart.

\n

Using a coding agent? Install the skill so your agent stays current with Interactions API patterns:

\n

Shell

\n
npx skills add google-gemini/gemini-skills --skill gemini-interactions-api\n
\n

Setup

\n

Create a free API key at Google AI Studio, then set it as an environment variable:

\n

Shell

\n
export GEMINI_API_KEY="YOUR_API_KEY"\n
\n

Install the SDK:

\n

Shell

\n
npm install @google/genai\n
\n

Send your first request.

\n

JavaScript

\n
import { GoogleGenAI } from "@google/genai";\n \nconst ai = new GoogleGenAI({});\n \nconst interaction = await ai.interactions.create({\n  model: "gemini-3.5-flash",\n  input: "Explain how AI works in a few words",\n});\nconsole.log(interaction.output_text);\n
\n

interaction.output_text gives you the final text directly. See the text generation guide for system instructions and generation config.

\n

Streaming

\n

Add stream: true and iterate over events. Each step.delta with type === "text" is a chunk you can display immediately.

\n

JavaScript

\n
import { GoogleGenAI } from "@google/genai";\n \nconst ai = new GoogleGenAI({});\n \nconst stream = await ai.interactions.create({\n  model: "gemini-3.5-flash",\n  input: "Explain how AI works",\n  stream: true,\n});\n \nfor await (const event of stream) {\n  if (event.event_type === "step.delta") {\n    if (event.delta.type === "text") {\n      process.stdout.write(event.delta.text);\n    }\n  }\n}\n
\n

See the streaming guide for event types and delta handling.

\n

Multi-turn conversations

\n

Chain interactions by passing previous_interaction_id. The server manages history for you.

\n

JavaScript

\n
import { GoogleGenAI } from "@google/genai";\n \nconst ai = new GoogleGenAI({});\n \nconst interaction1 = await ai.interactions.create({\n  model: "gemini-3.5-flash",\n  input: "I have 2 dogs in my house.",\n});\nconsole.log("Response 1:", interaction1.output_text);\n \nconst interaction2 = await ai.interactions.create({\n  model: "gemini-3.5-flash",\n  input: "How many paws are in my house?",\n  previous_interaction_id: interaction1.id,\n});\nconsole.log("Response 2:", interaction2.output_text);\n
\n

For client-side history management, set store: false. See the multi-turn guide.

\n

Multimodal understanding

\n

Gemini natively understands images, audio, video, and documents. Upload a file and pass it alongside text.

\n

JavaScript

\n
import { GoogleGenAI } from "@google/genai";\n \nconst ai = new GoogleGenAI({});\n \nconst uploadedFile = await ai.files.upload({ file: "photo.jpg" });\n \nconst interaction = await ai.interactions.create({\n  model: "gemini-3.5-flash",\n  input: [\n    { type: "text", text: "What is in this image?" },\n    {\n      type: "image",\n      uri: uploadedFile.uri,\n      mime_type: uploadedFile.mimeType,\n    },\n  ],\n});\nconsole.log(interaction.output_text);\n
\n

Audio, video, and documents use the same structure. See the guides for audio, video, and document processing.

\n

Image generation

\n

Generate images with Nano Banana 2 using the gemini-3.1-flash-image model.

\n

JavaScript

\n
import { GoogleGenAI } from "@google/genai";\nimport fs from "node:fs";\n \nconst ai = new GoogleGenAI({});\n \nconst interaction = await ai.interactions.create({\n  model: "gemini-3.1-flash-image",\n  input: "Generate an image of a futuristic city skyline at sunset",\n});\n \nfs.writeFileSync(\n  "generated_image.png",\n  Buffer.from(interaction.output_image.data, "base64")\n);\n
\n

Speech generation (multi-speaker TTS) and music generation (Lyria 3) work the same way. See the image generation guide for editing, aspect ratios, and style references.

\n

Structured output

\n

Get JSON that matches a schema you define. Works with Zod.

\n

JavaScript

\n
import { GoogleGenAI } from "@google/genai";\nimport * as z from "zod";\n \nconst ai = new GoogleGenAI({});\n \nconst recipeJsonSchema = {\n  type: "object",\n  properties: {\n    recipe_name: { type: "string", description: "Name of the recipe." },\n    ingredients: {\n      type: "array", items: { type: "string" }, description: "List of ingredients."\n    },\n    prep_time_minutes: { type: "integer", description: "Prep time in minutes." }\n  },\n  required: ["recipe_name", "ingredients"]\n};\n \nconst recipeSchema = z.fromJSONSchema(recipeJsonSchema);\n \nconst interaction = await ai.interactions.create({\n  model: "gemini-3.5-flash",\n  input: "Give me a recipe for banana bread",\n  response_format: {\n    type: "text",\n    mime_type: "application/json",\n    schema: recipeJsonSchema\n  },\n});\n \nconst recipe = recipeSchema.parse(JSON.parse(interaction.output_text));\nconsole.log(recipe);\n
\n

See the structured output guide for recursive schemas and enums.

\n

Tools (Google Search)

\n

Ground responses in real-time data by passing tools: [{ type: "google_search" }].

\n

JavaScript

\n
import { GoogleGenAI } from "@google/genai";\n \nconst ai = new GoogleGenAI({});\n \nconst interaction = await ai.interactions.create({\n  model: "gemini-3.5-flash",\n  input: "Who won the euro 2024?",\n  tools: [{ type: "google_search" }],\n});\nconsole.log(interaction.output_text);\n
\n

Other built-in tools: Code Execution, URL Context, File Search, Google Maps, Computer Use. Mix multiple tools in one request. See the tool combination guide.

\n

Function calling

\n

Declare functions, let the model decide when to call them, execute locally, and return results.

\n

JavaScript

\n
import { GoogleGenAI } from "@google/genai";\n \nconst ai = new GoogleGenAI({});\n \nconst weatherTool = {\n  type: "function",\n  name: "get_current_temperature",\n  description: "Gets the current temperature for a given location.",\n  parameters: {\n    type: "object",\n    properties: {\n      location: {\n        type: "string",\n        description: "The city name, e.g. San Francisco",\n      },\n    },\n    required: ["location"],\n  },\n};\n \nconst availableFunctions = {\n  get_current_temperature: ({ location }) => ({\n    location, temperature: "22", unit: "celsius"\n  }),\n};\n \nlet input = "What is the temperature in London?";\nlet previousId = null;\nlet interaction;\n \nwhile (true) {\n  interaction = await ai.interactions.create({\n    model: "gemini-3.5-flash",\n    input,\n    tools: [weatherTool],\n    previous_interaction_id: previousId,\n  });\n \n  const functionResults = [];\n  for (const step of interaction.steps) {\n    if (step.type === "function_call") {\n      const result = availableFunctions[step.name](step.arguments);\n      console.log(`Called ${step.name}(${JSON.stringify(step.arguments)}) →`, result);\n      functionResults.push({\n        type: "function_result",\n        name: step.name,\n        call_id: step.id,\n        result: [{ type: "text", text: JSON.stringify(result) }],\n      });\n    }\n  }\n \n  if (functionResults.length === 0) break;\n \n  input = functionResults;\n  previousId = interaction.id;\n}\n \nconsole.log(interaction.output_text);\n
\n

The model returns status: "requires_action" with function_call steps. You execute locally and submit function_result steps back. See the function calling guide for parallel calls and function choice modes.

\n

Managed agents

\n

Run an agent in a remote sandbox with code execution, web browsing, and file management. Pass agent instead of model and set environment: "remote".

\n

JavaScript

\n
import { GoogleGenAI } from "@google/genai";\n \nconst ai = new GoogleGenAI({});\n \nconst interaction = await ai.interactions.create({\n  agent: "antigravity-preview-05-2026",\n  input: "Write a script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt.",\n  environment: "remote",\n});\nconsole.log(interaction.output_text);\n
\n

Define custom agents with your own instructions, skills, and data sources. See the Managed Agents quickstart.

\n

Background execution

\n

Set background: true for long-running tasks. The call returns immediately and you poll for results.

\n

JavaScript

\n
import { GoogleGenAI } from "@google/genai";\n \nconst ai = new GoogleGenAI({});\n \nconst interaction = await ai.interactions.create({\n  model: "gemini-3.5-flash",\n  input: "Write a detailed analysis of AI in healthcare.",\n  background: true,\n});\nconsole.log(`Task started: ${interaction.id} (status: ${interaction.status})`);\n \nconst poll = setInterval(async () => {\n  const result = await ai.interactions.get(interaction.id);\n  if (result.status === "completed") {\n    console.log(result.output_text);\n    clearInterval(poll);\n  } else if (result.status === "failed") {\n    console.error("Failed:", result.error);\n    clearInterval(poll);\n  }\n}, 5000);\n
\n

See the background execution guide.

\n
\n

Thanks for reading! If you have any questions, feel free to contact me on Twitter or LinkedIn.

\n", "content_markdown": "The [Interactions API](https://ai.google.dev/gemini-api/docs/interactions) is Google's primary interface for Gemini models and agents. A single endpoint covers text generation, streaming, multi-turn chat, multimodal inputs, image generation, structured output, tool use, function calling, managed agents, and background execution.\n\nThis guide uses JavaScript. For Python and REST examples, see the [Interactions API quickstart](https://ai.google.dev/gemini-api/docs/interactions/quickstart).\n\n**Using a coding agent?** Install the skill so your agent stays current with Interactions API patterns:\n\nShell\n\n```shell\nnpx skills add google-gemini/gemini-skills --skill gemini-interactions-api\n```\n\n## Setup\n\nCreate a free API key at [Google AI Studio](https://aistudio.google.com/apikey), then set it as an environment variable:\n\nShell\n\n```shell\nexport GEMINI_API_KEY=\"YOUR_API_KEY\"\n```\n\nInstall the SDK:\n\nShell\n\n```shell\nnpm install @google/genai\n```\n\nSend your first request.\n\nJavaScript\n\n```javascript\nimport { GoogleGenAI } from \"@google/genai\";\n \nconst ai = new GoogleGenAI({});\n \nconst interaction = await ai.interactions.create({\n model: \"gemini-3.5-flash\",\n input: \"Explain how AI works in a few words\",\n});\nconsole.log(interaction.output_text);\n```\n\n`interaction.output_text` gives you the final text directly. See the [text generation guide](https://ai.google.dev/gemini-api/docs/interactions/text-generation) for system instructions and generation config.\n\n## Streaming\n\nAdd `stream: true` and iterate over events. Each `step.delta` with `type === \"text\"` is a chunk you can display immediately.\n\nJavaScript\n\n```javascript\nimport { GoogleGenAI } from \"@google/genai\";\n \nconst ai = new GoogleGenAI({});\n \nconst stream = await ai.interactions.create({\n model: \"gemini-3.5-flash\",\n input: \"Explain how AI works\",\n stream: true,\n});\n \nfor await (const event of stream) {\n if (event.event_type === \"step.delta\") {\n if (event.delta.type === \"text\") {\n process.stdout.write(event.delta.text);\n }\n }\n}\n```\n\nSee the [streaming guide](https://ai.google.dev/gemini-api/docs/interactions/streaming) for event types and delta handling.\n\n## Multi-turn conversations\n\nChain interactions by passing `previous_interaction_id`. The server manages history for you.\n\nJavaScript\n\n```javascript\nimport { GoogleGenAI } from \"@google/genai\";\n \nconst ai = new GoogleGenAI({});\n \nconst interaction1 = await ai.interactions.create({\n model: \"gemini-3.5-flash\",\n input: \"I have 2 dogs in my house.\",\n});\nconsole.log(\"Response 1:\", interaction1.output_text);\n \nconst interaction2 = await ai.interactions.create({\n model: \"gemini-3.5-flash\",\n input: \"How many paws are in my house?\",\n previous_interaction_id: interaction1.id,\n});\nconsole.log(\"Response 2:\", interaction2.output_text);\n```\n\nFor client-side history management, set `store: false`. See the [multi-turn guide](https://ai.google.dev/gemini-api/docs/interactions/text-generation#multi-turn-conversations).\n\n## Multimodal understanding\n\nGemini natively understands images, audio, video, and documents. Upload a file and pass it alongside text.\n\nJavaScript\n\n```javascript\nimport { GoogleGenAI } from \"@google/genai\";\n \nconst ai = new GoogleGenAI({});\n \nconst uploadedFile = await ai.files.upload({ file: \"photo.jpg\" });\n \nconst interaction = await ai.interactions.create({\n model: \"gemini-3.5-flash\",\n input: [\n { type: \"text\", text: \"What is in this image?\" },\n {\n type: \"image\",\n uri: uploadedFile.uri,\n mime_type: uploadedFile.mimeType,\n },\n ],\n});\nconsole.log(interaction.output_text);\n```\n\nAudio, video, and documents use the same structure. See the guides for [audio](https://ai.google.dev/gemini-api/docs/interactions/audio), [video](https://ai.google.dev/gemini-api/docs/interactions/video-understanding), and [document processing](https://ai.google.dev/gemini-api/docs/interactions/document-processing).\n\n## Image generation\n\nGenerate images with Nano Banana 2 using the `gemini-3.1-flash-image` model.\n\nJavaScript\n\n```javascript\nimport { GoogleGenAI } from \"@google/genai\";\nimport fs from \"node:fs\";\n \nconst ai = new GoogleGenAI({});\n \nconst interaction = await ai.interactions.create({\n model: \"gemini-3.1-flash-image\",\n input: \"Generate an image of a futuristic city skyline at sunset\",\n});\n \nfs.writeFileSync(\n \"generated_image.png\",\n Buffer.from(interaction.output_image.data, \"base64\")\n);\n```\n\n[Speech generation](https://ai.google.dev/gemini-api/docs/interactions/speech-generation) (multi-speaker TTS) and [music generation](https://ai.google.dev/gemini-api/docs/interactions/music-generation) (Lyria 3) work the same way. See the [image generation guide](https://ai.google.dev/gemini-api/docs/interactions/image-generation) for editing, aspect ratios, and style references.\n\n## Structured output\n\nGet JSON that matches a schema you define. Works with [Zod](https://zod.dev/).\n\nJavaScript\n\n```javascript\nimport { GoogleGenAI } from \"@google/genai\";\nimport * as z from \"zod\";\n \nconst ai = new GoogleGenAI({});\n \nconst recipeJsonSchema = {\n type: \"object\",\n properties: {\n recipe_name: { type: \"string\", description: \"Name of the recipe.\" },\n ingredients: {\n type: \"array\", items: { type: \"string\" }, description: \"List of ingredients.\"\n },\n prep_time_minutes: { type: \"integer\", description: \"Prep time in minutes.\" }\n },\n required: [\"recipe_name\", \"ingredients\"]\n};\n \nconst recipeSchema = z.fromJSONSchema(recipeJsonSchema);\n \nconst interaction = await ai.interactions.create({\n model: \"gemini-3.5-flash\",\n input: \"Give me a recipe for banana bread\",\n response_format: {\n type: \"text\",\n mime_type: \"application/json\",\n schema: recipeJsonSchema\n },\n});\n \nconst recipe = recipeSchema.parse(JSON.parse(interaction.output_text));\nconsole.log(recipe);\n```\n\nSee the [structured output guide](https://ai.google.dev/gemini-api/docs/interactions/structured-output) for recursive schemas and enums.\n\n## Tools (Google Search)\n\nGround responses in real-time data by passing `tools: [{ type: \"google_search\" }]`.\n\nJavaScript\n\n```javascript\nimport { GoogleGenAI } from \"@google/genai\";\n \nconst ai = new GoogleGenAI({});\n \nconst interaction = await ai.interactions.create({\n model: \"gemini-3.5-flash\",\n input: \"Who won the euro 2024?\",\n tools: [{ type: \"google_search\" }],\n});\nconsole.log(interaction.output_text);\n```\n\nOther built-in tools: [Code Execution](https://ai.google.dev/gemini-api/docs/interactions/code-execution), [URL Context](https://ai.google.dev/gemini-api/docs/interactions/url-context), [File Search](https://ai.google.dev/gemini-api/docs/interactions/file-search), [Google Maps](https://ai.google.dev/gemini-api/docs/interactions/maps-grounding), [Computer Use](https://ai.google.dev/gemini-api/docs/interactions/computer-use). Mix multiple tools in one request. See the [tool combination guide](https://ai.google.dev/gemini-api/docs/interactions/tool-combination).\n\n## Function calling\n\nDeclare functions, let the model decide when to call them, execute locally, and return results.\n\nJavaScript\n\n```javascript\nimport { GoogleGenAI } from \"@google/genai\";\n \nconst ai = new GoogleGenAI({});\n \nconst weatherTool = {\n type: \"function\",\n name: \"get_current_temperature\",\n description: \"Gets the current temperature for a given location.\",\n parameters: {\n type: \"object\",\n properties: {\n location: {\n type: \"string\",\n description: \"The city name, e.g. San Francisco\",\n },\n },\n required: [\"location\"],\n },\n};\n \nconst availableFunctions = {\n get_current_temperature: ({ location }) => ({\n location, temperature: \"22\", unit: \"celsius\"\n }),\n};\n \nlet input = \"What is the temperature in London?\";\nlet previousId = null;\nlet interaction;\n \nwhile (true) {\n interaction = await ai.interactions.create({\n model: \"gemini-3.5-flash\",\n input,\n tools: [weatherTool],\n previous_interaction_id: previousId,\n });\n \n const functionResults = [];\n for (const step of interaction.steps) {\n if (step.type === \"function_call\") {\n const result = availableFunctions[step.name](step.arguments);\n console.log(`Called ${step.name}(${JSON.stringify(step.arguments)}) →`, result);\n functionResults.push({\n type: \"function_result\",\n name: step.name,\n call_id: step.id,\n result: [{ type: \"text\", text: JSON.stringify(result) }],\n });\n }\n }\n \n if (functionResults.length === 0) break;\n \n input = functionResults;\n previousId = interaction.id;\n}\n \nconsole.log(interaction.output_text);\n```\n\nThe model returns `status: \"requires_action\"` with `function_call` steps. You execute locally and submit `function_result` steps back. See the [function calling guide](https://ai.google.dev/gemini-api/docs/interactions/function-calling) for parallel calls and function choice modes.\n\n## Managed agents\n\nRun an agent in a remote sandbox with code execution, web browsing, and file management. Pass `agent` instead of `model` and set `environment: \"remote\"`.\n\nJavaScript\n\n```javascript\nimport { GoogleGenAI } from \"@google/genai\";\n \nconst ai = new GoogleGenAI({});\n \nconst interaction = await ai.interactions.create({\n agent: \"antigravity-preview-05-2026\",\n input: \"Write a script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt.\",\n environment: \"remote\",\n});\nconsole.log(interaction.output_text);\n```\n\nDefine [custom agents](https://ai.google.dev/gemini-api/docs/custom-agents) with your own instructions, skills, and data sources. See the [Managed Agents quickstart](https://ai.google.dev/gemini-api/docs/managed-agents-quickstart).\n\n## Background execution\n\nSet `background: true` for long-running tasks. The call returns immediately and you poll for results.\n\nJavaScript\n\n```javascript\nimport { GoogleGenAI } from \"@google/genai\";\n \nconst ai = new GoogleGenAI({});\n \nconst interaction = await ai.interactions.create({\n model: \"gemini-3.5-flash\",\n input: \"Write a detailed analysis of AI in healthcare.\",\n background: true,\n});\nconsole.log(`Task started: ${interaction.id} (status: ${interaction.status})`);\n \nconst poll = setInterval(async () => {\n const result = await ai.interactions.get(interaction.id);\n if (result.status === \"completed\") {\n console.log(result.output_text);\n clearInterval(poll);\n } else if (result.status === \"failed\") {\n console.error(\"Failed:\", result.error);\n clearInterval(poll);\n }\n}, 5000);\n```\n\nSee the [background execution guide](https://ai.google.dev/gemini-api/docs/interactions/interactions-overview#background-execution).\n\n* * *\n\nThanks for reading! If you have any questions, feel free to contact me on [Twitter](https://twitter.com/_philschmid) or [LinkedIn](https://www.linkedin.com/in/philipp-schmid-a6a2bb196/).\n", "dateCreated": "2026-09-27T19:29:15.293681927+00:00", "date_created": "2026-06-23T00:00:00+00:00", "date_modified": "2026-06-23T00:00:00+00:00", "date_published": "2026-06-23T00:00:00+00:00", "description": "A developer guide to the Gemini Interactions API, text generation, streaming, multi-turn chat, multimodal inputs, structured output, tool use, managed agents, and background execution from a single endpoint.", "external_url": "https://www.philschmid.de/interactions-api-developer-guide", "git": { "commit": "ebb0941c5c06a2ab2377342d607535262a3e969e", "path": "items/philschmid-de/2026/06/2026-06-23-getting-started-with-the-gemini-interactions-api.md", "permalink": "https://github.com/aymericbeaumet/aggr-instance/blob/ebb0941c5c06a2ab2377342d607535262a3e969e/items/philschmid-de/2026/06/2026-06-23-getting-started-with-the-gemini-interactions-api.md" }, "id": "urn:aggr:item:628eaaa23480f670626c0b0fce711001cbb81635", "isBasedOn": { "@id": "https://www.philschmid.de/interactions-api-developer-guide" }, "mainEntity": { "@id": "https://www.philschmid.de/interactions-api-developer-guide", "@type": "CreativeWork", "archivedAt": { "@id": "https://aggr.aymericbeaumet.com/items/philschmid-de/2026-06-23-getting-started-with-the-gemini-interactions-api/#webpage" }, "dateModified": "2026-06-23T00:00:00+00:00", "datePublished": "2026-06-23T00:00:00+00:00", "headline": "Getting started with the Gemini Interactions API", "timeRequired": "PT5M", "url": "https://www.philschmid.de/interactions-api-developer-guide", "wordCount": 989 }, "name": "Archived snapshot: Getting started with the Gemini Interactions API", "preview": null, "reading_minutes": 5, "replicated_at": null, "source": "philschmid-de", "source_name": "philschmid.de - RSS feed", "summary": "A developer guide to the Gemini Interactions API, text generation, streaming, multi-turn chat, multimodal inputs, structured output, tool use, managed agents, and background execution from a single endpoint.", "tags": [], "temporalCoverage": "2026-09-27T19:29:15.293681927+00:00", "title": "Getting started with the Gemini Interactions API", "url": "https://aggr.aymericbeaumet.com/items/philschmid-de/2026-06-23-getting-started-with-the-gemini-interactions-api/", "word_count": 989 }