使用 Gemini API 密钥

如需使用 Gemini API，您需要一个 API 密钥。本页面简要介绍了如何在 Google AI Studio 中创建和管理密钥，以及如何设置环境以便在代码中使用密钥。

创建或查看 Gemini API 密钥

API 密钥

您可以在 Google AI Studio API 密钥页面中创建和管理所有 Gemini API 密钥。

获得 API 密钥后，您可以通过以下方式连接到 Gemini API：

对于初始测试，您可以对 API 密钥进行硬编码，但这只应是临时做法，因为这种做法并不安全。您可以在明确提供 API 密钥部分中找到对 API 密钥进行硬编码的示例。

Google Cloud 项目

Google Cloud 项目 是使用 Google Cloud 服务（例如 Gemini API）、 管理结算以及控制协作者和权限的基础。Google AI Studio 为您的 Google Cloud 项目提供了一个轻量级界面。

如果您尚未创建任何项目，则必须创建一个新项目，或将项目从 Google Cloud 导入到 Google AI Studio 中。Google AI Studio 中的项目 页面将显示所有具有使用 Gemini API 的足够权限的密钥。如需了解相关说明，请参阅导入项目部分。

默认项目

对于新用户，在接受《服务条款》后，Google AI Studio 会创建一个默认的 Google Cloud 项目和 API 密钥，以便用户轻松使用。您可以在 Google AI Studio 中重命名此 项目，方法是前往信息中心中的 项目视图，点击项目旁边的 3 个点设置按钮，然后 选择 重命名项目。现有用户或已拥有 Google Cloud 账号的用户不会创建默认项目。

导入项目

每个 Gemini API 密钥都与一个 Google Cloud 项目相关联。默认情况下，Google AI Studio 不会显示您的所有 Cloud 项目。您必须在导入项目 对话框中搜索名称或项目 ID，以导入所需项目。如需查看您可以访问的项目的完整列表，请访问 Cloud 控制台。

如果您尚未导入任何项目，请按照以下步骤导入 Google Cloud 项目并创建密钥：

  1. 前往 Google AI Studio。
  2. 从左侧边栏打开信息中心 。
  3. 选择项目 。
  4. 在项目 页面中，选择导入项目 按钮。
  5. 搜索并选择要导入的 Google Cloud 云项目，然后选择导入 按钮。

导入项目后，从信息中心 菜单前往 API 密钥 页面，然后在刚刚导入的项目中创建 API 密钥。

限制

以下是在 Google AI Studio 中管理 API 密钥和 Google Cloud 项目的限制。

  • 您一次最多可以从 Google AI Studio 的项目 页面创建 10 个项目。
  • 您可以命名和重命名项目和密钥。
  • API 密钥 和项目 页面最多显示 100 个密钥和 50 个项目。
  • 系统只会显示没有限制或仅限于 Generative Language API 的 API 密钥。

如需获得对项目的其他管理权限，包括修改和 限制 API 密钥，请访问 Google Cloud 控制台凭据页面。 在 Cloud 控制台中，您可以选择项目，点击现有 API 密钥，然后将其限制为 Generative Language API 。

将 API 密钥设置为环境变量

如果您设置了环境变量 GEMINI_API_KEY 或 GOOGLE_API_KEY，则在使用其中一个 Gemini API 库时，客户端会自动获取 API 密钥。建议您仅设置其中一个变量，但如果两者都设置了，则 GOOGLE_API_KEY 优先。

如果您使用的是 REST API 或浏览器上的 JavaScript，则需要明确提供 API 密钥。

下面介绍了如何在不同操作系统中将 API 密钥在本地设置为环境变量 GEMINI_API_KEY。

Linux/macOS - Bash

Bash 是一种常见的 Linux 和 macOS 终端配置。您可以通过运行以下命令来检查是否有其配置文件：

~/.bashrc

如果响应为“No such file or directory”，您需要创建此文件并通过运行以下命令打开它，或使用 zsh：

touch ~/.bashrc
open ~/.bashrc

接下来，您需要通过添加以下导出命令来设置 API 密钥：

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

保存文件后，通过运行以下命令应用更改：

source ~/.bashrc

macOS - Zsh

Zsh 是一种常见的 Linux 和 macOS 终端配置。您可以通过运行以下命令来检查是否有其配置文件：

~/.zshrc

如果响应为“No such file or directory”，您需要创建此文件并通过运行以下命令打开它，或使用 bash：

touch ~/.zshrc
open ~/.zshrc

接下来，您需要通过添加以下导出命令来设置 API 密钥：

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

