Gemini API 已付费仍报 free_tier_requests limit 0：按实际请求恢复

Gemini API 明明已付费，却返回 generate_content_free_tier_requests、limit: 0，先检查失败请求实际使用的 Key 所属项目，不要只看浏览器里某个项目的 Tier 1 标签。把运行配置指向正确的付费项目，完成该项目当前要求的计费或预付设置，再查看同一模型的有效配额，这是恢复请求的起点。

如果实际 Key、项目、模型、计费状态和有效配额已经对齐，仍稳定返回免费层零配额，就应停止反复建 Key、重新绑定计费或无限重试，保存脱敏错误并交给 Google 支持核查。RetryInfo 给出几秒后重试，也不会把原本为零的适用上限变成正数。

本文依据 2026 年 10 月 5 日核对的 Google 文档和有日期的用户报告更新；没有使用真实账户进行付款、改 Key 或 API 恢复测试。下面的控制台名称来自官方文档，实际账户可能处于不同的计费计划或迁移状态。

先确认零的是哪项限制

保存原始错误，找出 HTTP 状态、模型、quotaMetric、quotaId、quotaDimensions 和错误消息中的 limit。不同 SDK、API 和版本的展示格式并不一样，不能假定每次都有同一组 JSON 字段，更不能把 quotaValue 一律解释成“已使用次数”。

例如，2026 年 3 月的一条开发者论坛报告同时列出免费层请求、输入 token 的零限制，以及约三秒的 RetryInfo。这是该用户收到的错误，并非所有响应的通用模板。这里有用的判断是：错误明确指向免费层零上限时，应先核对请求归属和可用资格；如果实际限制为正、近期使用量已经达到它，才进入通常的限流恢复。

Gemini Developer API 的限制按项目执行，同项目多个 Key 共享配额；Key 没有独立计费设置，而是继承所属项目的计费状态。依据分别见 Google 速率限制文档和计费文档的项目与 Key 说明。

在失败的进程里找到生效 Key

先记下失败发生在终端、VS Code、Notebook、ADK Web、容器、CI 还是线上服务，同时记录请求域名、API 版本和精确模型 ID。若请求实际发往 Vertex AI 或第三方端点，应核对那条服务的认证与计费，不能拿 AI Studio Developer API 的页面代替。

对于使用环境变量自动取 Key 的 Gemini 客户端，官方规定：GOOGLE_API_KEY 与 GEMINI_API_KEY 同时存在时，GOOGLE_API_KEY 优先。如果代码显式传入 Key，或者框架从自己的配置、.env、部署 secret 中取值，还要检查那个来源。仅检查环境变量，不一定能证明最终传给客户端的是什么。Google API Key 配置说明

下面的 Python 代码只检查变量是否存在，不联网、不输出密钥。可以放在客户端初始化之前，观察实际应用进程的输出：

import os

has_google = bool(os.environ.get("GOOGLE_API_KEY"))
has_gemini = bool(os.environ.get("GEMINI_API_KEY"))
print("GOOGLE_API_KEY 已设置:", has_google)
print("GEMINI_API_KEY 已设置:", has_gemini)

if has_google:
    print("自动读取环境变量时，优先来源是 GOOGLE_API_KEY")
elif has_gemini:
    print("自动读取环境变量时，来源是 GEMINI_API_KEY")
else:
    print("这两个变量均未设置；继续检查显式 Key 和框架配置")

这段代码只能证明变量来源，不能从变量名推断项目。接着在 AI Studio API keys 中确认所用 Key 的关联项目，记录准确的 Project ID，再到 Projects 检查这个项目。不要把 Key 贴进日志、截图或论坛；需要团队协助时，使用内部的 Key 名称和项目标识核对。

如果发现取错了 Key，只修改造成错误的那个配置来源：例如部署 secret 仍指向测试项目，或者旧 GOOGLE_API_KEY 覆盖了新 GEMINI_API_KEY。修改后重新启动实际服务；Windows 修改持久环境变量后，也要打开新终端加载。浏览器切换项目、在另一个 PowerShell 窗口临时设置变量，都不会自动更新已经运行的服务。

