Gemini 中文指南
获取 API 密钥 ↗

使用 Gemini API 密钥

↓ 下载 Markdown

要使用 Gemini API,您必须验证您的请求。您可以使用标准或授权 API 密钥进行身份验证。

创建或查看 Gemini API 密钥

API 密钥类型:标准与授权 #

API 密钥提供对Gemini API的访问,但它们的安全特性不同。 Gemini API 正在从标准 API 密钥过渡到授权密钥以提高安全性:

  • 标准型 API 密钥:将请求与 Google Cloud 项目关联以用于计费和配额目的。标准密钥无法识别调用者,这限制了它们可以支持的权限和访问控制的粒度。

  • 授权 (auth) 密钥:直接绑定到 Google Cloud 服务帐户。当您使用授权密钥时,您的请求将在该绑定服务帐户的身份下进行处理,从而实现精细的访问控制。默认情况下,授权密钥仅限于生成语言 API (Gemini API),并提供快速泄漏密钥强制执行,可快速停止使用我们的系统检测到的泄漏密钥。

为了确保安全使用,Gemini API将从标准密钥转移到身份验证密钥:

  • 授权密钥默认:从 5 月开始,28, 2026, 在 Google AI Studio 中创建的所有新 API 密钥都会自动创建为身份验证密钥。

  • 不受限制的密钥被拒绝: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 按键 仪表板中的页面以在该项目中创建密钥。

导入项目可能需要 项目验证 他们可以使用 Gemini API 免费套餐。您还可以 设置帐单 改为使用付费套餐。

密钥创建权限疑难解答 #

如果 创建 API 密钥 按钮不可用并显示消息: “您无权在此项目中创建密钥”,您缺乏所需的 IAM 权限。

请您的 Google Cloud 项目或组织管理员授予您包含以下权限的角色(例如项目编辑者):

  • resourcemanager.projects.get:允许AI Studio查找项目。

  • apikeys.keys.create:允许生成密钥。

  • serviceusage.services.enable:确保启用生成语言 API。

  • iam.serviceAccounts.create:需要创建链接的服务帐户。

  • iam.serviceAccountApiKeyBindings.create:将服务帐号与API 密钥绑定。

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

使用页面上的未知键 #

该 使用页面 在 Google AI Studio 组中请求它无法与项目中名为 API 密钥的项目匹配 (未知键)。这包括 30 天前删除的密钥、没有显示名称的密钥以及使用其他凭据(例如 OAuth)发出的请求。

在Google Cloud控制台中创建密钥 #

Google AI Studio 仅显示 Gemini API 不受限制或限制的按键。如果您无法使用 AI Studio,或者您想在一个位置管理所有 API 密钥,请按照以下云文档进行操作: 创建 API 密钥。创建 Gemini API 密钥需要将其绑定到 服务帐户。在 Google AI Studio 之外创建的项目可能需要 项目验证 在他们可以使用免费套餐之前。

设置您的环境 #

获得密钥后,配置您的环境以在应用程序中安全地使用它。

选项 1:使用环境变量(推荐) #

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

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

验证您是否有 bash 配置文件:

posix-terminal
~/.bashrc

如果没有,请创建一个并打开它:

posix-terminal
touch ~/.bashrc && open ~/.bashrc

在文件末尾添加导出命令:

posix-terminal
export GEMINI_API_KEY=[YOUR_API_KEY_HERE]

保存文件,然后应用更改:

posix-terminal
source ~/.bashrc

选项 2:在代码中显式提供 API 密钥 #

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

python
from google import genai

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

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

安全与保密管理 #

将您的 Gemini API 密钥视为密码。如果受到威胁,其他人可能会消耗您项目的配额、产生意外的计费费用并访问私有资源。

关键安全规则 #

  • 对密钥保密:切勿将 API 密钥检查到 Git 等源代码控制系统中。

  • 切勿在生产中暴露密钥客户端:请勿直接在 Web 或移动应用程序中对 API 密钥进行硬编码。用户可以提取客户端代码中编译的密钥。为了保护客户端应用程序的安全,请运行后端代理服务器来进行实际的 API 调用。

秘密管理最佳实践 #

  • 环境变量:从环境变量而不是配置文件中读取密钥。

  • 秘密经理:对于生产,请将密钥存储在安全的秘密存储中,例如 Google Cloud 秘密管理器.

  • 账单提醒:在 Google Cloud 控制台中设置计费警报,以便在使用量或成本激增时通知您。

泄漏响应检查表 #

如果您怀疑您的 API 密钥已被泄露:

  1. 生成新密钥:在Google AI Studio或云控制台中创建替换密钥。

  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. 上 API 按键 页面进入 Google AI Studio,找到标有的键 无限制 标签。

  2. 将鼠标悬停在标签上并单击 添加限制 在对话框中。

  3. 选择 仅限制为 Gemini API.

  4. 点击 限制键 确认。

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

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

  1. 参观 Google Cloud 控制台凭证页面.

  2. 选择项目和 API 密钥。

  3. 下 API 限制,选择 限制键.

  4. 从下拉列表中,选择您希望此密钥访问的 API。不要选择 生成语言 API.

  5. 点击 保存。在 AI Studio 中创建一个单独的受限密钥以继续使用 Gemini API。

被阻止的休眠键 #

从 5 月开始,7, 2026, Gemini API 会阻止已休眠较长时间的不受限制的 API 密钥。这些键显示 被阻止 AI Studio 中的标签。您必须生成新密钥或使用现有的受限密钥才能继续。

迁移到身份验证密钥 #

请按照以下步骤创建新的身份验证 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 项目。

  • 仅显示不受限制或专门限制于生成语言 API (Gemini API) 的 API 密钥。

对于高级项目管理或修改具有其他限制的密钥,请使用 Google Cloud 控制台凭证页面.

搜索标题、API 名称或正文内容