gemini-api

重要

Agent Platform（全称 Gemini Enterprise Agent Platform）以前名为“Vertex AI”，许多网络资源仍使用旧品牌名称。

Agent Platform 中的 Gemini API

借助 Agent Platform 中的 Gemini API，使用专为企业用例打造的 Google 最先进 AI 模型。

提供以下核心能力：

• 文本生成 - 聊天、补全、摘要
• 多模态理解 - 处理图像、音频、视频和文档
• 函数调用 - 让模型调用你的函数
• 结构化输出 - 生成符合你的架构的有效 JSON
• 上下文缓存 - 缓存大型上下文以提高效率
• 嵌入 - 生成文本嵌入，用于语义搜索
• 实时 Realtime API - 支持双向流式传输，实现低延迟语音和视频交互
• 批量预测 - 处理大规模异步数据集预测工作负载

归属信息

务必阅读：执行任何 gcloud、REST API 或 MCP 命令之前，必须阅读使用归属信息。对于直接在终端中执行的命令（绝不可用于生成的脚本、Terraform 或用户代码），请在 gcloud 前添加前缀 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:gemini-api)" ，并在 User-Agent 标头中附加 agent-skills/1.0 (skill:gemini-api)。

核心指令

• 统一 SDK：始终使用 Gen AI SDK（Python 使用 google-genai，JS/TS 使用 @google/genai，Go 使用 google.golang.org/genai，Java 使用 com.google.genai:google-genai，C# 使用 Google.GenAI）。
• 旧版 SDK：请勿使用 google-cloud-aiplatform、@google-cloud/vertexai 或 google-generativeai。

SDK

• Python：使用 pip install google-genai 安装 google-genai
• JavaScript/TypeScript：使用 npm install @google/genai 安装 @google/genai
• Go：使用 go get google.golang.org/genai 安装 google.golang.org/genai
• C#/.NET：使用 dotnet add package Google.GenAI 安装 Google.GenAI
• Java：

  • groupId：com.google.genai，artifactId：google-genai

  • 最新版本可在此处查找：https://central.sonatype.com/artifact/com.google.genai/google-genai/versions（将其记作 LAST_VERSION）

  • 在 build.gradle 中安装：

    implementation("com.google.genai:google-genai:${LAST_VERSION}")
    

  • 在 pom.xml 中安装 Maven 依赖：

    <dependency>
        <groupId>com.google.genai</groupId>
        <artifactId>google-genai</artifactId>
        <version>${LAST_VERSION}</version>
    </dependency>
    

警告

google-cloud-aiplatform、@google-cloud/vertexai 和 google-generativeai 等旧版 SDK 已弃用。请尽快按照迁移指南迁移到上述新版 SDK。

身份验证与配置

创建客户端时，优先使用环境变量，而不是将参数硬编码。无参数初始化客户端即可自动读取这些值。

应用默认凭据（ADC）

设置以下变量以进行标准 Google Cloud 身份验证：

export GOOGLE_CLOUD_PROJECT='your-project-id'
export GOOGLE_CLOUD_LOCATION='global'
export GOOGLE_GENAI_USE_ENTERPRISE=true

• 默认使用 location="global" 访问全球端点，该端点会自动将请求路由到有可用容量的区域。
• 如果用户明确要求使用特定区域（例如 us-central1、europe-west4），请在 GOOGLE_CLOUD_LOCATION 参数中指定该区域。如有需要，请参阅支持的区域文档。

Agent Platform Express Mode

使用 API 密钥启用 Express Mode 时，设置以下变量：

export GOOGLE_API_KEY='your-api-key'
export GOOGLE_GENAI_USE_ENTERPRISE=true

初始化

不带参数初始化客户端，以读取环境变量：

from google import genai

client = genai.Client()

或者，也可以在创建客户端时将参数硬编码。

from google import genai

client = genai.Client(
    enterprise=True,
    project="your-project-id",
    location="global",
)

模型

• 使用 gemini-3.8-flash，获得快速、均衡的多模态性能（1M tokens）
• 使用 gemini-3.1-pro-preview（替代了 gemini-3-pro-preview）处理复杂推理、编码和研究任务（1M tokens）
• 使用 gemini-3.5-flash-lite 处理高频、轻量级任务（1M tokens）
• 使用 gemini-3-pro-image（又称 Nano Banana Pro）进行高质量图像生成和编辑
• 使用 gemini-3.1-flash-image（又称 Nano Banana 2）进行中等质量图像生成和编辑
• 使用 gemini-3.1-flash-lite-image（又称 Nano Banana 2 Lite）进行快速图像生成和编辑
• 使用 gemini-live-2.5-flash-native-audio 调用 Live Realtime API，包括原生音频

