Gemini API 详解：Interactions、定价与速率限制

• Interactions API 围绕一个核心资源构建——Interaction，代表一次完整的对话轮次，是一份会话记录，按时间顺序包含全部执行步骤，比如模型的思考过程、工具调用及其结果，以及最终的模型输出。

  Interactions API overview

• 在后续调用中把已完成交互的 id 作为 previous_interaction_id 传入，就能继续这段对话；服务器会代你取回历史记录，不用自己重发。这种服务端状态管理是可选的——你也可以自己维护完整历史，以无状态方式使用。

  Interactions API overview

• previous_interaction_id 只保留对话历史；tools、system_instruction、generation_config 这类参数是"本次交互专属"的，如果想让它们持续生效，每一次新的交互都要重新指定。

  Interactions API overview

• 默认情况下 API 会存储 Interaction 对象（store=true），以支持服务端状态管理、后台执行和可观测性；可以按请求单独设置 store=false 来关闭。

  Interactions API overview

• 存储的交互记录，付费层保留 55 天，免费层保留 1 天。

  Interactions API overview

• 一共有三档方案——Free、Paid、Enterprise。Paid 解锁更高的速率限制、上下文缓存、Batch API（价格降低 50%）、访问 Google 最先进的模型，并且内容不会被用来改进 Google 的产品；Free 层的内容则可能被用来改进产品。

  Gemini API pricing

• 在标准（非批处理）付费层，Gemini 3.8 Flash 的输入价格是每百万 token 0.75 美元，输出（含思考 token）是每百万 token 3.75 美元，这个价格持续到 2026 年 12 月 31 日；从 2027 年 1 月 1 日起分别涨到 1.50 美元和 7.50 美元。

  Gemini API pricing

• 付费层的 Google 搜索联网每月包含 5,000 次免费搜索请求（在所有 Gemini 3.x 模型间共享），超出后每 1,000 次 14 美元；Google 地图联网也是同样的每月 5,000 次免费、超出后每 1,000 次 14 美元的结构。

  Gemini API pricing

• 付费层的 Batch API 对 Gemini 3.8 Flash 的定价大约是标准层的一半（2026 年 12 月 31 日之前，输入每百万 token 0.375 美元，输出 1.875 美元）。

  Gemini API pricing

• 速率限制按三个维度衡量——每分钟请求数（RPM）、每分钟 token 数（TPM）、每天请求数（RPD）——按项目计算，不是按 API 密钥；只要触碰其中任何一项就会触发速率限制错误，哪怕另外两项都还没超。

  Gemini API rate limits

• 每天请求数（RPD）配额在太平洋时间午夜重置；实验性和预览版模型的速率限制会更严格。

  Gemini API rate limits

• Gemini API 还会执行基于消费金额的速率限制，按滚动 10 分钟窗口评估；Tier 1 每 10 分钟上限 10 美元，Tier 2 是 50 美元，Tier 3 是 200 美元。超出会返回 429 RESOURCE_EXHAUSTED 错误。

  Gemini API rate limits

• 用量层级会随消费金额和账号历史自动升级——Tier 1 需要关联一个有效的结算账号（结算层上限 250 美元），Tier 2 需要累计支付 100 美元且距首次成功付款满 3 天（上限 2,000 美元），Tier 3 需要累计支付 1,000 美元且距首次成功付款满 30 天（上限 20,000 到 100,000 美元以上）。

  Gemini API rate limits

1. 先决定功能需不需要服务端历史（previous_interaction_id，默认 store=true），还是走无状态方式（store=false，自己重发历史）。
2. 如果用 previous_interaction_id，每次新调用都要重新指定 tools、system_instruction、generation_config——它们不会自动带过去。
3. 参考 Gemini 3.8 Flash 的定价表（2026 年底前输入 $0.75/1M、输出 $3.75/1M）估算成本，看看 Batch API 大约半价的费率是否适合你的场景。
4. 根据结算账号状态和付款历史，确认项目当前属于哪个用量层级，因为这决定了 RPM/TPM/RPD 和消费限额。
5. 遇到 429 错误时，分别检查 RPM、TPM、RPD 和滚动 10 分钟消费限额——任何一项单独超限都会触发这个错误。

