如何使用 Gemini 3.8 Flash API：Interactions API、思考层级以及在 Apifox 中的首次调用

Google 于 2026 年 9 月 2 日发布了 Gemini 3.8 Flash，其 API 模型 ID 是纯字符串 gemini-3.8-flash，没有 preview 后缀。在 2026 年 12 月 31 日之前，它保留了 3.7 Flash 每百万输入 Token 0.75 美元、每百万输出 Token 3.75 美元的优惠价格。Google 将其描述为一个“更努力工作”的模型：在处理复杂任务时，它会采取更多的推理步骤并更频繁地调用工具，而这会体现在你的 Token 账单中。

本指南涵盖了实现完整集成的全流程：在 AI Studio 中获取密钥、通过 Interactions API（Google 目前针对 Gemini 3.x 的主要 API）发送第一个请求、大多数现有代码仍在使用且与之等价的旧版 generateContent 接口、thinking_level 在各自接口中的位置、流式传输，以及如何读取 thoughtsTokenCount 以便思考成本永远不会出乎你的意料。每次调用都是带有 JSON 的纯 HTTP 请求，因此在将其写入应用代码之前，你可以在 Apifox 中构建并检查每一个请求。

AI Coding 交流群

如果你也在用 AI 写代码，或者正在研究 Cursor、Claude Code 这些工具，欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流，还有各种新工具和新玩法。

要了解模型概览、基准测试以及变更内容，请先了解 Gemini 3.8 Flash 是什么。Google 的发布博客给出了官方说明。

Gemini 3.8 Flash API 一览

在编写代码之前，有两个细节需要特别注意。默认的思考层级是 medium，而不是 Gemini 3 Pro 上的 high。此外，根据官方定价页面，思考 Token 是按输出速率计费的，因此你选择的层级既是质量决策，也是成本决策。定价明细计算了每个任务的具体数值。

第 1 步：在 AI Studio 中获取 API 密钥

打开 Google AI Studio，使用 Google 账号登录，并在密钥页面创建一个 API 密钥。该密钥可立即在免费层级中使用，但受速率限制约束，并且 Google 表示免费层级的数据会“用于改进我们的产品”。绑定结算账户以升级到 Tier 1，从而获得生产级别的限制配额。

导出密钥，而不是将其硬编码粘贴到代码中：

export GEMINI_API_KEY="AIza..."

官方 Python SDK 会从环境中读取 GEMINI_API_KEY，因此 genai.Client() 不需要传参。可以使用 pip install google-genai 进行安装。

第 2 步：使用 Interactions API 发起首次调用

Google 现在将 Interactions API 作为调用 Gemini 3.x 模型的主要方式。请求是一个 JSON 对象：包含模型、input 以及可选的 generation_config（thinking_level 位于其中）。

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": "Explain HTTP caching in 3 sentences.",
    "generation_config": {"thinking_level": "medium"}
  }'

响应是一组执行步骤，而不是单条消息。模型的思考过程和工具调用都会作为步骤出现，而最后一步是包含最终文本的 model_output。在 Python 中，SDK 会帮你将这些步骤展平：

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain HTTP caching in 3 sentences.",
    generation_config={"thinking_level": "medium"},
)

print(interaction.output_text)

请无需设置 temperature、top_p 和 top_k。Google 对所有 Gemini 3 模型的官方建议是将 temperature 保持为默认值 1.0，因为降低该值“可能会导致循环或性能下降”。如果你是从旧模型复制的配置，这应当是你首先需要删除的代码。

步骤 3：使用 previous_interaction_id 进行多轮对话

Interactions API 默认在服务端保存对话状态。要继续对话，只需将上一条响应的 id 作为 previous_interaction_id，并仅与新的用户输入一同发送即可。你无需重新发送历史记录。

follow_up = client.interactions.create(
    model="gemini-3.8-flash",
    input="Now give one example of a Cache-Control header.",
    previous_interaction_id=interaction.id,
)
print(follow_up.output_text)

如果你的合规规则禁止服务端存储，请设置 store: false。折中方案是你需要自行管理状态，包括在每一轮对话中将收到的模型思考块（thought blocks）和思考签名（thought signatures）原封不动地发回。这与 3.8 Flash 函数调用指南中提到的容易引发错误的工具使用规则相同。

步骤 4：旧版 generateContent 路径

生产环境中的大多数 Gemini 代码仍在使用 generateContent。虽然 Google 将其称为“旧版（legacy）”，但它“仍获得全面支持”且没有停用日期，因此你目前无需重写任何代码。我们之前的 Gemini 3.7 Flash API 指南仅涵盖了此路径；3.8 Flash 的结构与之完全一致，只是思考设置的位置与 Interactions 中有所不同。

