前言¶

從 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