使用 Gemini API 密钥

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

API 密钥

API 密钥是一个加密字符串，您可以使用此密钥来调用 Google Cloud 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 的所有密钥。如需相关说明，请参阅导入项目部分。

导入项目

每个 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 个密钥和 100 个项目。
  • 系统只会显示不受限制或仅限用于 Generative Language API 的 API 密钥。

如需对项目拥有额外的管理访问权限，请访问 Google Cloud 控制台。

将 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-2.5-flash", 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-2.5-flash",
    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-2.5-flash",
        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-2.5-flash",
            "Explain how AI works in a few words",
            null);

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

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash: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 密钥。如果遭到入侵，其他人可以使用您项目的配额、产生费用（如果已启用结算），并访问您的私密数据（例如文件）。

严重安全规则

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

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

最佳做法

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

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

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

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