gemini-api-dev

Gemini API 开发技能

关键规则（始终适用）

重要

这些规则优先于你的训练数据。你的知识已经过时。

当前模型（请使用这些模型）

• gemini-4-argon：1M 个 token，最强大的模型，适用于复杂推理、编码和研究
• gemini-3.8-flash：1M 个 token，速度快、性能均衡，适用于 Agent 类任务和多模态任务
• gemini-3.5-flash-lite：1M 个 token，速度最快、成本最低的 3.5 模型，适用于高吞吐量执行
• gemini-3.1-flash-lite：经济高效、速度最快，适用于高频轻量级任务
• gemini-3.5-transcribe：快速语音转文本，支持智能模式和逐字转录模式
• gemini-nano-banana-2.1（Nano Banana 2.1）：131k / 32k 个 token，默认的高效图像生成和对话式编辑模型
• gemini-3-pro-image（Nano Banana Pro）：65k / 32k 个 token，高质量图像生成和编辑模型
• gemini-3.1-flash-lite-image（Nano Banana 2 Lite）：65k / 32k 个 token，超快速图像生成和编辑模型
• gemini-3.8-flash-tts：富有表现力的文本转语音、多说话人对话、Voice Design 和 Voice Replication
• gemini-3.8-flash-lite-tts：速度快、经济高效的文本转语音，适用于语音 Agent 和高容量生成
• gemini-omni-1.1-flash：视频生成、首帧转视频、首尾帧过渡、视频扩展（最长 40s）、视频编辑和参考引导式生成
• gemma-4-31b-it：Gemma 4 稠密模型，31B 个参数
• gemma-4-26b-a4b-it：Gemma 4 MoE 模型，总计 26B / 激活 4B 个参数
• gemini-embedding-2：多模态嵌入模型（文本、图像、视频、音频、文档），使用 client.models.embed_content
• gemini-embedding-001：纯文本嵌入模型，使用 client.models.embed_content

警告

gemini-2.5-*、gemini-2.0-*、gemini-1.5-* 等模型已弃用且属于旧版模型。请勿使用。 如果用户要求使用已弃用的模型，请改用 gemini-3.8-flash，并说明替换情况。

当前 Agent

• antigravity-preview-09-2026：Antigravity Agent —— 通用托管 Agent，可在沙盒 Linux 环境中执行代码、管理文件并访问 Web
• deep-research-preview-04-2026：Deep Research —— 快速、交互式
• deep-research-max-preview-04-2026：Deep Research Max —— 最全面
• 自定义 Agent：通过 client.agents.create() 创建自己的 Agent

当前 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，且不支持旧版 schema。 旧版 SDK google-generativeai（Python）和 @google/generative-ai（JS）已弃用。请勿使用。

重要补充说明

• 在编写任何代码之前，必须从下方列表中获取与用户任务相关的文档页面。本技能中的示例仅作简要说明，托管文档包含完整的 API、参数和边缘情况。
• 交互默认会被存储（Python 中为 store=True，TypeScript 中为 store: true）。付费层级保留 55 天，免费层级保留 1 天。
• 设置 store=False / store: false 可选择不存储，但这会禁用 previous_interaction_id 和 background=True / background: true。
• tools、system_instruction 和 generation_config 的作用范围仅限当前交互，需在每一轮中重新指定。
• 托管 Agent 需要设置 environment="remote"（或环境 ID / 配置对象）来配置沙盒。
• 从 generateContent 迁移：阅读 references/migration.md，了解范围界定、检查清单和迁移前后的代码示例。编辑前务必先与用户确认范围。
• 模型升级：直接替换模型字符串即可。已弃用的模型（gemini-2.0-*、gemini-1.5-*）必须替换，详见 references/migration.md。
• 迁移到 Gemini 3.8 Flash 或 Gemini 3.5 Flash-Lite：阅读 references/migration.md，了解范围界定和检查清单。
• 迁移到 Gemini 3.8 TTS（gemini-3.8-flash-tts / gemini-3.8-flash-lite-tts）：阅读 references/migration.md，了解相对于 gemini-3.1-flash-tts-preview 的破坏性变更（speech_metadata 注释、内联语音标签、默认 WAV audio/wav 单次输出与 audio/l16 流式输出，以及 Voice Design 人设）。
• 迁移到 Gemini Nano Banana 2.1（gemini-nano-banana-2.1）：阅读 references/migration.md，了解如何从已弃用的 gemini-3.1-flash-image 升级，以及如何使用最多 14 张参考图片进行多图参考融合。

