ChatGPT 中文指南

Appearance

Gemini AI Studio API Key 怎么创建？配额不足与模型不可用排查（2026） ​

更新时间：2026年9月21日

直接答案： Gemini API Key 在 Google AI Studio 的 API Key 页面创建，但“Key 已创建”不等于请求一定可用。遇到 401、403、429、配额不足或模型找不到时，按“Key 是否完整—绑定项目是否正确—API 是否启用—账号/计费与配额—模型 ID—代码环境”顺序排查。不要把旧教程中的模型名、固定免费额度或旧 SDK 当成永久规则，先以 AI Studio 当前页面和 Gemini API 模型列表为准。

本文专门处理 API Key、额度和模型调用故障，不重复介绍 AI Studio 的提示词入门。配额、可用模型、地区、计费和控制台界面会变化；排错时应保留错误类型、项目 ID 和时间，但不要公开完整 Key。

一、先把“Key 不工作”分成四类 ​

现象常见层级第一项检查
401、API key not valid凭据或请求头环境变量、Key 是否被撤销、请求是否真的带 Key
403、permission denied项目、API、账号或组织策略Key 绑定项目、Gemini API 是否启用、权限/地区
429、resource exhausted速率或配额当前模型、项目用量、RPM/TPM/日限额和响应头
model not found模型 ID 或版本官方模型列表、稳定/预览状态、账号可见范围

先不要连续点击“重新创建 Key”。同一问题生成更多 Key 不会自动解决项目、权限或配额配置，反而会让排查对象变多。

二、正确创建并确认 API Key ​

第一步：从 AI Studio 打开 Key 页面 ​

登录 Google AI Studio，进入 API Key 页面创建或查看密钥。页面可能要求选择现有 Google Cloud 项目或创建新项目；项目名称、组织策略和界面选项以当前页面为准。

创建后马上记下三项非敏感信息：

  • Key 对应的 Google Cloud 项目名称或项目编号；
  • 计划调用的 API 与模型名称；
  • 创建时间和使用它的应用环境。

不要把完整 Key 放进文章、截图、前端 JavaScript、公开仓库或日志。浏览器端代码可以被访问者查看，正式应用应由服务端读取环境变量。

第二步：确认调用项目没有漂移 ​

最常见的误区是“在项目 A 创建 Key，却用项目 B 的配额或 API 设置来排错”。在 Google Cloud 控制台核对当前项目，再检查对应 API 是否启用、组织策略是否允许调用。若应用使用多个项目，给每个环境写一份非敏感配置表，避免只凭项目显示名称判断。

第三步：用环境变量注入，而不是写入源码 ​

PowerShell 临时设置示例：

powershell
$env:GEMINI_API_KEY = "仅在本机安全输入，不要提交"

检查变量是否存在但不输出值：

powershell
if (Test-Path Env:GEMINI_API_KEY) { "GEMINI_API_KEY is set" } else { "GEMINI_API_KEY is missing" }

.env.example 只保留变量名：

dotenv
GEMINI_API_KEY=

如果 Key 曾经出现在 GitHub、CI 日志、截图或聊天中，应立即在对应控制台撤销并轮换；删除文本本身不能消除已经暴露的凭据。

三、401：Key 无效、未加载或带错了 ​

1. 先确认代码读取的是当前变量 ​

常见情况是本地终端设置了变量，但 IDE、Docker、CI 或服务进程没有继承；也可能代码仍读取旧变量名。启动应用的同一环境中检查变量是否存在，重启开发服务器后再试。

2. 排查完整性和请求格式 ​

不要在日志打印完整 URL、请求头或 Key。确认使用的是官方 SDK 或 REST 文档当前要求的认证方式，避免同时把旧 SDK 的参数和新 SDK 的参数混用。若使用 REST，请核对 Key 是以当前文档要求的方式传递，而不是把占位符、引号或换行一起发送。

3. Key 被撤销或复制时带入空格 ​

