进阶 ai.google.dev 2026-10-15 02:43:21 · 42 阅读

第1章 Gemini API 密钥使用指南

Gemini 4 Argon 现已上线,快去试试吧。

使用 Gemini API 密钥

使用 Gemini API 需要进行身份验证。你可以使用标准密钥或授权密钥进行认证。

创建或查看 Gemini API 密钥

API 密钥类型:标准密钥与授权密钥的区别

API 密钥提供对 Gemini API 的访问权限,但其安全特性有所不同。Gemini API 正在从标准密钥向授权密钥过渡,以提升安全性:

- 标准 API 密钥:将请求与 Google Cloud 项目关联,用于计费和配额管理。标准密钥不识别调用者身份,限制了其在权限和访问控制方面的粒度。 - 授权(Auth)密钥:直接绑定到 Google Cloud 服务账号。使用授权密钥时,请求将基于绑定的服务账号身份进行处理,从而实现细粒度的访问控制。授权密钥默认仅限于 Generative Language API(即 Gemini API),并提供快速生效的泄露密钥强制执行机制,能迅速阻止我们系统检测到的泄露密钥的使用。

为确保安全使用,Gemini API 将从标准密钥过渡到 Auth 密钥:

- Auth 密钥成为默认:从 2026 年 5 月 28 日起,在 Google AI Studio 中创建的所有新 API 密钥将自动设为 Auth 密钥。 - 拒绝无限制密钥:Gemini API 将拒绝来自无限制标准密钥的请求。已应用明确限制的标准 API 密钥仍可正常工作。此限制旨在防止密钥被未经授权地公开共享或链接到其他服务。

在 Google AI Studio 中管理 API 密钥

你可以直接在 Google AI Studio 中管理项目和密钥。

Google Cloud 项目

每个 Gemini API 密钥都关联到一个 Google Cloud 项目。Google Cloud 项目负责管理计费、协作者和权限。Google AI Studio 提供了一个轻量级界面来访问这些项目。

- 默认项目:如果你是新用户,在接受服务条款后,Google AI Studio 会自动创建一个默认的 Google Cloud 项目和 API 密钥。你可以在仪表盘的“项目”视图中重命名此项目。 - 现有项目:如果你已有 Google Cloud 账号,AI Studio 不会创建默认项目。相反,你需要导入现有的项目。

导入项目

默认情况下,Google AI Studio 不会显示你所有的 Google Cloud 项目。你需要手动导入想要使用的项目:

1. 前往 Google AI Studio。 2. 从左侧面板打开“仪表盘”,并选择“项目”。 3. 点击“导入项目”按钮。 4. 搜索并选择要导入的 Google Cloud 项目,然后点击“导入”。 5. 导入完成后,在仪表盘中的“API 密钥”页面创建一个该项目的密钥。

排查密钥创建权限问题

如果“创建 API 密钥”按钮不可用,并显示提示:“你没有权限在此项目中创建密钥”,说明你缺少所需的 IAM 权限。

请联系你的 Google Cloud 项目或组织管理员,授予你包含以下权限的角色(例如项目编辑器 Project Editor):

- `resourcemanager.projects.get`:允许 AI Studio 验证项目。 - `apikeys.keys.create`:允许生成密钥。 - `serviceusage.services.enable`:确保 Generative Language API 已启用。 - `iam.serviceAccounts.create`:创建关联的服务账号所必需。 - `iam.serviceAccountApiKeyBindings.create`:将服务账号绑定到 API 密钥。

如果你无法获得管理权限,可以创建一个未与组织关联的新 Google Cloud 项目来生成密钥。

在 Google Cloud 控制台中创建密钥

Google AI Studio 仅显示无限制或限制用于 Gemini API 的密钥。如果无法使用 AI Studio,或者希望在一个地方管理所有 API 密钥,请按照云端文档创建 API 密钥。创建 Gemini API 密钥需要将其绑定到服务账号。

配置你的环境

一旦拥有密钥,请配置环境以在应用中安全使用它。