• 在决定升级付费层之前，先估算一个 Gemini 3.8 Flash 集成每月大概要花多少钱。
• 设计一个多轮功能时，决定是用 previous_interaction_id 还是自己维护历史记录。
• 遇到 429 错误时，判断这是请求速率限制、token 速率限制，还是基于消费金额的限制。

• 以为 previous_interaction_id 也会带上上一轮的工具配置或 system instructions。它只保留对话历史——"本次交互专属"的参数每次都要重新传。
• 没意识到免费层的内容可能被用来改进 Google 的产品，而付费层不会——对于处理非公开数据的场景，这是个需要认真考虑的点。
• 只按 token 单价做预算，忘了 Google 搜索联网和 Google 地图联网在每月 5,000 次免费额度（Gemini 3.x 模型共享）用完之后是单独计费的。
• 把所有 429 错误都当成同一种请求速率问题处理。基于消费金额的速率限制返回的是同样的 429 RESOURCE_EXHAUSTED 错误，但解决方式不一样——需要放慢花费速度，而不只是重试请求。
• 以为存储的交互记录可以无限期取回。免费层保留期只有 1 天，即便是付费层也只有 55 天，不是永久保存。

一个 Interaction 里到底包含什么？

一次完整轮次的全部执行历史——模型的思考过程、工具调用及其结果，以及最终的模型输出，都挂在一个可以之后取回、或作为 previous_interaction_id 传入下一轮的 id 上。

必须让 Google 存储我的交互记录吗？

不是必须的。存储默认是开启的（store=true），用来支持状态管理、后台执行和可观测性，但可以按请求单独设置 store=false 关闭。

Gemini 3.8 Flash 到底多少钱？

在付费标准层，2026 年底之前是每百万输入 token 0.75 美元、每百万输出 token（含思考 token）3.75 美元，2027 年 1 月 1 日起价格翻倍。免费层不收 token 费用，但访问权限更受限。

明明没超过每分钟请求数上限，为什么还是收到了 429 错误？

速率限制不只看 RPM。也可能是每分钟 token 数限制、每天请求数限制，或者——如果你的用量层级有这一项的话——基于滚动 10 分钟窗口评估的消费金额限制。

怎么才能升到更高的用量层级？

层级会根据 Google Cloud 累计结算消费和账号历史自动升级——Tier 1 需要关联结算账号，Tier 2 需要累计支付 100 美元且距首次成功付款满 3 天，Tier 3 需要累计支付 1,000 美元且距首次成功付款满 30 天。

这些是本教程对照核验的官方页面。需要厂商的原始措辞时请直接查阅。

• Interactions API overview

  https://ai.google.dev/gemini-api/docs/interactions-overview.md.txt

• Gemini API pricing

  https://ai.google.dev/gemini-api/docs/pricing.md.txt

• Gemini API rate limits

  https://ai.google.dev/gemini-api/docs/rate-limits.md.txt

来源状态

• Gemini API 入门：一分钟内完成第一次调用获取 Gemini API 密钥、安装 SDK，用 Interactions API 完成第一次调用——这是 Google 自 2026 年 6 月起为所有新项目推荐的接口。
• Google AI Studio：写代码之前先把提示词试出来Google AI Studio 让你在浏览器里直接试模型、试提示词，试好了再拿到可用的代码。这篇讲清楚 Chat prompt、Run settings 和 Get code 是怎么配合的。
• 函数调用、Google 搜索联网与托管智能体用函数调用把 Gemini 接到真实的操作上，用 Google 搜索联网让它的回答有实时依据，再把开放式的多步任务交给托管智能体沙箱去完成。