Gemini API 使用教程：获取 Key 与第一次调用

从在 Google AI Studio 获取 API Key、设置环境变量到用官方 SDK 完成第一次调用，讲清 Gemini Developer API 的接口形态、认证方式、限流层级，以及它和 AI Studio、企业版平台之间的边界。

先把三个名字分清楚

搜 “Gemini API” 会同时搜到三样东西，混在一起写的教程会让你越看越糊涂。它们的关系是这样的：

名字	是什么	怎么认证	你在这里做什么
Google AI Studio	网页工作台	Google 账号登录	拿密钥、试提示词、看用量
Gemini Developer API	程序调用的接口	API Key	真正的调用发生在这里
企业版平台（Google Cloud）	Cloud 上的同一批模型	服务账号与 IAM	需要企业级控制时才用

不是三个模型，是同一批模型的三种接入方式。 本文讲的是中间那个——Gemini Developer API，也就是绝大多数开发者第一次接入时该走的路。最后一节会说明什么时候该考虑企业版。

开始之前

• 一个 Google 账号，不需要额外注册。
• 一个能跑代码的环境：Python 或 Node.js；只想确认链路的话 curl 就够。
• 网络能访问 aistudio.google.com 与 generativelanguage.googleapis.com。

获取 API Key

用 Google 账号登录 Google AI Studio，打开 API keys 页面。

新用户通常不需要先手动建项目——AI Studio 会自动创建一个项目和一把密钥，直接复制即可。也可以点击新建再加一把。

按用途分开建密钥是个好习惯：本地调试一把、生产一把，出问题时可以只撤销受影响的那一个。

密钥安全

官方文档在这一点上写得很直白：不要把密钥硬编码进网页或移动应用，因为编译进客户端代码的密钥可以被用户提取出来。需要在前端使用模型能力时，正确做法是让前端调用你自己的后端，由后端持有密钥去调 Gemini。

其余底线和别家一样：不进源码、不进公开仓库、不进截图和聊天记录；怀疑泄露就立刻在 AI Studio 里删除并重建。

设置环境变量

export GEMINI_API_KEY="你的密钥"

Windows 上在系统环境变量里新建 GEMINI_API_KEY，保存后重开终端才会生效。

这里有个容易踩的坑：SDK 同时认 GEMINI_API_KEY 和 GOOGLE_API_KEY，两个都设置时后者优先。 如果机器上残留着一把旧的 GOOGLE_API_KEY（比如以前用别的 Google 服务留下的），它会静默覆盖你刚配好的密钥，表现出来就是莫名其妙的认证失败。排查认证问题时先把这个变量查一遍。

安装官方 SDK

官方现在提供的是统一的 Google Gen AI SDK：同一个库既能连 Developer API，也能连企业版平台，切换只是一个参数。

Python：

pip install -U google-genai

JavaScript：

npm install @google/genai

注意 Python 的包名是 google-genai，导入时写 from google import genai。网上有不少教程用的是更早的包，装错了会发现文档里的方法都找不到。

第一次请求

Python：

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="用一句话解释什么是 API。"
)

print(interaction.output_text)

JavaScript：

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

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: "用一句话解释什么是 API。",
});

console.log(interaction.output_text);

REST：

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "用一句话解释什么是 API。"
  }'

Client() 不传参数，是因为它自己去读环境变量了。

两个容易出错的地方：认证头是 x-goog-api-key，不是别家常见的 Authorization: Bearer；模型名会变，写代码前到官方模型页面确认当前可用的名称，不要照抄旧文章。

关于接口形态

如果你在网上看到的 Gemini 教程写法和上面不一样，多半是因为接口形态换过。

官方当前的默认形态是 Interactions 接口，也是新项目该起步的地方。更早的 generateContent 写法仍然受支持，存量代码不必为了迁移而迁移，但没有理由让新代码从旧形态开始。

这也是为什么本文强调以官方快速开始文档为准：这一块的教程过期速度比其他家更快。

理解 model 参数

