前言¶
在 Cursor、Claude Code 等环境里写 Gemini 调用代码时，模型名、SDK 包名和 API 形态往往和训练数据里的「旧版」不一致：generateContent 与 interactions、旧包 google-generativeai 与新包 google-genai 并存，文档又分散在 REST 说明与各语言 changelog 里。接错模型或沿用已弃用接口，轻则编译失败，重则 silently 打到 legacy 端点。
下面介绍 Google 在 gemini-skills 仓库中维护的 gemini-api-dev：把当前模型列表、SDK 版本约束、迁移说明和可运行示例收进一份 Agent Skill，在写代码前优先约束助手的行为。
这是什么¶
gemini-api-dev 是 Google Gemini 团队提供的 Agent Skill，路径为 skills/gemini-api-dev。Skill 元数据写明：在需要调用 Gemini API 做文本生成、多轮对话、多模态理解、图像/视频/语音生成、流式输出、后台研究任务、函数调用、结构化输出，或从旧版 generateContent 迁移时，应启用本 Skill；覆盖 Python 与 TypeScript 的 SDK 用法与最佳实践（officialskills.sh 还说明其亦涵盖 Go、Java 场景下的应用构建指引）。
核心定位可以概括为：用「Critical Rules」覆盖助手过时知识，并指向仓库内 references/ 文档与托管文档页，而不是只给零散代码片段。
核心功能¶
以下内容均来自官方 SKILL.md 与 skills 目录说明，仅列已写明的能力。
模型与 Agent 清单¶
Skill 强制使用文档中的「当前模型」，并标明 gemini-2.5-*、gemini-2.0-*、gemini-1.5-* 等为 legacy，不得选用；若用户指定弃用模型，应替换为 gemini-3.8-flash 并说明替换关系。
文档列出的模型类型包括（节选）：
- 通用与推理：
gemini-4-argon、gemini-3.8-flash、gemini-3.5-flash-lite、gemini-3.1-flash-lite - 语音转写：
gemini-3.5-transcribe - 图像：
gemini-nano-banana-2.1、gemini-3-pro-image、gemini-3.1-flash-lite-image - TTS：
gemini-3.8-flash-tts、gemini-3.8-flash-lite-tts - 视频：
gemini-omni-1.1-flash - Gemma 4 开放权重：
gemma-4-31b-it、gemma-4-26b-a4b-it - 嵌入：
gemini-embedding-2（多模态）、gemini-embedding-001（纯文本）
托管 Agent 包括 antigravity-preview-09-2026、deep-research-preview-04-2026、deep-research-max-preview-04-2026，并支持通过 client.agents.create() 自定义 Agent。
SDK 与 API 形态¶
当前 SDK 要求：
| 语言 | 包名 | 最低版本 | 安装 |
|---|---|---|---|
| Python | google-genai |
>= 2.30.1 |
pip install -U google-genai |
| JavaScript/TypeScript | @google/genai |
>= 2.29.1 |
npm install @google/genai |
SDK 2.0.0 及以上使用新的 steps schema，不再支持 legacy schema。旧包 google-generativeai（Python）与 @google/generative-ai（JS）在 Skill 中标记为 deprecated，不得使用。
调用入口以 client.interactions.create 为主（Quick Start 示例），响应对象提供 output_text、output_image、output_audio 等便捷字段。
开发与迁移指引¶
Skill 要求在写任何代码之前，根据任务从文档列表拉取对应托管文档页（Skill 内示例为最小集，完整参数与边界情况在文档中）。
其他硬性约定包括：
- 交互默认
store=True（Python）/store: true（TS）；付费档保留 55 天，免费档 1 天。设为false可退出存储，但会禁用previous_interaction_id与background=True。 tools、system_instruction、generation_config为 interaction 作用域，每轮需重新传入。- 托管 Agent 需
environment="remote"（或环境 ID / 配置对象）以 provision 沙箱。 - 从
generateContent迁移、升级 Flash / TTS / Nano Banana 图像模型等，需阅读仓库内references/migration.md并按 Skill 要求先与用户确认范围。
官方 skills 站归纳的能力还包括：多模态输入、函数调用、结构化 JSON、代码执行、上下文缓存、嵌入等；具体 API 以 Skill 指向的文档为准。
安装与启用¶
在支持 Agent Skills 的助手环境中，可用官方推荐的 CLI 安装整个 gemini-skills 仓库并只启用本 Skill：
npx skills add https://github.com/google-gemini/gemini-skills --skill gemini-api-dev
也可将 Skill 目录链接交给编码助手安装：
https://github.com/google-gemini/gemini-skills/tree/main/skills/gemini-api-dev
环境变量方面，Quick Start 使用默认 genai.Client() / new GoogleGenAI({})，即依赖各 SDK 约定的 API Key 配置方式（具体字段以当前 SDK 文档为准；Skill 正文未展开各 IDE 差异，此处不臆造 Cursor / Codex CLI 的专有配置项）。
典型用法¶
单轮文本生成¶
Python 侧创建客户端并调用 interactions.create，模型示例为 gemini-3.8-flash：
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 等价写法：
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);
多轮有状态对话¶
第二轮通过 previous_interaction_id 关联上一轮 interaction.id，依赖服务端在 store=True 下的上下文保留：
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)
Deep Research 后台任务¶
使用 Agent 名 deep-research-preview-04-2026（或 max 版本），并设置 background=True，轮询 client.interactions.get 直至 status 为 completed 或 failed：
import time
interaction = client.interactions.create(
agent="deep-research-preview-04-2026",
input="Research the history of Google TPUs.",
background=True
)
while True:
interaction = client.interactions.get(interaction.id)
if interaction.status == "completed":
print(interaction.output_text)
break
elif interaction.status == "failed":
print(f"Failed: {interaction.error}")
break
time.sleep(10)
适用场景与注意¶
适合谁：正在用 Gemini 3.x / 4.x 系列模型和 google-genai 新 SDK 做应用或 Agent 的开发者；需要从旧 generateContent 或旧 SDK 迁移、且希望编码助手不要自动填 legacy 模型名的团队。
何时启用（据 officialskills.sh）：结构化 JSON、函数调用、音视频文档多模态解析、多轮聊天、语料嵌入语义检索等任务。
需要注意：
- Skill 明确声明规则优先于助手训练数据；仍应在生成代码前让助手按 Skill 要求 fetch 对应文档页，避免只抄 Skill 内最小示例。
- 默认存储交互会带来留存策略与隐私考量；若不需要
previous_interaction_id或后台任务，需理解store=False的副作用。 - 模型与 Agent 名称随预览版迭代，应以仓库内
SKILL.md的 Current Models / Current Agents 为准，而非公开教程里的旧名称。
Gemini API 与 SDK 迭代较快，官方 Skill 的价值在于把「当前该用什么」固化成助手必读规则，并挂接迁移清单与文档入口，减少对照 discovery spec 与多份 changelog 的手工成本。
官方地址：https://github.com/google-gemini/gemini-skills/tree/main/skills/gemini-api-dev