方案 1:使用环境变量(推荐)

设置环境变量 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`。Gemini API 客户端库会自动检测并使用这些变量。如果两者都已设置,`GOOGLE_API_KEY` 优先。

选择你的操作系统来设置变量:

- Linux/macOS - Bash 验证是否拥有 bash 配置文件:`~/.bashrc` 如果没有,请创建一个并打开它:`touch ~/.bashrc && open ~/.bashrc` 在文件末尾添加 export 命令:`export GEMINI_API_KEY=` 保存文件,然后应用更改:`source ~/.bashrc`

- macOS - Zsh 验证是否拥有 zsh 配置文件:`~/.zshrc` 如果没有,请创建一个并打开它:`touch ~/.zshrc && open ~/.zshrc` 添加 export 命令:`export GEMINI_API_KEY=` 保存文件,然后应用更改:`source ~/.zshrc`

- Windows 在 Windows 搜索栏中搜索“环境变量”。 在系统属性对话框中点击“环境变量”。 在“用户变量”或“系统变量”下,点击“新建”。 将变量名称设为 `GEMINI_API_KEY`,值设为你的 API 密钥。 点击“确定”保存。打开一个新的终端会话以加载该变量。

方案 2:在代码中显式提供 API 密钥

初始化客户端时,可以显式传入 API 密钥。仅当你无法使用环境变量时,才这样做。

Python ```python from google import genai

client = genai.Client(api_key="YOUR_API_KEY")

interaction = client.interactions.create( model="gemini-3.8-flash", input="Explain how AI works in a few words" ) print(interaction.output_text) ```

JavaScript ```javascript import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: "YOUR_API_KEY" });

async function main() { const interaction = await ai.interactions.create({ model: "gemini-3.8-flash", input: "Explain how AI works in a few words", }); console.log(interaction.output_text); }

main(); ```

Java ```java import com.google.genai.Client; import com.google.genai.gaos.models.interactions.CreateModelInteraction; import com.google.genai.gaos.models.interactions.Interaction; import com.google.genai.gaos.models.interactions.InteractionsInput; import com.google.genai.gaos.models.interactions.Model; import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = Client.builder().apiKey("YOUR_API_KEY").build();

CreateModelInteraction params = CreateModelInteraction.builder() .model(Model.of("gemini-3.8-flash")) .input(InteractionsInput.of("Explain how AI works in a few sentences.")) .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse("")); ```

Go ```go package main

import ( "context" "fmt" "log"

"google.golang.org/genai" "google.golang.org/genai/interactions/models/interactions" "google.golang.org/genai/interactions/models/operations" )

