前言¶

从 2026 年 6 月起，Google 将 Interactions API 标为 Generally Available，并建议新项目优先采用；旧的 generateContent 仍可用，但文档明确写「新模型、多模态、工具与 Agent 能力会先在 Interactions API 上发布」。如果你还在用 google-generativeai、手写 generateContent，或让编码助手凭训练数据猜 SDK，很容易踩到已弃用模型、错误端点或遗漏 previous_interaction_id 等约定。

下面介绍 Google 在 google-gemini/gemini-skills 仓库里维护的 gemini-api-dev Skill。它面向 Gemini Interactions API 的文本、多模态、流式、函数调用、结构化输出及从 generateContent 迁移等场景。说明一点：线索里的路径 skills/gemini-interactions-api 在仓库 main 分支当前返回 404；官方目录与安装名均为 gemini-api-dev，Interactions 文档 也写明应安装该 Skill。

这是什么¶

gemini-api-dev 是一份符合 Agent Skills 规范的 SKILL.md 指令集，由 google-gemini/gemini-skills 维护（仓库声明：非 Google 官方支持产品）。Skill 的 description 写明：在调用 Gemini API 做文本生成、多轮对话、多模态理解、图像/视频/语音生成、流式响应、后台研究任务、函数调用、结构化输出，或 从旧 generateContent 迁移 时使用；覆盖 Python 与 TypeScript SDK 用法与最佳实践。

与「只贴一段 Quickstart」不同，Skill 强调规则优先于模型陈旧知识：当前应使用的模型 ID、SDK 包与版本下限、Interaction 数据模型（steps、流式事件类型），以及写代码前必须拉取对应 hosted 文档页。

核心功能（已核实范围）¶

根据 SKILL.md 与仓库 README，该 Skill 覆盖的能力包括：

1. Interactions API 主路径：client.interactions.create / get，响应辅助属性 output_text、output_image、output_audio。
2. 有状态多轮：通过 previous_interaction_id 链式续聊；tools、system_instruction、generation_config 为 interaction-scoped，每轮需重新传入。
3. 流式：stream=True（Python）或 stream: true（TypeScript），事件序列含 interaction.created、 step.delta、interaction.completed 等。
4. 函数调用与工具生态：Skill 内列出 Function Calling、Google Search、Code Execution、Structured Output 等文档入口；步骤类型含 function_call / function_result。
5. Agent：Deep Research（background=True 轮询）、托管 Agent（如 antigravity-preview-09-2026，需 environment="remote"）、自定义 Agent（client.agents.create）。
6. 迁移：Skill 要求从 generateContent 迁移时阅读随 Skill 附带的 references/migration.md，并与用户确认改动范围。
7. 存储与合规默认值：Interactions 默认 store=true（付费档保留 55 天，免费档 1 天）；store=false 时不能使用 previous_interaction_id 与 background=true。

Skill 明确要求使用 google-genai ≥ 2.30.1（Python）与 @google/genai ≥ 2.29.1（JS/TS），并弃用 google-generativeai / @google/generative-ai。实时双向 Live API 则指向同仓库的 gemini-live-api-dev Skill，不在本文 Skill 内展开。

仓库 README 提到：为该系列 Skill 做评测时，加入 Skill 后助手按最佳实践生成正确 API 代码的比例在 Gemini 3 Flash 上约为 87%、Gemini 3.1 Pro 上约为 96%（详见 Google 开发者博客 Closing the knowledge gap with agent skills）。

安装与启用¶

安装时使用的 Skill 名称是 gemini-api-dev，不是已失效的 gemini-interactions-api 路径。

Vercel skills CLI（skills.sh）：

# 浏览并安装
npx skills add google-gemini/gemini-skills --list

# 仅安装 gemini-api-dev
npx skills add google-gemini/gemini-skills --skill gemini-api-dev

Context7：

npx ctx7 skills install /google-gemini/gemini-skills gemini-api-dev

Cursor：

/add-plugin google-gemini/gemini-skills

安装的是整个 gemini-skills 插件集；Interactions 相关开发对应其中的 gemini-api-dev。

Claude Code：

/plugin marketplace add google-gemini/gemini-skills
/plugin install gemini-skills@gemini-skills

OpenAI Codex：

codex plugin marketplace add https://github.com/google-gemini/gemini-skills
codex plugin add gemini-skills@gemini-skills

Antigravity 可内置该插件集，或通过：

agy plugin install https://github.com/google-gemini/gemini-skills

更完整的编码助手 + Gemini Docs MCP 配置见 Set up your coding agent。

典型用法¶

启用 Skill 后，让助手「按 Interactions API 写一段最小可运行示例」时，应落到 interactions.create 而非 generateContent。下面示例来自官方 SKILL.md，用于验证环境与 Skill 是否生效。

Python：先安装 SDK，再发起单次文本 Interaction。

pip install -U google-genai

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Tell me a short joke about programming."
)
print(interaction.output_text)

TypeScript：

npm install @google/genai

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: "Tell me a short joke about programming.",
});
console.log(interaction.output_text);

有状态第二轮（同一对话链）：

interaction1 = client.interactions.create(
    model="gemini-3.8-flash",
    input="Hi, my name is Phil."
)
interaction2 = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is my name?",
    previous_interaction_id=interaction1.id
)
print(interaction2.output_text)

流式输出（节选处理 step.delta 文本）：

for event in client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain quantum entanglement in simple terms.",
    stream=True,
):
    if event.event_type == "step.delta" and event.delta.type == "text":
        print(event.delta.text, end="", flush=True)

Skill 要求：在写具体业务代码之前，根据任务从 SKILL.md 的 Documentation Pages 列表抓取对应 ai.google.dev 文档（如 Function Calling、Streaming），以参数与边界情况为准，示例仅作最小演示。

适用场景与注意¶

适合谁：

• 新建或改造 Gemini 应用，需要统一走 Interactions API（文本、多模态、工具、Agent）。
• 使用 Cursor、Claude Code、Codex 等助手生成 SDK 代码，希望减少弃用 API 与错误模型 ID。
• 正在从 generateContent 迁移，需要清单式对照与 references/migration.md 指引。

限制与坑：

• 安装路径请用 gemini-api-dev；skills/gemini-interactions-api 目前无法访问，勿按错误目录名安装。
• Skill 内将部分 gemini-2.x / gemini-1.5 标为 legacy；与 Interactions 官方支持模型表 并存时，以你要调用的 API 与账号可用模型为准，迁移时按 Skill 要求替换并告知用户。
• Interactions API 仍不支持 Batch API、Python 自动函数调用等（官方 Limitations 列表）；有这类需求需继续评估 generateContent 或其它产品能力。
• 默认存储 Interaction；若合规要求无状态，需显式 store=false 并接受无法链式 previous_interaction_id。
• 仓库 Disclaimer：本项目不属于 Google 官方支持的开源产品。

结尾¶

Interactions API 已是 Google 文档推荐的新项目默认接口；gemini-api-dev Skill 把模型/SDK 约束、Interaction 数据模型、流式与迁移要点写进助手上下文，弥补模型训练截止带来的文档滞后。若你正在把助手接到 Gemini 开发流里，可先按上文命令安装该 Skill，再用最小 interactions.create 示例跑通，再按任务拉取官方文档页扩展函数调用或多模态。

官方 Skill 目录：https://github.com/google-gemini/gemini-skills/tree/main/skills/gemini-api-dev
Interactions API 文档：https://ai.google.dev/gemini-api/docs/interactions