前言¶
在 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
