开始使用 Gemini Interactions API

Interactions API 是 Google 为 Gemini 模型和 agent 提供的主要接口。单个端点即可覆盖文本生成、流式传输、多轮对话、多模态输入、图像生成、结构化输出、工具使用、函数调用、托管 agent 以及后台执行。

本指南使用 JavaScript。Python 和 REST 示例请参阅 Interactions API 快速入门。

正在使用编码 agent？ 安装该技能，让你的 agent 始终掌握 Interactions API 的最新模式：

Shell

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

设置

在 Google AI Studio 创建一个免费 API 密钥，然后将其设置为环境变量：

Shell

export GEMINI_API_KEY="YOUR_API_KEY"

安装 SDK：

Shell

npm install @google/genai

发送你的第一个请求。

JavaScript

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

interaction.output_text 直接返回最终文本。系统指令和生成配置请参阅文本生成指南。

流式传输

添加 stream: true 并遍历事件。每个 type === "text" 的 step.delta 都是一个可以立即显示的 chunk。

JavaScript

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

事件类型和 delta 处理请参阅流式传输指南。

多轮对话

通过传递 previous_interaction_id 来链式调用 interactions。服务器会为你管理历史记录。

JavaScript

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

如需客户端管理历史记录，请设置 store: false。请参阅多轮对话指南。

多模态理解

Gemini 原生理解图像、音频、视频和文档。上传文件并将其与文本一起传递。

JavaScript

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

音频、视频和文档使用相同的结构。请参阅音频、视频和文档处理指南。

图像生成

使用 gemini-3.1-flash-image 模型，通过 Nano Banana 2 生成图像。

JavaScript

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

（多说话人 TTS）和音乐生成（Lyria 3）的工作方式相同。编辑、宽高比和风格参考请参阅图像生成指南。

结构化输出

获取与你定义的 schema 匹配的 JSON。可与 Zod 配合使用。

JavaScript

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

递归 schema 和枚举请参阅结构化输出指南。

工具（Google 搜索）

通过传递 tools: [{ type: "google_search" }] 将响应基于实时数据。

JavaScript

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

其他内置工具：代码执行、URL 上下文、文件搜索、Google Maps、计算机使用。可在单个请求中混合使用多个工具。请参阅工具组合指南。

函数调用

声明函数，让模型决定何时调用，在本地执行，并返回结果。

JavaScript

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

模型返回 status: "requires_action" 并附带 function_call 步骤。你在本地执行，然后将 function_result 步骤提交回去。并行调用和函数选择模式请参阅函数调用指南。

托管 agent

在远程沙箱中运行一个 agent，支持代码执行、网页浏览和文件管理。传递 agent 而非 model，并设置 environment: "remote"。

JavaScript

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

使用你自己的指令、技能和数据源定义自定义 agent。请参阅托管 Agent 快速入门。

后台执行

对于长时间运行的任务，设置 background: true。调用会立即返回，你可以轮询获取结果。

JavaScript

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

请参阅后台执行指南。

---

感谢阅读！如有任何问题，欢迎通过 Twitter 或 LinkedIn 联系我。