使用 Gemini API 密钥

如需使用 Gemini API，您必须对请求进行身份验证。您可以使用标准 API 密钥或授权 API 密钥进行身份验证。

创建或查看 Gemini API 密钥

API 密钥类型：标准密钥与授权密钥

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

• 标准 API 密钥：将请求与 Google Cloud 项目关联，以进行 结算和配额计算。标准密钥不会识别调用方，这限制了它们可以支持的权限和访问控制的精细程度。
• 授权 (auth) 密钥：直接绑定到 Google Cloud 服务 账号。当您使用授权密钥时，系统会以该绑定服务账号的身份处理您的请求，从而实现精细的访问控制。授权密钥默认仅限于 Generative Language API (Gemini API)，并提供快速响应的泄露密钥强制执行功能，可快速停止使用我们的系统检测到的泄露密钥。

为确保安全使用，Gemini API 将从标准密钥迁移到授权密钥：

• 授权密钥默认设置：在 Google AI Studio 中创建的所有新 API 密钥 都会自动创建为授权密钥。
• 2026 年 6 月 19 日：Gemini API 将拒绝来自 不受限制的标准密钥 的请求。应用了明确限制的标准 API 密钥将继续正常运行。此限制可防止未经授权使用可能公开共享或链接到其他服务的密钥。
• 2026 年 9 月：Gemini API 将拒绝来自 标准版 密钥 的请求。您必须在此日期之前迁移到授权密钥 ，以避免服务中断。请务必在 2026 年 9 月之前迁移到授权密钥。

在 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 项目或组织管理员为您授予包含以下权限的角色（例如“项目 Editor”）：

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

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

设置环境

获得密钥后，请配置环境，以便在应用中安全地使用该密钥。

使用环境变量（推荐）

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

选择您的操作系统以设置变量：

~/.bashrc

touch ~/.bashrc && open ~/.bashrc

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

source ~/.bashrc

~/.zshrc

touch ~/.zshrc && open ~/.zshrc

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

source ~/.zshrc

在代码中明确提供 API 密钥

您可以在初始化客户端时明确传递 API 密钥。仅当您无法使用环境变量时，才应执行此操作。

from google import genai

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

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Explain how AI works in a few words"
)
print(response.text)

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

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

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: "Explain how AI works in a few words",
  });
  console.log(response.text);
}

main();

package main

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

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

    result, err := client.Models.GenerateContent(
        ctx,
        "gemini-3.5-flash",
        genai.Text("Explain how AI works in a few words"),
        nil,
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Text())
}

package com.example;

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

public class GenerateTextFromTextInput {
  public static void main(String[] args) {
    Client client = Client.builder().apiKey("YOUR_API_KEY").build();

    GenerateContentResponse response =
        client.models.generateContent(
            "gemini-3.5-flash",
            "Explain how AI works in a few words",
            null);

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

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent"       -H 'Content-Type: application/json'       -H "x-goog-api-key: YOUR_API_KEY"       -X POST       -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "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 密钥

如需在 2026 年 6 月 19 日之后继续使用 Gemini API，您必须保护所有不受限制的密钥。

通过 AI Studio 将密钥限制为仅用于 Gemini API

如果您仅将密钥用于 Gemini API，请直接在 AI Studio 中保护该密钥：

1. 在 Google AI Studio 的 API 密钥 页面上，找到标有 不受限制 标签的密钥。
2. 将鼠标悬停在该标签上，然后在对话框中点击添加限制 。
3. 选择限制为仅用于 Gemini API 。
4. 点击限制密钥 进行确认。

通过 Google Cloud 控制台限制密钥以用于其他服务

如果密钥与其他 Google API 共享（不推荐），请在 Cloud 控制台中限制该密钥。注意：应用这些限制后，使用此密钥的 Gemini API 请求将失败。

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

已屏蔽的休眠密钥

自 2026 年 5 月 7 日起，Gemini API 会屏蔽长期处于休眠状态的不受限制的 API 密钥。这些密钥在 AI Studio 中会显示 Blocked 标记。您必须生成新密钥或使用现有的受限密钥才能继续。

迁移到授权密钥

请按照以下步骤创建新的授权 API 密钥并更新应用：

1. 前往AI Studio API 密钥页面。
2. 检查密钥类型 列，以识别列为标准 的任何密钥。
3. 点击创建 API 密钥 以生成新密钥。在 AI Studio 中创建的所有新密钥都会自动创建为授权密钥。
4. 复制新的授权 API 密钥。
5. 更新应用代码、环境变量和任何部署配置，以使用新的授权 API 密钥。
6. 测试应用，确认其在新密钥下正常运行。
7. 验证后，删除或撤消旧的流量密钥，以防止滥用。

限制

Google AI Studio 施加了以下项目和密钥管理限制：

• 您一次最多可以从 Google AI Studio 的项目 页面创建 10 个项目。
• API 密钥 和项目 页面最多显示 100 个密钥和 50 个项目。
• 仅显示不受限制或专门限制为 Generative Language API (Gemini API) 的 API 密钥。

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