LINUX DO 的一条中文讨论正好说明这种差别：2025 年 12 月，发帖者报告 PowerShell 和 VS Code 的 ADK Web 使用了不同环境，重新建 Key 没有帮助；修正环境后，错误变成了 503。这个个人案例可以提示检查进程配置，却不能证明 503 就代表付费配额验证通过或内容生成成功。

对照项目当前状态完成计费设置

现在检查的是上一步确认的项目。进入 AI Studio Projects，查看它的 Billing Tier 和 Status，再到 Billing 检查所关联计费账户的计划、付款与状态。

“买了 Gemini 订阅”“绑过信用卡”“另一个项目是 Tier 1”都不能代替这一步。API Key 属于项目，项目继承关联计费账户的状态；当前预付或后付计划也会改变恢复动作。Google 计费设置与状态说明

这些状态对应的动作来自官方当前计费文档。对于要求 Prepay 的账户，文档写明最低充值为 5 美元或等值当地货币；有些账户被分配 Postpay 或仍处于迁移过程，应以自己的计划和通知为准，不要假定所有账户都必须走同一充值流程。

预付余额归零与免费层零配额并不是同一件事。 当前文档说明，余额归零会让该计费账户下所有关联项目的 Key 停止服务，返回 HTTP 402；项目不会自动降回 Free Tier。若收到 402，处理余额而非给请求加退避；如果报错仍是 429 免费层零限制，继续核对请求和项目状态，不凭“以前充过值”断定根因。Prepay 说明及余额 FAQ

余额为正也不保证服务可用。计费账户月度上限、项目支出上限，以及关联 Cloud 账户其他服务的逾期款项，都可能影响访问。检查当前警告和支出控制项即可，不要把提高支出上限、解绑再绑定账户当成默认修复。涉及付款或账户更改时，应由有权限的负责人根据实际需求操作。

文本能用、图片报零：检查具体模型，不直接判定 Bug

先到 AI Studio 有效速率限制查看同一项目、准确模型和调用方式的限制，再核对官方定价页是否提供该模型的 Free Tier。用量层级、模型资格和实际剩余额度回答的是不同问题。

截至 2026 年 10 月 5 日，官方定价页对以下图片模型的免费层输入、输出均标为 Not available：

• gemini-3.1-flash-image；
• gemini-3.1-flash-lite-image；
• gemini-3-pro-image。

因此，另一个提供免费额度的文本模型能成功，并不能证明当前图片请求使用了付费项目，也不能证明图片模型获得了有效配额。要比较两个结果，必须确认它们来自相同进程、Key、项目和端点，并分别核对模型资格与限制。

同时检查是否还在调用旧模型或旧别名。Google 对 gemini-2.5-flash-image公布的停止服务计划是 2026 年 10 月 2 日，并提示迁移到 3.1 Flash Image 或 Flash Lite Image。这个日期已经过去；排查时应先按当前官方模型信息修正调用目标。公布的退役计划不是本文真实调用验证，也不能单独解释你收到的某条 429。

确实存在“文本能用、付费图片仍报零”的用户报告。例如这条论坛讨论的发帖者在 2026 年 9 月 7 日报告 Tier 1、Postpay 下 Flash Lite Image 返回免费层零限制，等待后仍失败；后续回复请求项目资料调查。可见帖子没有给出确认根因或解决结果，不能由此推导成“所有付费图片请求都遇到同一个持续 Bug”。

如果项目状态正常、目标模型有正的有效配额，实际请求仍被免费层零限制拒绝，已经具备升级给支持的理由。此时不要继续根据 Key 创建时间猜测“旧 Key 缓存”：官方说明 Key 继承项目状态，并没有要求每次启用计费都必须重建 Key。

什么情况下值得等待，怎样确认恢复