从密码管理器复制时，前后空格和换行可能导致认证失败。不要通过在日志中打印 Key 来确认；可在安全的本地环境重新设置变量，或直接轮换一枚新 Key，再比较结果。

四、403：项目、API、权限或地区不匹配 ​

403 通常意味着请求已经到达服务，但当前项目或身份没有完成调用条件。按顺序检查：

  1. Key 绑定的项目是否就是应用实际使用的项目；
  2. 对应 Gemini API 是否在该项目中启用；
  3. Google Workspace、组织策略或服务账号权限是否限制调用；
  4. 当前账号和地区是否满足页面显示的服务条件；
  5. 请求的模型是否对当前项目可见，尤其是预览模型。

不要用“再建一个 Key”绕过组织策略。若同一项目的网页测试与 API 请求都被拒绝，保存时间、项目编号和错误 request ID，交给项目管理员或按官方支持流程处理。

五、429 或配额不足：先区分速率与总量 ​

“配额不足”可能指不同限制：短时间请求次数、输入或输出 token 速率、并发、每日用量、项目预算或某个模型的独立上限。具体数字和免费层条件会变动，因此不要把旧文章的额度写死到代码中。

1. 看响应和控制台，而不是只看状态码 ​

记录以下非敏感信息：

  • HTTP 状态码和错误类型；
  • 请求使用的项目、模型 ID 和时间（不要记录完整输入中的隐私资料）；
  • 是否首次请求就失败，还是运行一段时间后失败；
  • 控制台显示的当前用量、速率和计费状态。

首次请求就 429，优先查项目配额、模型可用性和计费设置；运行一段时间后才 429，更像速率、并发或累计用量问题。

2. 用有限退避处理暂时性速率限制 ​

只对明确的速率或服务暂时错误做有限次数退避；401、403 和模型拼写错误不应重试。伪代码示例：

text
如果响应是 429 或服务端暂时错误：
  读取 Retry-After（如果有）
  按 1、2、4 秒等有限间隔重试，设置最大次数
否则：
  记录错误类型并停止重试，先修复配置

同时降低并发、限制输入长度、缓存可复用结果，避免把“重试”变成更快耗尽配额的循环。正式服务还应设置单用户限流和预算告警。

3. 配额够用但仍 429 ​

检查是否有多个应用共用同一项目、后台任务突然提高并发，或代码在超时后重复发送同一请求。为开发、预发布和生产环境分开项目或至少分开凭据与限流策略，便于定位消耗来源。

六、模型不可用、找不到或参数不支持 ​

1. 以当前模型列表为准 ​

模型可能新增、下线、改名，预览模型也可能改变访问条件。遇到 model not found、unsupported model 或参数错误时，回到 Gemini API 模型列表，确认：

  • 模型 ID 的完整拼写与大小写；
  • 当前 API 方法是否支持该模型；
  • 输入和输出模态是否匹配；
  • 模型是稳定版、预览版还是实验版；
  • 账号和项目是否能看到该模型。

不要只把名称中的 pro、flash 或日期片段拼接成模型 ID。AI Studio 的“代码获取”功能可以作为当前请求结构的起点，但上线前仍要检查 SDK 版本和错误处理。

2. 网页可用，代码却提示模型不可用 ​

AI Studio 页面可能使用了与你代码不同的项目、模型版本、系统说明或工具设置。逐项记录 AI Studio 当前选择，再与代码中的模型 ID、API 版本、内容格式和项目变量比较。不要仅复制页面标题；应复制官方示例中的实际模型字段。

3. 输出模态或功能不匹配 ​

图片、音频、视频、长上下文、结构化输出和工具调用并非所有模型都支持。先在模型列表核对能力，再用最小文本请求验证认证与基础连通性，最后逐项加回文件和工具。这样能区分“模型能力不支持”和“Key/配额故障”。

七、SDK、环境变量和最小请求检查 ​