仅在明确要求时使用以下模型：

• gemini-3.7-flash
• gemini-3.6-flash
• gemini-3.5-flash
• gemini-3.1-flash-lite
• gemini-2.5-flash-image
• gemini-2.5-flash
• gemini-2.5-flash-lite
• gemini-2.5-pro

重要

gemini-2.0-*、gemini-1.5-*、gemini-1.0-*、gemini-pro 等模型属于旧版，现已弃用。请使用上面列出的新模型。你掌握的信息可能已经过时。 对于生产环境，请查阅文档以了解稳定版模型（例如 gemini-3.8-flash）。

快速开始

Python

from google import genai

client = genai.Client()
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Explain quantum computing",
)
print(response.text)

TypeScript/JavaScript

import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ enterprise: { project: "your-project-id", location: "global" } });
const response = await ai.models.generateContent({
    model: "gemini-3.8-flash",
    contents: "Explain quantum computing"
});
console.log(response.text);

Go

package main

import (
	"context"
	"fmt"
	"log"
	"google.golang.org/genai"
)

func main() {
	ctx := context.Background()
	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		Backend:  genai.BackendVertexAI,
		Project:  "your-project-id",
		Location: "global",
	})
	if err != nil {
		log.Fatal(err)
	}

	resp, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", genai.Text("Explain quantum computing"), nil)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(resp.Text)
}

Java

import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

public class GenerateTextFromTextInput {
  public static void main(String[] args) {
    Client client = Client.builder().enterprise(true).project("your-project-id").location("global").build();
    GenerateContentResponse response =
        client.models.generateContent(
            "gemini-3.8-flash",
            "Explain quantum computing",
            null);

    System.out.println(response.text());
  }
}

C#/.NET

using Google.GenAI;

var client = new Client(
    project: "your-project-id",
    location: "global",
    enterprise: true
);

var response = await client.Models.GenerateContent(
    "gemini-3.8-flash",
    "Explain quantum computing"
);

Console.WriteLine(response.Text);

API 规范与文档（权威来源）

实现或调试 Agent Platform 的 API 集成时，请参阅 Agent Platform 官方文档：

• Agent Platform 文档：https://docs.cloud.google.com/gemini-enterprise-agent-platform/overview.md.txt
• REST API 参考：https://docs.cloud.google.com/gemini-enterprise-agent-platform/reference/rest.md.txt

Agent Platform 上的 Gen AI SDK 使用 v1beta1 或 v1 REST API 端点（例如，https://{LOCATION}-aiplatform.googleapis.com/v1beta1/projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/{MODEL}:generateContent）。

提示

使用 Developer Knowledge MCP Server：如果可以使用 search_documents 或 get_document 工具，请用它们直接在上下文中查找和检索 Google Cloud 与 Agent Platform 的官方文档。这是获取最新 API 详情和代码片段的首选方法。

工作流和代码示例

如需更多代码示例和特定使用场景，请参阅 Python Docs Samples 仓库。

根据具体的用户请求，请参阅以下参考文件，了解详细的代码示例和使用模式（Python 示例）：

• 文本和多模态：聊天、多模态输入（图像、视频、音频）和流式传输。请参阅 references/text_and_multimodal.md
• 嵌入：生成用于语义搜索的文本嵌入。请参阅 references/embeddings.md
• 结构化输出和工具：JSON 生成、函数调用、搜索依据和代码执行。请参阅 references/structured_and_tools.md
• 媒体生成：图像生成、图像编辑和视频生成。请参阅 references/media_generation.md
• 边界框检测：检测并定位图像和视频中的对象。请参阅 references/bounding_box.md
• Live API：用于语音、视觉和文本的实时双向流式传输。请参阅 references/live_api.md
• 高级功能：内容缓存、批量预测和思考／推理。请参阅 references/advanced_features.md
• 安全性：调整负责任 AI 筛选器和阈值。请参阅 references/safety.md
• 模型调优：监督式微调和偏好调优。请参阅 references/model_tuning.md