等待必须对应一个会随时间改变的条件。当前计费文档说付款或满足升级条件后，层级通常在约十分钟内反映；速率限制文档说 Free 到 Tier 1 通常立即生效。两者都不能作为“五分钟一定恢复”的承诺。银行转账可能需要数天确认，费用图表也可能延迟到一天或更久，图表暂时没有费用并不能证明计费未关联。计费处理时间

滚动支出限制按十分钟窗口评估，是否适用于你的账户与计费历史、账户状态有关；它与月度支出上限不同。要判断具体容量，使用 Google 当前速率限制说明和自己的有效限制，不复制固定 Tier RPM 或“付费每日无限”的旧表。

修正后，在原先失败的环境中，对原目标模型做一次最小、低输出请求；这可能产生费用，先确认你接受相应计费。保存请求时间、模型、项目、状态与脱敏响应。如果成功，再恢复小规模任务并观察，最后逐步恢复原负载。

成功返回内容说明那次请求可用，不会单独证明它属于付费项目；归属仍需与 Key、项目、计费状态和控制台记录对应。错误从零配额变成 503，只说明失败类型改变；按临时错误处理，不能宣布恢复。若已变成 403，转到按失败动作排查 Gemini API Key 权限，不要继续充值。

对于确认属于暂时性 429 或 5xx 的错误，可使用有次数上限的指数退避和抖动。官方 SDK 可能已有自动重试，先核对所用版本与设置，避免在外层叠加无限循环。Google 重试指南

状态一致仍报零，提交哪些证据

把证据对齐到同一次失败，支持才有机会判断“页面状态正确，实际执行却不一致”。准备以下资料：

• 带时区的发生时间、HTTP 状态和完整脱敏错误；
• 请求域名、API 版本、方法、精确模型 ID；
• 实际运行环境、SDK 版本、Key 配置来源与关联 Project ID；
• 同项目的 Billing Tier、Status、计费计划和付款确认状态；
• 同模型有效配额的截图或记录，以及对应时间的使用量；
• 若响应提供 request ID 或 trace ID，附上该标识；
• 每次只修改一项配置后，错误是否改变、是否成功返回内容。

付款、账户状态和迁移未完成的问题联系 Cloud Billing 支持；无法解释的模型配额执行问题可以在 Google AI 开发者论坛查询对应模型讨论或提交脱敏报告。项目等账户资料通过可信的私密支持渠道提供，公开帖子不要附完整 Key、账单敏感信息或用户提示词。

业务必须继续时，可以暂缓失败的图片任务，或使用团队已经验证过的其他模型、服务路线。文本模型可承接纯文本任务，却不能替代图片生成；另一条路线也有自己的费用、认证和限制，应单独验证，不能当作“自动修好这个项目”的证明。

常见问题

新建 API Key 能修复 free_tier_requests limit 0 吗？

只有它纠正了实际凭证或项目错误，才可能帮助恢复。相同项目中的新 Key 继承相同计费状态与配额，不会创建新的付费额度。若 Key 泄露、被封锁或认证限制不匹配，按那个错误处理；不要把重建 Key 当作零配额的通用开关。Key 与项目计费关系

我已经付费，为什么后台仍显示免费层限制？

先确认付款对应的项目就是失败 Key 的所属项目，再检查这个项目当前的计费计划和状态。付款未确认、Prepay 流程未完成、错误进程读取了另一个 Key，都需要不同动作；这些条件全部一致而仍报免费层零限制时，带证据联系支持。仅凭报错不能确认是哪一种原因。

按 RetryInfo 等了几秒，为什么仍然 limit 0？

重试提示不会创建模型资格或完成计费。它适用于可随时间恢复的请求条件；若适用上限仍是零，重复等待同样的秒数不会修正项目、Key 或模型资格。先完成上面的核对，只有正配额窗口耗尽或暂时服务错误，才使用有限重试。

同一项目多建几个 Key，能避免这类限制吗？

不能增加项目配额。Gemini Developer API 限制按项目执行；同项目不同进程、成员和 Key 的请求会共同消耗它。对于容量不足，降低并发、减少输入、等待正确窗口或申请适用配额；对于持续零配额，核对状态并升级支持。项目级速率限制