在 generateContent 中，思考层级使用小驼峰（camelCase）形式放置在 generationConfig.thinkingConfig.thinkingLevel 下：

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Explain HTTP caching in 3 sentences."}]}],
    "generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}
  }'

Python 中的等效实现使用了强类型配置对象：

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Explain HTTP caching in 3 sentences.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="low")
    ),
)
print(response.text)

如果你之前使用的配置将 thinking_budget 设置为整数，请将其替换为字符串枚举。在 Gemini 3 及更高版本中，candidate_count 也已被移除。包含每项修改的前后对比 JSON 的完整清单，可以在 3.7 到 3.8 Flash 迁移指南中找到。

以下是两套 API 对应功能的对比表格，方便你在两个 API 之间进行转换，无需重新阅读两份文档：

步骤 5：流式传输与读取思考成本

对于聊天界面，请将方法名更换为 streamGenerateContent 并添加 ?alt=sse 以获取服务器发送事件（Server-Sent Events），每个事件包含一个 candidates 的部分 chunk：

curl -N "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"List three HTTP caching headers."}]}]}'

无论是否使用流式传输，每个 generateContent 响应都以一个 usageMetadata 对象结尾。每次调用时均需读取该对象：

"usageMetadata": {
  "promptTokenCount": 12,
  "candidatesTokenCount": 84,
  "thoughtsTokenCount": 310,
  "totalTokenCount": 406
}

thoughtsTokenCount 是 3.8 Flash 上需要关注的数字。在优惠期内，思考 Token 按输出 Token 计费（每百万 Token 3.75 美元），并且 Google 指出该模型“可能会使用更多 Token 来最大化性能，特别是在较高的 effort level 下”。Artificial Analysis 在 high 级别下的索引运行中测得每个任务约 48k 输出 Token，比 3.7 Flash 多 30%，在单 Token 价格不变的情况下，将每个任务的成本从 $0.40 推高至 $0.58。其在 medium 和 low 级别下的运行成本分别为每个任务 $0.41 和 $0.24。思考级别指南将这些数字转化为针对每条路由的策略。

要查看模型的推理过程，请在 thinkingConfig 中添加 "includeThoughts": true。思考摘要会作为带有 "thought": true 标记的部分返回；在组装可见答案时跳过这些部分即可。

你在第一个小时内可能会遇到的错误

thinking_level: "minimal" 校验失败。 Gemini 3.8 Flash 仅支持 low、medium 和 high。发送 minimal 会返回 400 INVALID_ARGUMENT，并提示 “Thinking level MINIMAL is not supported for this model. Please retry with other thinking level.”（于 2026 年 9 月 3 日的实测调用中验证），解决办法只需将其改为 low。较旧的 3.x 配置和复制的代码片段通常是引发该问题的根源。

429 意味着你触及了对应层级（Tier）的限制，而不是 Bug。 速率限制页面解释了各个层级：免费层级受速率限制；关联结算账户即可解锁 Tier 1；Tier 2 需要消费满 100 美元且满 3 天；Tier 3 则需要消费满 1,000 美元且满 30 天。每个模型的每分钟请求数（requests-per-minute）和每分钟 Token 数（tokens-per-minute）数值仅在针对你账户的 AI Studio 速率限制页面上显示，因此请在该页面查看，而不要轻信博客文章中的数据。出现 429 时，请退避并重试；如果在低流量下频繁遭遇 429，请提升层级。对于离线任务，Batch API 是更好的解决方案：在优惠期内它提供 50% 的折扣（每百万 Token $0.375 / $1.875），并且拥有独立的排队 Token 限制：Tier 1 为 3M，Tier 2 为 400M，Tier 3 为 1B。Gemini 批处理模式指南展示了请求的格式。

函数结果缺少 call_id。 如果你使用了工具，在 3.8 Flash 上，每个 function_result (Interactions) 都必须同时包含 call_id 和 name，并且每个旧版 functionResponse 都必须包含匹配的 id 加 name。遗漏其中任何一个都会导致该轮次失败。

在上线前先在 Apifox 中测试这两个接口

一旦这两个请求在终端中运行成功，请将它们转移到整个团队都可以运行的地方。下载 Apifox，创建一个项目，并将上述两个接口添加为已保存的请求。养成以下四个习惯将会大有裨益：