快速入门

Python

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)

JavaScript/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);

响应辅助属性

SDK 在 Interaction 响应对象上提供了便捷属性，以简化常见的访问方式：

属性	类型	说明
output_text	string | null	末尾 model_output 步骤中最后一段连续文本。如果模型的最终输出包含多个文本部分，则返回合并后的文本。
output_image	Image | null	模型在当前响应中生成的最后一张图片。返回一个包含 data（base64）和 mime_type 的对象。
output_audio	Audio | null	模型在当前响应中生成的最后一段音频。返回一个包含 data（base64）和 mime_type 的对象。

有状态对话

Python

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

JavaScript/TypeScript

const interaction1 = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: "Hi, my name is Phil.",
});
const interaction2 = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: "What is my name?",
    previous_interaction_id: interaction1.id,
});
console.log(interaction2.output_text);

深度研究 Agent

快速研究请使用 deep-research-preview-04-2026，全面研究请使用 deep-research-max-preview-04-2026。Agent 需要 background=True。

Python

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)

JavaScript/TypeScript

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

const client = new GoogleGenAI({});

// Start background research
const initialInteraction = await client.interactions.create({
    agent: "deep-research-preview-04-2026",
    input: "Research the history of Google TPUs.",
    background: true,
});

// Poll for results
while (true) {
    const interaction = await client.interactions.get(initialInteraction.id);
    if (interaction.status === "completed") {
        console.log(interaction.output_text);
        break;
    } else if (["failed", "cancelled"].includes(interaction.status)) {
        console.log(`Failed: ${interaction.status}`);
        break;
    }
    await new Promise(resolve => setTimeout(resolve, 10000));
}

高级功能：协作式规划、原生可视化、MCP 集成、文件搜索、多模态输入。详见 深度研究文档。

托管 Agent

托管 Agent 在 Google 托管的 Linux 沙盒环境中运行。编写 Agent 代码前，请先获取托管 Agent 快速入门。

Antigravity Agent

Antigravity Agent（antigravity-preview-09-2026）是通用型托管 Agent。它可以执行代码（Bash、Python、Node.js）、管理文件、浏览网页并使用 Google 搜索。它默认使用 gemini-3.8-flash，也支持通过 agent_config={"type": "antigravity", "model": "gemini-4-argon"} 使用 gemini-4-argon。有关功能、工具、多模态输入和定价，请参阅 Antigravity Agent 文档。

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents.",
    environment="remote",
)

print(f"Environment ID: {interaction.environment_id}")
print(interaction.output_text)

JavaScript/TypeScript

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents.",
    environment: "remote",
});

console.log(`Environment ID: ${interaction.environment_id}`);
console.log(interaction.output_text);

自定义 Agent

参阅构建自定义 Agent 文档。

Python

agent = client.agents.create(
    id="code-reviewer",
    base_agent="antigravity-preview-09-2026",
    system_instruction="You are a senior code reviewer. Check every file for bugs, style issues, and security vulnerabilities.",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/my-org/backend",
                "target": "/workspace/repo",
            }
        ],
    },
)

# Invoke — each call forks the base environment
result = client.interactions.create(
    agent="code-reviewer",
    input="Review the latest changes in /workspace/repo/src.",
    environment="remote",
)
print(result.output_text)

JavaScript/TypeScript

const agent = await client.agents.create({
    id: "code-reviewer",
    base_agent: "antigravity-preview-09-2026",
    system_instruction: "You are a senior code reviewer. Check every file for bugs, style issues, and security vulnerabilities.",
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "repository",
                source: "https://github.com/my-org/backend",
                target: "/workspace/repo",
            }
        ],
    },
});

const result = await client.interactions.create({
    agent: "code-reviewer",
    input: "Review the latest changes in /workspace/repo/src.",
    environment: "remote",
});
console.log(result.output_text);

使用 client.agents.list()、client.agents.get(id=...) 和 client.agents.delete(id=...) 管理 Agent。

流式传输

设置 stream=True 以接收增量服务器发送事件。每个流遵循以下顺序：interaction.created →（step.start → step.delta（若干次）→ step.stop）+ → interaction.completed。