func main() { ctx := context.Background() client, err := genai.NewClient(ctx, &genai.ClientConfig{ APIKey: "YOUR_API_KEY", }) if err != nil { log.Fatal(err) }

res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{ Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{ Model: interactions.Model("gemini-3.8-flash"), Input: interactions.NewInteractionsInput("Explain how AI works in a few sentences."), }), }) if err != nil { log.Fatal(err) } if res.Interaction.OutputText != nil { fmt.Println(*res.Interaction.OutputText) } } ```

REST ```bash curl "https://generativelanguage.googleapis.com/v1beta/interactions" \ -H 'Content-Type: application/json' \ -H "x-goog-api-key: YOUR_API_KEY" \ -X POST \ -d '{ "model": "gemini-3.8-flash", "input": "Explain how AI works in a few words" }' ```

安全与密钥管理

将 Gemini API 密钥视同密码对待。一旦泄露,他人可消耗你项目的配额,产生意外账单费用,并访问私有资源。

关键安全规则

- 保持密钥机密:切勿将 API 密钥提交到 Git 等源代码控制系统。 - 切勿在生产环境中于客户端暴露密钥:不要在 Web 或移动应用代码中硬编码 API 密钥。编译在客户端代码中的密钥可被用户提取。为保护客户端应用,应运行后端代理服务器来发起实际的 API 调用。

密钥管理最佳实践

- 环境变量:从环境变量而非配置文件中读取密钥。 - Secret Manager:在生产环境中,将密钥存储在安全的密钥存储中,如 Google Cloud Secret Manager。 - 计费警报:在 Google Cloud 控制台设置计费警报,以便在使用量或费用激增时收到通知。

泄露应对清单

如果你怀疑 API 密钥已泄露:

1. 生成新密钥:在 Google AI Studio 或 Cloud 控制台中创建一个替代密钥。 2. 更新你的应用:使用新密钥部署代码。 3. 禁用或删除泄露的密钥:确认新密钥无误后,在 Cloud 控制台中禁用泄露的旧密钥。在新密钥完全生效之前,不要删除旧密钥,以避免应用中断。 4. 审计使用情况:检查 Google Cloud 控制台中的计费日志和 API 使用情况,以识别未经授权的活动。

限制与保护你的密钥

为 API 密钥添加限制可最大程度减少密钥泄露时可能造成的损失。

应用请求来源限制

来源限制决定了哪些 IP 地址、网站或应用可以使用你的密钥。

1. 前往 Google Cloud 控制台的“凭据”页面。 2. 选择你的项目,点击你想限制的那个 API 密钥的名称。 3. 在“应用限制”下,选择 IP 地址(或适合你环境的其他限制类型)。 4. 指定允许的 IP 地址或范围,然后点击“保存”。

保护无限制的标准 API 密钥

若要继续使用 Gemini API,你必须保护任何无限制的密钥。

方法 A:将密钥限制为仅用于 Gemini API(AI Studio)

如果你仅将该密钥用于 Gemini API,可直接在 AI Studio 中对其进行保护:

1. 在 Google AI Studio 的“API 密钥”页面,找到标记为“无限制”的密钥。 2. 将鼠标悬停在该标签上,并在弹出的对话框中点击“添加限制”。 3. 选择“仅限制为 Gemini API”。 4. 点击“限制密钥”以确认。

方法 B:为其他服务限制密钥(Google Cloud 控制台)

如果密钥与其他 Google API 共享(不推荐),请在 Cloud 控制台中进行限制。注意:应用这些限制后,使用此密钥发出的 Gemini API 请求将失败。

1. 访问 Google Cloud 控制台的“凭据”页面。 2. 选择项目和 API 密钥。 3. 在“API 限制”下,使用“选择 API 限制”下拉菜单选择你希望此密钥访问的 API。请勿选择 Generative Language API。 4. 点击“保存”。在 AI Studio 中创建一个单独的限制密钥,以继续正常使用 Gemini API。

被阻止的休眠密钥

从 2026 年 5 月 7 日起,Gemini API 将阻止长期休眠的无限制 API 密钥。这些密钥在 AI Studio 中会显示“已阻止”标签。你需要生成新密钥或使用现有的受限密钥以继续使用。

迁移到 Auth 密钥

按照以下步骤创建新的 Auth API 密钥并更新你的应用:

1. 前往 AI Studio 的“API 密钥”页面。 2. 检查“密钥类型”列,识别任何列为“标准”的密钥。 3. 点击“创建 API 密钥”生成新密钥。在 AI Studio 中创建的所有新密钥均为 Auth 密钥。 4. 复制新的 Auth API 密钥。 5. 更新你的应用程序代码、环境变量及任何部署配置,以使用新的 Auth API 密钥。 6. 测试你的应用,确认其在新密钥下能正常工作。 7. 验证无误后,删除或撤销旧的流量密钥,以防止误用。

限制

Google AI Studio 在项目和密钥管理方面存在以下限制:

- 在 Google AI Studio 的“项目”页面,一次最多只能创建 10 个项目。 - “API 密钥”和“项目”页面最多显示 100 个密钥和 50 个项目。 - 仅显示无限制或专门限制为 Generative Language API(Gemini API)的 API 密钥。

如需进行高级项目管理或修改带有其他限制的密钥,请使用 Google Cloud 控制台的“凭据”页面。

评论 (0)