• 切勿在请求中明文保留 Key。 将 GEMINI_API_KEY 添加为环境变量，并在 x-goog-api-key header 中将其引用为 {{GEMINI_API_KEY}}。这样保存的请求就不会包含密钥，而且在免费层 Key 与付费 Key 之间进行切换也只需修改一次环境。
• 对状态和 Token 用量添加断言。 添加一个状态码为 200 的断言，然后再添加一个 JSON Path 断言，确保 usageMetadata.thoughtsTokenCount 低于你为每个 Prompt 设置的上限。该上限就是你的成本回归警报：如果 Prompt 更新或模型静默变更导致思考 Token 增加，测试会在收到账单之前提前报错。SSE 测试指南涵盖了流式传输的变体，Apifox 会将其渲染为合并后的事件流，而不是原始分块（chunk）。
• 在所有三个级别上发送相同的 Prompt。 分别使用 low、medium 和 high 复制请求，并横向对比 thoughtsTokenCount 与响应时间。这样可以为你自己的 Prompt 提供真实的参考数据，而不是指标平均值。
• 使用定时任务。 将这些请求转化为测试场景并设置定时运行，这样无论是速率限制变更、校验规则调整（例如移除 minimal），还是 Token 异常飙升，都会直接呈现在报告中，而不是爆发在生产环境中。《如何在 Apifox 中设置 API 测试定时任务》一文详细介绍了具体配置。

Apifox 并不会去运行模型或替代 SDK。它为你提供的是一种可保存、可共享且可断言的 HTTP 调用机制，而这恰恰是大多数团队在系统出故障之前经常忽视的部分。

常见问题

新项目应该使用哪个接口？ 使用 Interactions API。虽然 Google 将 generateContent 称为旧版，且目前仍完全支持，但新功能会优先落地在 Interactions API 上，而且服务端状态可以让多轮对话的代码更简短。对于现有服务，在没有迁移理由之前可以继续保留 generateContent。

调用 Gemini 3.8 Flash 需要付费账号吗？ 不需要。免费的 AI Studio Key 即可使用，但受限于速率限制和 Google 的数据使用条款。免费使用指南列出了免费层级包含和不包含的内容，包括 Gemini App 需要 AI Pro 或 Ultra 订阅计划才能使用 3.8 Flash。

3.8 Flash 比 3.7 Flash 更慢吗？ 从单个 Token 来看，并不更慢。Google 的 Logan Kilpatrick 表示两者速度大致相同，Artificial Analysis 实测约为每秒 300 个输出 Token。但从单项任务来看，在设置为 high 时耗时更长（在他们的测试中为 2.5 分钟对比 2.2 分钟），因为它生成了更多的 Token。

我可以继续调用 Gemini 3.7 Flash 吗？ 可以。Google 表示 3.7 Flash “仍处于完全支持状态”，且尚未发布任何弃用日期。如果在你的工作负载中，3.8 Flash 增加的 Token 开销未能带来额外的收益，那么维持现状是一个合理的选择。

3.8 Flash 是否支持 Live API 或图像生成？ 不支持。它仅支持纯文本输出。该模型不支持音频生成、图像生成以及 Live API。

下一步

现在，你已经拥有了两条可用的调用路径、一种多轮对话模式以及 Token 使用量检查机制。在此基础上，你可以结合 function calling 指南接入工具，参考思考层级（thinking levels）文章来决定各个路由的配置；如果你还在犹豫是否要进行迁移，3.8 与 3.7 Flash 的对比分析已为你清晰梳理了其中的权衡与取舍。请保持 Apifox 测试场景持续运行，这样一旦发生成本偏离，就会直接体现为测试失败。

开发必备：API 全流程管理神器 Apifox

介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集 API 文档、调试、设计、测试、Mock、自动化测试于一体的工具，Apifox 是目前提升研发效率的首选。

如果你正在开发项目，不妨试试其极其友好的界面设计，它完全兼容 Postman 和 Swagger 数据格式，导入数据非常方便，，即使是新手也能很快上手，点击这里即可注册使用。

值得一提的是，除了个人和常规团队使用，针对有高安全合规要求、或需要在内网环境协作的企业，Apifox 还提供了深度定制的私有化部署方案。

获取专属报价与部署方案

详细的私有化部署系统架构与安全白皮书

针对您公司规模的专属报价单

免费的 1v1 专属产品演示 (Demo) 机会

获取部署方案

* 提交后，我们的客户经理将在 1 个工作日内与您联系

林俊锋 企业微信

@Apifox 专属顾问

扫码备注: 私有化 + 公司名