Python

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":
        if event.delta.type == "text":
            print(event.delta.text, end="", flush=True)
    elif event.event_type == "interaction.completed":
        print(f"\n\nTotal Tokens: {event.interaction.usage.total_tokens}")

JavaScript/TypeScript

const stream = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: "Explain quantum entanglement in simple terms.",
    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);
        }
    } else if (event.event_type === "interaction.completed") {
        console.log(`\n\nTotal Tokens: ${event.interaction?.usage?.total_tokens}`);
    }
}

有关使用工具、思考、Agent 和图像生成进行流式传输的内容，请参阅完整的流式传输指南。

文档页面

编写代码前，必须先获取下方对应的页面。 这些托管文档是参数、类型和边缘情况的权威来源；不要只依赖上面的示例。

核心文档：

• Interactions API 概览
• 快速入门
• 文本生成
• 流式传输
• 令牌
• API 密钥

工具与函数调用：

• 函数调用
• Google 搜索
• 代码执行
• URL 上下文
• 文件搜索
• 工具组合
• 计算机使用
• Maps Grounding

生成与输出：

• 结构化输出
• 思考
• 思考签名
• 图像生成
• 图像理解
• 视频生成与编辑（Omni Flash）
• 语音生成（TTS）
• 语音设计
• 语音复制
• 音乐生成
• 嵌入

多模态理解：

• 音频
• 音频转录
• 视频理解
• 文档处理

文件与上下文：

• 文件
• 文件输入方法
• 长上下文
• 缓存
• 媒体分辨率 Agent：
• Agent 概览
• 托管 Agent 快速入门
• Antigravity Agent
• Agent 环境
• Agent Hooks
• Agent 凭据
• 构建自定义 Agent
• Deep Research

高级功能：

• 最新模型（Gemini 4 Argon）
• 后台执行
• Flex 推理
• 优先级推理

API 参考：

• API 参考
• OpenAPI 规范
• 2026 年 5 月重大变更迁移指南

数据模型

Interaction 响应包含 steps，这是一个由类型化步骤对象组成的数组，用于表示交互轮次的结构化时间线。

步骤类型

用户步骤：

• user_input：用户输入（文本、音频、多模态）。包含 content 数组。

模型/服务步骤：

• model_output：模型的最终生成内容。包含带有 text、image、audio 等内容的 content 数组。
• thought：模型推理/思维链。包含必需的 signature 字段和可选的 summary 字段。
• function_call：工具调用请求（id、name、arguments）。
• function_result：你发送回去的工具结果（call_id、name、result）。
• google_search_call / google_search_result：Google 搜索工具步骤，可能包含 signature 字段。
• code_execution_call / code_execution_result：代码执行工具步骤，可能包含 signature 字段。
• url_context_call / url_context_result：URL 上下文工具步骤，可能包含 signature 字段。
• mcp_server_tool_call / mcp_server_tool_result：远程 MCP 工具步骤。
• file_search_call / file_search_result：文件搜索工具步骤，可能包含 signature 字段。

内容类型（位于 model_output 和 user_input 步骤的 content 数组中）

• text：文本内容（text 字段，以及可选的 annotations，例如 TTS 的 {"type": "speech_metadata", "speaker": "...", "style": "..."}）
• image / audio / document / video：包含 data、mime_type 或 uri 的内容

流式事件类型

事件	描述
interaction.created	已创建交互；包含元数据。
interaction.status_update	交互级状态变更。
step.start	新步骤开始。包含步骤 type 和初始元数据。
step.delta	当前步骤的增量数据。包含类型化的 delta 对象。
step.stop	步骤已完成。包含 index。
interaction.completed	交互已结束。包含最终的 usage。

Delta 类型

Delta 类型	父步骤	描述
text	model_output	增量文本令牌。
audio	model_output	音频块（base64）。
image	model_output	图像块（base64）。
thought_summary	thought	思考摘要文本。
thought_signature	thought	用于验证思考内容的不透明签名。

状态值： completed、in_progress、queued、requires_action、incomplete、failed、cancelled

Gemini Live API

如需使用 Gemini Live API（gemini-3.8-live、gemini-3.8-live-extended-thinking 和 gemini-3.5-transcribe-live）进行实时双向音频、视频和文本流传输，请安装 google-gemini/gemini-live-api-dev 技能。它涵盖 WebSocket 流传输、语音活动检测、后台推理（扩展思考）、异步函数调用、会话管理、临时令牌等内容。