使用 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 密钥 都会自动创建为授权密钥。
  • 拒绝不受限制的密钥：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.6-flash",
    input="Explain how AI works in a few words"
)
print(interaction.output_text)

JavaScript

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

const ai =