使用 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 项目来生成密钥。

设置环境

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

方法 1：使用环境变量（推荐）

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

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

Linux/macOS - Bash

验证您是否有 Bash 配置文件：

~/.bashrc

如果没有，请创建一个并打开：

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

在该文件末尾添加导出命令：

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

保存文件，然后应用更改：

source ~/.bashrc

macOS - Zsh

验证您是否有 Zsh 配置文件：

~/.zshrc

如果没有，请创建一个并打开：

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

添加导出命令：

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

保存文件，然后应用更改：

source ~/.zshrc

Windows

  1. 在 Windows 搜索栏中搜索“环境变量”。
  2. 在“系统属性”对话框中，点击环境变量 。
  3. 在用户变量 或系统变量 下，点击新建…。
  4. 将变量名称设置为 GEMINI_API_KEY，并将值设置为您的 API 密钥。
  5. 点击确定 进行保存。打开新的终端会话以加载变量。

方法 2：在代码中明确提供 API 密钥

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

Python

from google import genai

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

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

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.5-flash",
    input: "Explain how AI works in a few words",
  });
  console.log(interaction.output_text);
}

main();

Go

package main

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

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)
    }

    interaction, err := client.Interactions.NewModel(ctx, interactions.NewModelParams{
        Model: "gemini-3.5-flash",
        Input: interactions.Input{
            String: "Explain how AI works in a few words",
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range interaction.Steps {
        if step.ModelOutput != nil {
            for _, content := range step.ModelOutput.Content {
                if content.Text != nil {
                    fmt.Println(content.Text.Text)
                }
            }
        }
    }
}

Java

package com.example;

import com.google.genai.Client;
import com.google.genai.interactions.models.interactions.CreateModelInteractionParams;
import com.google.genai.interactions.models.interactions.Interaction;

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

    CreateModelInteractionParams params =
        CreateModelInteractionParams.builder()
            .input("Explain how AI works in a few words")
            .model("gemini-3.5-flash")
            .build();

    Interaction interaction = client.interactions.create(params);

    interaction.steps().forEach(step -> {
      if (step.isModelOutput()) {
        step.asModelOutput().content().ifPresent(contents -> {
          contents.forEach(content -> {
            content.text().ifPresent(text -> System.out.println(text.text()));
          });
        });
      }
    });
  }
}

REST

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.5-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 Console 中创建替换密钥。
  2. 更新应用：使用新密钥部署代码。
  3. 停用或删除泄露的密钥：验证新密钥后，在 Cloud Console 中停用泄露的密钥。在新密钥完全激活之前，请勿删除旧密钥，以免应用停机。
  4. 审核用量：在 Google Cloud 控制台中查看结算日志和 API 用量，以识别未经授权的活动。

限制和保护密钥

为 API 密钥添加限制可以最大限度地减少密钥泄露造成的潜在损害。

应用请求来源限制

来源限制用于限制哪些 IP 地址、网站或应用可以使用您的密钥。

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

保护不受限制的标准 API 密钥

如需在 2026 年 6 月 19 日之后继续使用 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 Console 中限制该密钥。注意：应用这些限制后，使用此密钥的 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 中会显示 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 控制台的“凭据”页面。