# 使用 Gemini API 密钥

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

{% button href="https://aistudio.google.com/apikey" variant="ais" %}创建或查看 Gemini API 密钥{% /button %}

## API 密钥类型：标准与授权  {% #api-keys %}

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 密钥继续有效。此限制可防止未经授权使用可能公开共享或链接到其他服务的密钥。

{% callout type="note" %}
通过授权密钥验证的请求不会记录在 Google Cloud 服务帐户使用指标中。
{% /callout %}

## 在Google AI Studio中管理API 密钥  {% #getting-started %}

您可以管理您的项目并直接输入 [Google AI Studio](https://aistudio.google.com/apikey).

### Google Cloud 项目  {% #google-cloud-projects %}

每个 Gemini API 密钥都与一个相关联 [Google Cloud项目](https://cloud.google.com/resource-manager/docs/creating-managing-projects)。 Google Cloud 项目管理计费、协作者和权限。 Google AI Studio 提供了一个轻量级接口来访问这些项目。

* **默认项目**：如果您是新用户，在您接受服务条款后，Google AI Studio 会自动创建默认的 Google Cloud 项目和 API 密钥。您可以通过导航到重命名该项目 **项目** 在您的仪表板中查看。

* **现有项目**：如果您已有Google Cloud帐户，AI Studio不会创建默认项目。相反，您必须导入现有项目。

### 导入项目  {% #import-projects %}

默认情况下，Google AI Studio 不会显示所有 Google Cloud 项目。您必须导入要使用的项目：

1. 前往 [Google AI Studio](https://aistudio.google.com).

1. 打开 **仪表板** 从左侧面板中选择 **项目**.

1. 单击 **导入项目** 按钮。

1. 搜索并选择要导入的 Google Cloud 项目，然后单击 **进口**.

1. 导入后，导航至 **API 按键** 仪表板中的页面以在该项目中创建密钥。

导入项目可能需要 [项目验证](/docs/verification) 他们可以使用 Gemini API 免费套餐。您还可以 [设置帐单](/docs/billing#setup-billing) 改为使用付费套餐。

### 密钥创建权限疑难解答  {% #key-permission %}

如果 **创建 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 项目来生成密钥。

### 使用页面上的未知键  {% #unknown-keys %}

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

## 在Google Cloud控制台中创建密钥  {% #cloud-console %}

Google AI Studio 仅显示 Gemini API 不受限制或限制的按键。如果您无法使用 AI Studio，或者您想在一个位置管理所有 API 密钥，请按照以下云文档进行操作： [创建 API 密钥](https://cloud.google.com/docs/authentication/api-keys#create)。创建 Gemini API 密钥需要将其绑定到 [服务帐户](https://cloud.google.com/iam/docs/service-account-overview)。在 Google AI Studio 之外创建的项目可能需要 [项目验证](/docs/verification) 在他们可以使用免费套餐之前。

## 设置您的环境  {% #setup-environment %}

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

### 选项 1：使用环境变量（推荐）  {% #set-api-env-var %}

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

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

{% tabs %}
{% tab label="Linux/macOS - Bash" %}
验证您是否有 bash 配置文件：

```posix-terminal
~/.bashrc
```

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

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

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

```posix-terminal
export GEMINI_API_KEY=[YOUR_API_KEY_HERE]
```

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

```posix-terminal
source ~/.bashrc
```
{% /tab %}

{% tab label="macOS-Zsh" %}
验证您是否有 zsh 配置文件：

```posix-terminal
~/.zshrc
```

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

```posix-terminal
touch ~/.zshrc && open ~/.zshrc
```

添加导出命令：

```posix-terminal
export GEMINI_API_KEY=[YOUR_API_KEY_HERE]
```

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

```posix-terminal
source ~/.zshrc
```
{% /tab %}

{% tab label="窗户" %}
1. 在 Windows 搜索栏中搜索“环境变量”。
1. 点击 **环境变量** 在系统属性对话框中。
1. 下 **用户变量** 或 **系统变量**，点击 **新...**.
1. 将变量名称设置为 `GEMINI_API_KEY` 以及您的 API 密钥的价值。
1. 点击 **OK** 保存。打开一个新的终端会话来加载变量。
{% /tab %}
{% /tabs %}

### 选项 2：在代码中显式提供 API 密钥  {% #provide-api-key-explicitly %}

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

{% tabs %}
{% tab label="Python" %}
```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)
```
{% /tab %}

{% tab label="JavaScript" %}
```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-4-hydrogen",
    input: "Explain how AI works in a few words",
  });
  console.log(interaction.output_text);
}

await main();
```
{% /tab %}

{% tab label="Java" %}
```java
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(""));
```
{% /tab %}

{% tab label="Go" %}
```go
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)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
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"
  }'
```
{% /tab %}
{% /tabs %}

## 安全与保密管理  {% #security %}

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

### 关键安全规则  {% #critical-security-rules %}

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

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

### 秘密管理最佳实践  {% #secret-management %}

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

* **秘密经理**：对于生产，请将密钥存储在安全的秘密存储中，例如 [Google Cloud 秘密管理器](https://cloud.google.com/secret-manager).

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

### 泄漏响应检查表  {% #leak-response %}

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

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

1. **更新您的应用程序**：使用新密钥部署您的代码。

1. **禁用或删除受损的密钥**：验证新密钥后，请在 Cloud 控制台中禁用泄漏的密钥。在新密钥完全激活之前，请勿删除旧密钥，以避免应用程序停机。

1. **审计使用情况**：在 Google Cloud 控制台中检查计费日志和 API 使用情况，以识别未经授权的活动。

## 限制和保护您的密钥  {% #restricting-keys %}

向 API 密钥添加限制可最大限度地减少密钥泄露时的潜在损害。

### 应用请求来源限制  {% #request-origin-restrictions %}

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

1. 前往 [Google Cloud 控制台凭证页面](https://console.cloud.google.com/apis/credentials).

1. 选择您的项目，然后单击要限制的 API 密钥的名称。

1. 下 **应用限制**，选择 **IP地址** （或适合您环境的限制类型）。

1. 指定允许的 IP 地址或范围，然后单击 **保存**.

### 确保不受限制的标准 API 密钥  {% #secure-unrestricted-keys %}

要继续使用 Gemini API，您必须保护所有不受限制的密钥。

#### 方法A：将密钥限制为仅限Gemini API（AI Studio）  {% #method-a-restrict-the-key-to-the-gemini-api-only-ai-studio %}

如果您仅使用 Gemini API 的密钥，请直接在 AI Studio 中保护它：

1. 上 **API 按键** 页面进入 [Google AI Studio](https://aistudio.google.com/api-keys)，找到标有的键 **无限制** 标签。

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

1. 选择 **仅限制为 Gemini API**.

1. 点击 **限制键** 确认。

{% callout type="note" %}
要限制 API 密钥，您必须具有 `apikeys.keys.update` 关联 Google Cloud 项目的权限。此权限包含在诸如 **API 密钥管理** 或 **编辑**.
{% /callout %}

#### 方法B：限制其他服务的密钥（Google Cloud控制台）  {% #method-b-restrict-the-key-for-other-services-google-cloud-console %}

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

1. 参观 [Google Cloud 控制台凭证页面](https://console.cloud.google.com/apis/credentials).

1. 选择项目和 API 密钥。

1. 下 **API 限制**，选择 **限制键**.

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

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

### 被阻止的休眠键  {% #blocked-keys %}

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

## 迁移到身份验证密钥  {% #migrate-to-auth-key %}

请按照以下步骤创建新的身份验证 API 密钥并更新您的应用程序：

1. 前往 [AI Studio API 按键页面](https://aistudio.google.com/api-keys).

1. 检查 **钥匙类型** 列来标识列出的任何键 **标准型**.

1. 点击 **创建 API 密钥** 生成新密钥。在 AI Studio 中创建的所有新密钥都会自动创建为身份验证密钥。

1. 复制新的授权 API 密钥。

1. 更新您的应用程序代码、环境变量和任何部署配置以使用新的身份验证 API 密钥。

1. 测试您的应用程序以确认它可以使用新密钥正常工作。

1. 验证后，删除或撤销您的旧流量密钥以防止滥用。

{% callout type="note" %}
如果您没有看到密钥，则可能需要将云项目导入 AI Studio。请参阅 [进口项目](/docs/api-key#import-projects) 部分的说明。
{% /callout %}

## 限制  {% #limitations %}

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

* 您一次最多可以从 Google AI Studio 创建 10 项目 **项目** 页。

* 该 **API 密钥** 和 **项目** 页面最多显示 100 键和 50 项目。

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

对于高级项目管理或修改具有其他限制的密钥，请使用 [Google Cloud 控制台凭证页面](https://console.cloud.google.com/apis/credentials).