model 决定能力上限、响应速度和单价。选型的实际做法：

• 先用能力较强的模型把功能跑通，确认效果达标。
• 再往下试更快更便宜的档位，看效果是否仍然可接受。
• 对延迟敏感的场景优先小模型。

本文不列价格表。 模型与单价变动频繁，需要具体数字时看官方定价页面。把模型名做成配置项而不是散落在代码各处的字面量，换模型时会省很多事。

多模态输入

Gemini 是多模态模型，除文本外还能接收图片等其他形式的输入，这也是它常被提到的特点之一。

入门阶段的建议是：先把纯文本调通再加多模态。多模态请求的参数结构比纯文本复杂，而且这部分的写法在版本更替中变动较多，照抄旧教程出错率很高。确认文本链路正常之后，按官方文档补这一段。

Token 与成本

token 是模型处理文本的基本单位，也是计费单位，输入和输出分别计价。

三条实用结论和别家一致：多轮对话每轮都要重发历史，成本随对话长度增长；控制成本最直接的手段是裁剪历史和限制输出长度；上下文窗口是单次请求的总量上限，长对话迟早要做摘要或截断。

限流与用量层级

Gemini API 的限流按几个维度同时计算：

• RPM：每分钟请求数
• TPM：每分钟 token 数
• RPD：每天请求数（按太平洋时间午夜重置）

图像类模型还有每分钟图像数，部分模型另有每天 token 数。

RPD 这个维度值得单独提醒。 别家通常只按分钟限流，Gemini 免费层还有日额度——写个循环跑测试，很可能先把当天的额度用完，而不是撞到每分钟限制。本地调试时降低频率、加上缓存，能省掉不少困惑。

层级从免费层开始，开通结算后进入付费层级，随累计消费与时间自动升级，每一级有对应的花费上限。当前层级和各模型的具体限额可以在 AI Studio 的限流页面查看。

超限时返回 429，错误里会带资源耗尽的标识。处理方式和别家一样：指数退避加随机抖动，不要让多个客户端在同一时刻集体重试。

什么时候该转向企业版平台

Developer API 和企业版平台共用同一套 SDK，切换在代码层面只是一个参数：Python 里给 genai.Client() 传 vertexai=True 加上项目和区域，JavaScript 里传对应的构造参数。

真正的差别在认证与治理：

	Developer API	企业版平台
认证	API Key	Google Cloud 服务账号
权限	密钥即权限	IAM 精细控制
计费	AI Studio 结算	Google Cloud 账单
适合	多数开发者与产品	有企业控制或合规要求

官方的建议很明确：多数开发者用 Developer API 就够，除非确实需要特定的企业级控制。 不要因为”企业版听起来更正式”就一上来选它——它会把 Google Cloud 项目、IAM、结算这一整套复杂度提前引入你的入门流程。

顺带说明：本文讲的是 Gemini API，不是 Google Cloud 教程。企业版平台的完整配置是另一个话题。

AI Studio 该怎么用

拿到密钥之后，AI Studio 还有两个实际用途：

调提示词。 系统提示、生成参数的迭代速度在网页界面里远高于改代码。把它调稳定再落回项目，比在业务代码里反复试快得多。

看用量。 密钥管理、用量监控、当前层级都在这里。

它不是运行环境——生产调用应该发生在你自己的服务端，由服务端持有密钥、做错误处理与限流应对。AI Studio 的详细用法见 Google AI Studio 入门。

下一步

• AI Studio 怎么用：Google AI Studio 入门
• 网页版 Gemini 怎么用：Gemini 怎么用：入门指南
• 同一件事在别家怎么做：OpenAI API 使用教程、Anthropic Claude API 使用教程
• 听说过第三方中转：API 中转站是什么？和官方 API 有什么区别
• 看看还有哪些接口：AI API 目录

参考资料

• Gemini API 快速开始（官方文档）
• 获取并使用 API Key（官方文档）
• 限流与用量层级（官方文档）
• Developer API 与企业版平台的差异（官方文档）