保存文件后，通过运行以下命令应用更改：

source ~/.zshrc

Windows

  1. 在搜索栏中搜索“环境变量”。
  2. 选择修改系统设置 。您可能需要确认是否要执行此操作。
  3. 在系统设置对话框中，点击标有环境变量 的按钮。
  4. 在用户变量 （针对当前用户）或系统变量 （适用于使用该机器的所有用户）下，点击新建...
  5. 将变量名称指定为 GEMINI_API_KEY。将 Gemini API 密钥指定为变量值。
  6. 点击确定 以应用更改。
  7. 打开新的终端会话 (cmd 或 Powershell) 以获取新变量。

明确提供 API 密钥

在某些情况下，您可能需要明确提供 API 密钥。例如：

  • 您要执行简单的 API 调用，并且偏好对 API 密钥进行硬编码。
  • 您希望进行明确控制，而不必依赖 Gemini API 库自动发现环境变量
  • 您使用的环境不支持环境变量（例如 Web），或者您要进行 REST 调用。

以下示例展示了如何明确提供 API 密钥：

Python

from google import genai

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

response = client.models.generate_content(
    model="gemini-3-flash-preview", contents="Explain how AI works in a few words"
)
print(response.text)

JavaScript

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

const ai = new GoogleGenAI({ apiKey: "YOUR_API_KEY" });

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3-flash-preview",
    contents: "Explain how AI works in a few words",
  });
  console.log(response.text);
}

main();

Go

package main

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

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

    result, err := client.Models.GenerateContent(
        ctx,
        "gemini-3-flash-preview",
        genai.Text("Explain how AI works in a few words"),
        nil,
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Text())
}

Java

package com.example;

import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

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

    GenerateContentResponse response =
        client.models.generateContent(
            "gemini-3-flash-preview",
            "Explain how AI works in a few words",
            null);

    System.out.println(response.text());
  }
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ]
      }
    ]
  }'

确保 API 密钥的安全

请像对待密码一样对待 Gemini API 密钥。如果密钥泄露，其他人可以使用您项目的配额，产生费用（如果已启用结算功能），并访问您的私有数据（例如文件）。

关键安全规则

  • 确保密钥的机密性：Gemini 的 API 密钥可能会访问您的 应用所依赖的敏感数据。

    • 切勿将 API 密钥提交到源代码控制系统。不要将 API 密钥签入 Git 等版本控制系统。

    • 切勿在客户端公开 API 密钥。请勿在生产环境中的 Web 应用或移动应用中直接使用 API 密钥。客户端代码（包括我们的 JavaScript/TypeScript 库和 REST 调用）中的密钥可能会被提取。

  • 限制访问权限：尽可能将 API 密钥的使用范围限制为特定 IP 地址、HTTP 引荐来源网址或 Android/iOS 应用。

  • 限制使用范围：仅为每个密钥启用必要的 API。

  • 定期执行审核：定期审核 API 密钥并定期轮换密钥 。

最佳做法

  • 使用带有 API 密钥的服务器端调用 ：使用 API 密钥的最安全方式是从服务器端应用调用 Gemini API，这样可以确保密钥的机密性。

  • 使用临时令牌进行客户端访问（仅限 Live API）： 如需直接从客户端访问 Live API，您可以使用临时令牌。这些令牌的安全风险较低，适合在生产环境中使用。如需了解详情，请参阅 临时令牌指南。

  • 考虑为密钥添加限制： 您可以通过添加 API 密钥限制来限制密钥的权限。这样可以最大限度地减少密钥泄露后可能造成的损害。

如需了解一些常规最佳实践，您还可以查看这篇 支持文章。

排查 API 密钥创建问题

在 Google AI Studio 中，创建 API 密钥 按钮可能显示为不可用，并显示以下消息："您无权在此项目中创建密钥"。

如果您缺少在项目中生成新密钥所需的权限，则会发生此问题：

  • resourcemanager.projects.get：允许 AI Studio 验证项目是否存在。
  • apikeys.keys.create：允许生成 API 密钥本身。
  • serviceusage.services.enable：确保 Gemini API 在项目上处于活跃状态所必需的权限。
  • iam.serviceAccounts.create：每个新的 API 密钥现在都需要一个关联的 服务账号， 该账号是在创建 API 密钥时生成的。

如需修复权限，请让项目管理员（如果项目属于组织，则让组织管理员）向您授予具有上述权限的角色（例如项目 Editor 或自定义角色）。

如果您没有项目的管理权限，可以创建一个未与组织关联的新项目来生成密钥。