Google 官方当前提供多种语言 SDK，包名和接口会变化。以 Node.js 新 SDK 的结构为例，模型 ID 应替换为 AI Studio 当前测试通过的值：

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

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const response = await ai.models.generateContent({
  model: "填写当前官方模型列表中的 ID",
  contents: "请用一句话说明 API 连通性。"
});

console.log(response.text);

最小请求只验证认证、项目和模型，不要一开始带入文件、工具、超长上下文和复杂 JSON。运行前检查：

  • 应用进程能读取 GEMINI_API_KEY；
  • SDK 版本与当前官方快速入门一致；
  • 模型 ID 来自当前模型列表；
  • 输入字段符合 SDK 当前类型；
  • 日志只记录状态、错误类型和 request ID，不记录 Key 与敏感内容。

完整参数以 Gemini API 快速入门和当前 SDK 文档为准。不要为了让旧代码“跑起来”而关闭 TLS 校验或把 Key 移到前端。

八、从现象到修复的快速决策表 ​

现象先做什么修复后怎么验证
401在应用同一进程确认变量存在，轮换疑似泄露/失效 Key最小文本请求返回正常响应
403核对项目、API 启用、组织策略和模型可见性管理员确认策略后重试同一请求
429查项目用量和速率，降并发并有限退避在低并发下连续完成少量请求
model not found从当前模型列表复制 ID，确认方法和版本使用最小请求验证模型
网页正常、代码失败对照项目、模型、设置、历史上下文和 SDK让 AI Studio 导出的最小代码先跑通
本地正常、部署失败检查部署平台环境变量和项目权限在部署环境运行一次脱敏健康检查

常见问题 FAQ ​

Gemini API Key 在哪里创建？ ​

登录 Google AI Studio 后进入 API Key 页面，按页面提示选择或创建 Google Cloud 项目。创建后记录项目对应关系，并把 Key 存入服务端环境变量。

AI Studio 网页测试需要 API Key 吗？ ​

网页工作区和程序调用是两个阶段。网页测试可以先验证提示词和模型；把能力接入自己的程序时，才需要按当前文档创建并配置 API Key。

为什么刚创建的 Key 也提示配额不足？ ​

配额通常按项目、模型、账号和时间窗口计算，不只看 Key 的创建时间。检查绑定项目、当前模型、已有应用用量、速率限制和计费状态；不要连续创建更多 Key。

429 应该一直重试吗？ ​

不应该。先确认是速率限制还是累计配额，再读取 Retry-After（如果返回）并设置有限次数退避。401、403、模型不存在等配置错误应停止重试。

为什么 API Key 放在前端不安全？ ​

浏览器里的代码和请求可以被访问者查看，Key 也可能被复制并消耗项目配额。让后端读取环境变量，再由后端调用 Gemini API，并为应用设置限流和预算监控。

AI Studio 有模型，代码却提示找不到？ ​

页面和代码可能使用了不同项目、模型 ID、API 版本或账号权限。回到当前模型列表核对完整 ID、支持的方法、稳定/预览状态和项目可见性，再用最小请求验证。

Key 泄露后只删除 Git 提交可以吗？ ​

不够。先在控制台撤销或轮换 Key，再检查调用记录和项目用量，最后清理代码、日志、缓存和 CI 变量，并补上密钥扫描。

官方来源 ​

继续阅读 ​

站群延伸阅读 ​

总结 ​

Gemini AI Studio 的 Key、配额和模型问题要分开处理：先确认 Key 是否加载，再核对项目与 API 权限，随后查看速率/总量配额和当前模型 ID，最后才检查 SDK 参数。用一个不含敏感数据的最小请求完成验证，并把 Key 留在服务端环境变量中，通常比反复重建密钥更快找到根因。

本站为独立中文教程与资料整理站，不代表 OpenAI、Anthropic、Google 或 xAI 官方立场。

内容仅供学习参考，请以相关服务官方页面和条款为准。