使用 Gemini API 密钥
要使用 Gemini API,您必须验证您的请求。您可以使用标准或授权 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 项目。您必须导入要使用的项目:
前往 Google AI Studio.
打开 仪表板 从左侧面板中选择 项目.
单击 导入项目 按钮。
搜索并选择要导入的 Google Cloud 项目,然后单击 进口.
导入后,导航至 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 配置文件:
~/.bashrc
如果没有,请创建一个并打开它:
touch ~/.bashrc && open ~/.bashrc
在文件末尾添加导出命令:
export GEMINI_API_KEY=[YOUR_API_KEY_HERE]
保存文件,然后应用更改:
source ~/.bashrc
验证您是否有 zsh 配置文件:
~/.zshrc
如果没有,请创建一个并打开它:
touch ~/.zshrc && open ~/.zshrc
添加导出命令:
export GEMINI_API_KEY=[YOUR_API_KEY_HERE]
保存文件,然后应用更改:
source ~/.zshrc
- 在 Windows 搜索栏中搜索“环境变量”。
- 点击 环境变量 在系统属性对话框中。
- 下 用户变量 或 系统变量,点击 新....
- 将变量名称设置为
GEMINI_API_KEY以及您的 API 密钥的价值。 - 点击 OK 保存。打开一个新的终端会话来加载变量。
选项 2:在代码中显式提供 API 密钥 #
您可以在初始化客户端时显式传递 API 密钥。仅当无法使用环境变量时才执行此操作。
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)
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "YOUR_API_KEY" });
async function main() {
const interaction = await ai.interactions.create({
model: "gemini-4-hydrogen",
input: "Explain how AI works in a few words",
});
console.log(interaction.output_text);
}
await main();
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-4-hydrogen"))
.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(""));
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: "{{ '<var>YOUR_API_KEY</var>' }}",
})
if err != nil {
log.Fatal(err)
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
Model: interactions.Model("gemini-4-hydrogen"),
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)
}
}
curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H 'Content-Type: application/json' \
-H "x-goog-api-key: YOUR_API_KEY" \
-H "Api-Revision: 2026-05-20" \
-X POST \
-d '{
"model": "gemini-4-hydrogen",
"input": "Explain how AI works in a few words"
}'
安全与保密管理 #
将您的 Gemini API 密钥视为密码。如果受到威胁,其他人可能会消耗您项目的配额、产生意外的计费费用并访问私有资源。
关键安全规则 #
对密钥保密:切勿将 API 密钥检查到 Git 等源代码控制系统中。
切勿在生产中暴露密钥客户端:请勿直接在 Web 或移动应用程序中对 API 密钥进行硬编码。用户可以提取客户端代码中编译的密钥。为了保护客户端应用程序的安全,请运行后端代理服务器来进行实际的 API 调用。
秘密管理最佳实践 #
环境变量:从环境变量而不是配置文件中读取密钥。
秘密经理:对于生产,请将密钥存储在安全的秘密存储中,例如 Google Cloud 秘密管理器.
账单提醒:在 Google Cloud 控制台中设置计费警报,以便在使用量或成本激增时通知您。
泄漏响应检查表 #
如果您怀疑您的 API 密钥已被泄露:
生成新密钥:在Google AI Studio或云控制台中创建替换密钥。
更新您的应用程序:使用新密钥部署您的代码。
禁用或删除受损的密钥:验证新密钥后,请在 Cloud 控制台中禁用泄漏的密钥。在新密钥完全激活之前,请勿删除旧密钥,以避免应用程序停机。
审计使用情况:在 Google Cloud 控制台中检查计费日志和 API 使用情况,以识别未经授权的活动。
限制和保护您的密钥 #
向 API 密钥添加限制可最大限度地减少密钥泄露时的潜在损害。
应用请求来源限制 #
来源限制限制了哪些 IP 地址、网站或应用程序可以使用您的密钥。
选择您的项目,然后单击要限制的 API 密钥的名称。
下 应用限制,选择 IP地址 (或适合您环境的限制类型)。
指定允许的 IP 地址或范围,然后单击 保存.
确保不受限制的标准 API 密钥 #
要继续使用 Gemini API,您必须保护所有不受限制的密钥。
方法A:将密钥限制为仅限Gemini API(AI Studio) #
如果您仅使用 Gemini API 的密钥,请直接在 AI Studio 中保护它:
上 API 按键 页面进入 Google AI Studio,找到标有的键 无限制 标签。
将鼠标悬停在标签上并单击 添加限制 在对话框中。
选择 仅限制为 Gemini API.
点击 限制键 确认。
方法B:限制其他服务的密钥(Google Cloud控制台) #
如果密钥与其他 Google API 共享(不推荐),请在 Cloud 控制台中对其进行限制。 注意:应用这些限制后,使用此密钥的 Gemini API 请求将失败。
选择项目和 API 密钥。
下 API 限制,选择 限制键.
从下拉列表中,选择您希望此密钥访问的 API。不要选择 生成语言 API.
点击 保存。在 AI Studio 中创建一个单独的受限密钥以继续使用 Gemini API。
被阻止的休眠键 #
从 5 月开始,7, 2026, Gemini API 会阻止已休眠较长时间的不受限制的 API 密钥。这些键显示 被阻止 AI Studio 中的标签。您必须生成新密钥或使用现有的受限密钥才能继续。
迁移到身份验证密钥 #
请按照以下步骤创建新的身份验证 API 密钥并更新您的应用程序:
检查 钥匙类型 列来标识列出的任何键 标准型.
点击 创建 API 密钥 生成新密钥。在 AI Studio 中创建的所有新密钥都会自动创建为身份验证密钥。
复制新的授权 API 密钥。
更新您的应用程序代码、环境变量和任何部署配置以使用新的身份验证 API 密钥。
测试您的应用程序以确认它可以使用新密钥正常工作。
验证后,删除或撤销您的旧流量密钥以防止滥用。
限制 #
Google AI Studio 施加以下项目和密钥管理限制:
您一次最多可以从 Google AI Studio 创建 10 项目 项目 页。
该 API 密钥 和 项目 页面最多显示 100 键和 50 项目。
仅显示不受限制或专门限制于生成语言 API (Gemini API) 的 API 密钥。
对于高级项目管理或修改具有其他限制的密钥,请使用 Google Cloud 控制台凭证页面.