2026 年 Gemini API 密钥获取与使用全指南：官方不会强调的关键细节

官方文档往往将信息分散在各个页面，新手很难快速找到核心要点。本文将完整拆解从登录、生成密钥到多语言代码验证的全流程，每一步都清晰明确，不省略任何可能导致卡住的环节，特别标注官方文档中不会重点提醒的关键注意事项。

一、获取 API 密钥：官方唯一入口

Gemini API 密钥只能通过 Google AI Studio 平台获取，这是官方指定的唯一通道，具体操作步骤如下：

1. 打开浏览器访问官方平台：https://aistudio.google.com
2. 使用 Google 账号（Gmail 邮箱）登录，首次登录需阅读并接受服务条款
3. 在左侧导航栏找到🔑「Get API key（获取 API 密钥）」选项并点击进入
4. 系统会要求你为密钥设置标识名称，并选择绑定的项目。新手建议直接选择「在新 Google Cloud 项目中创建 API 密钥」，系统会自动完成项目创建并启用 Generative Language API。密钥名称建议与用途相关，方便后续管理多个项目
5. 点击「Create」按钮，屏幕中央会弹出一个包含密钥的浮层

最重要的安全提醒

生成的密钥只会在这个浮层中完整显示一次。关闭浮层后，没有任何 "查看" 或 "找回" 按钮，只能删除旧密钥并重新生成。请立即将完整密钥复制到密码管理器、本地加密备忘录或项目的.env 文件中妥善保存。

二、安全存储密钥：正确做法与常见错误

官方 SDK 会自动读取环境变量GEMINI_API_KEY或GOOGLE_API_KEY（如果两个都设置，GOOGLE_API_KEY优先级更高，建议只设置其中一个）。

最推荐的存储方式

将密钥保存在项目根目录的.env文件中，并务必将该文件添加到.gitignore，避免密钥意外提交到代码仓库：

bash

运行

# .env 文件内容（必须添加到 .gitignore！）
GEMINI_API_KEY=AIzaSy你的完整密钥

也可以在 Shell 中直接导出环境变量，写入.zshrc或.bashrc可实现全局生效：

bash

运行

export GEMINI_API_KEY="AIzaSy你的完整密钥"

⚠️ 特别注意：原文中出现的GOOGLE-API_KEY（带横杠）是非法的环境变量名，无法被系统正确识别，正确写法为下划线分隔的GOOGLE_API_KEY或GEMINI_API_KEY。

三、快速验证：用 curl 确认密钥有效性

拿到密钥后的第一件事不是打开 IDE 编写代码，而是通过终端执行一条 curl 命令进行验证。这是最快的验证方式，三秒钟就能确认密钥是否有效、API 通路是否畅通。

将以下命令中的YOUR_API_KEY替换为你刚复制的密钥，然后在终端中执行：

bash

运行

curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          { "text": "你好，请用一句话介绍一下你自己" }
        ]
      }
    ]
  }'

说明：通过 URL 的?key=参数传递密钥是 AI Studio API Key 的标准用法，也可以使用请求头X-Goog-Api-Key传递，两种方式效果相同。使用gemini-2.5-flash模型进行验证最稳定，它是免费层的主力型号，配额相对宽松。

结果判定与常见问题

表格

四、代码接入：Python 与 JavaScript 官方 SDK

终端验证通过后，即可进入代码开发环节。2026 年 Google 官方主推以下两款 SDK，分别对应 Python 和 JavaScript/TypeScript 语言。

Python SDK 使用指南

安装最新版本的官方 SDK：

bash

运行

pip install -U google-genai

最小可运行脚本：

python

运行

from google import genai

# 不传入api_key参数时，Client会自动读取环境变量GOOGLE_API_KEY或GEMINI_API_KEY
client = genai.Client()

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="用一句话介绍一下Python"
)

print(response.text)

最常见的新手错误：忘记设置环境变量就直接运行代码，导致客户端找不到密钥，出现莫名其妙的认证错误。

JavaScript/TypeScript SDK 使用指南

安装 Node.js 对应的官方 SDK：

bash

运行

npm install @google/genai

最小可运行脚本：

javascript

运行

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

// 不传apiKey参数时，自动读取环境变量GEMINI_API_KEY或GOOGLE_API_KEY
const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: "用一句话介绍一下Node.js",
  });
  console.log(response.text);
}

main();

官方强烈建议不要在代码中硬编码 API 密钥，始终让 SDK 从环境变量中读取。

五、配额与付费：免费层与付费层详解

2026 年 Gemini API 的免费层采用 RPM（每分钟请求数）、TPM（每分钟 Token 数）和 RPD（每日请求数）三维限制，任一维度超限都会返回 429 错误。

免费层配额详情

表格

需要特别注意：免费层配额是按项目计算，不是按密钥计算，多个密钥不会叠加额度。此外，免费层用户的请求数据可能会被 Google 用于模型改进，只有升级到付费层（通过 Google Cloud 结算账号）才会获得数据不用于训练的承诺，敏感数据请勿在免费层处理。

如果免费层配额无法满足需求，最正规的升级方式是前往 Google Cloud Console 启用结算功能，升级到 Tier 1 后，RPM 会提升至 150-300 + 量级。

六、常见问题与避坑指南

1. 超时问题：弱网环境下 Gemini API 的响应时间可能超过 30 秒，而 Python 默认的 HTTP 超时时间约为 10 秒。需要在客户端或请求层显式将超时时间设置为 60 秒，避免结果还没返回就被切断。
2. 上下文隐式消耗：免费额度按 Token 总量计算，每次请求中包含的历史对话越多，额度消耗越快。多轮对话要定期清理历史记录，这是节省成本的关键。

结语

完成 "获取密钥→配置环境变量→curl 验证→代码运行" 这一系列步骤，就意味着你已经打通了 Gemini API 的基础使用链路。随着 AI 开发需求的增长，你可能会遇到多模型切换、高并发调用、企业级稳定性等更高要求。

UseAIAPI作为一站式大模型服务平台，聚合了 Gemini、Claude、ChatGPT、DeepSeek 等全球主流前沿 AI 大模型，提供稳定可靠的企业级定制化服务，无需复杂配置即可快速接入使用。平台推出了极具竞争力的优惠政策，全线服务最低可享官方定价 5 折，大幅降低了高强度开发和内容生产场景下的使用成本，让更多开发者和企业能够以更低的门槛享受到先进 AI 技术带来的效率提升。