Google AI Studio 免费 API 密钥

很多人拿到 Google AI Studio 的免费密钥后卡在同一个地方：Key 存好了，代码跑起来却报鉴权失败或没反应，不知道是密钥没生效、环境变量没读到，还是请求写法不对。这篇按工程落地顺序走一遍——申请、存放、第一次调用、出错怎么查，让你在十分钟内确认链路真的通了，而不是对着屏幕猜。

拿到 Google AI Studio 的免费密钥，卡住的地方基本不在申请，而在配置和第一次调用。Key 明明存好了，跑起来却报鉴权失败，或者干脆没反应，你分不清是密钥没生效、环境变量没读到，还是请求写法不对。

这篇按工程落地的顺序走一遍：怎么申请、怎么存、怎么写第一个最小请求、出错先查哪里。目标是十分钟内确认这条链路真的通了，而不是对着屏幕猜。免费档的用量限制和具体额度会变，需要数字时到站内 /official-api 看当时说明。

拿到 Key 之后第一件事：别写进代码

申请入口在 Google AI Studio 控制台里，登录后按引导创建密钥。创建完成那一刻是唯一一次完整显示，先把整串复制进密码管理器，再关页面——很多人关完才想起来没存，只能删掉重建。

1. 创建并立即落库在控制台按引导生成密钥，复制到密码管理器或者本地加密笔记，确认能粘贴出来再关闭页面。
2. 放进环境变量本地开发用 .env 或系统环境变量，代码里只读变量名，不写字符串字面量。顺手把 .env 加进 .gitignore。
3. 检查有没有漏出去已经提交过的仓库要清历史记录，然后把这把 Key 停用重发。别指望删掉那一行就算完，历史里还在。
4. 按人发 Key小团队协作别共用一把，每人一把、按人命名，出问题时能直接定位到是谁的用量异常。

免费档的配额和速率限制会调整，别把某篇旧文章里的数字当当前事实。需要准确数值时，到 /official-api 核对当时的官方说明。

用最小请求确认链路通不通

第一次调用不要接进项目，写十行以内的脚本，或者直接用一条命令行请求，只发一句最简单的话。目的是把变量压到最少，让失败点一眼可见。下面是命令行发请求的形状，Key 从环境变量读：

export GOOGLE_AI_KEY="你的密钥"
curl -s -X POST "接口地址" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GOOGLE_AI_KEY" \
  -d '{"contents":[{"parts":[{"text":"说一句你好"}]}]}'

• Key 从环境变量读，不要硬编码，这一步能提前暴露大部分配置问题。
• 先只发一句话，跑通后再加流式、多轮对话、图片输入，一次只加一个变量。
• 响应体里如果带错误结构，先看错误码和错误信息字段，不要只看 HTTP 状态。
• 拿到正常响应后，再回头确认输出内容和你的输入对得上，避免请求发错端点。

延迟基线可以用 /tools/speed-test 量一遍，记下当时的数值。以后你觉得变慢了，才有对照，而不是凭感觉判断。

没反应或报错时的排查顺序

报错的类别不同，处理路径完全不一样。按下面的顺序查，不要跳步：先确认鉴权字段，再区分错误类型，再查网络，最后才怀疑代码逻辑。

鉴权类报错和权限类报错原因不同，别混着猜。具体对照可以看站内 /401-vs-403-api-errors，那篇把两类错误的差别和对应动作拆开了。

另外确认网络出口能到达服务端。本地开着代理、公司网络有白名单、容器里没配 DNS，都会让请求静默失败。换一台机器或换一个网络试一次，能快速排除这一层。

免费档要提前想好的几件事

链路通了只是起点。免费档有速率上限，代码要默认带退避重试，别让失败请求原地打转；同时给 Key 的调用量加一层简单计数或日志，用量异常时能第一时间发现。

• 重试要带指数退避和上限次数，不要无限循环，否则容易把额度打满。
• 把用量写进日志或简单计数器，定期看一眼，异常增长往往先于报错出现。
• 不要把免费 Key 直接放进前端或移动端，客户端能被人翻出来；要用就加一层自己的服务端转发。
• 在代码里留一个切换点，免费额度不够或策略调整时，能换到另一家而不改业务逻辑。

什么情况下这套做法不适用：如果这是对外正式产品、有明确的可用性承诺，免费档本身就不该作为唯一依赖，降级路径要在上线前就准备好，而不是等出问题再补。