Gemini 3.7 Flash API 配置教程：价格、模型参数与第一个 Agent

摘要：Google 已于 2026 年 8 月 13 日正式推出 Gemini 3.7 Flash，并将其定位为 Gemini 3 系列面向编码、复杂工作流和 AI Agent 的主力 Flash 模型。对于准备调用 Gemini API、开发工具型 Agent、自动化工作流或企业应用的开发者来说，3.7 Flash 当前最值得关注的变化不是单纯“模型更聪明”，而是 Agent 执行、函数调用、多步骤规划、长上下文和单位成本之间的平衡进一步改善。本文从零开始讲清 Gemini 3.7 Flash API Key 配置、最新价格、上下文和 Thinking 参数、Interactions API，并通过一个完整的 Function Calling 示例搭建第一个可调用外部工具的 Agent。

核心结论

如果你正在新建 Gemini API 项目，尤其是准备开发 AI Agent、编程助手、企业自动化或多步骤工具调用工作流，Gemini 3.7 Flash 已经可以直接作为首选 Flash 模型测试。官方模型 ID 为 gemini-3.7-flash，并且 Google 已明确建议新项目优先使用 Interactions API，而不是继续围绕旧的 generateContent 接口设计新的 Agent 架构。

• 模型已经 GA：Gemini 3.7 Flash 于 2026 年 8 月 13 日正式发布，可用于生产环境，不是 Preview 模型。
• Agent 是重点：Google 将 3.7 Flash 定位为面向 coding、agentic workflows 和可靠多步骤执行的主力 Flash 模型。
• 上下文足够大：上下文窗口为 1,048,576 Token，最大输出为 65,536 Token，适合大型代码库、PDF、知识库和长任务链。
• 推理参数发生变化：建议使用 thinking_level，可选 low、medium、high，默认 medium；3.7 Flash 不支持 MINIMAL。
• 目前价格非常关键：2026 年 12 月 31 日前 Standard API 优惠价为输入 $0.75/百万 Token、输出 $3.75/百万 Token；2027 年 1 月 1 日起计划恢复至 $1.50 和 $7.50。

因此，如果你的目标只是大批量分类、翻译、字段抽取，Flash-Lite 仍可能更经济；但如果一个任务需要“理解 → 判断 → 调工具 → 根据工具结果继续执行 → 输出最终结果”，Gemini 3.7 Flash 更符合 Agent 型工作负载。

Gemini 3.7 Flash 是什么，为什么这次更新值得关注

Gemini 3.7 Flash 属于 Gemini 3 系列的原生多模态推理模型。Google 在发布时没有单纯强调聊天质量，而是把重点放在软件工程、Web 开发、知识工作以及 Agentic Workflow 上。官方将其描述为目前最强的 Flash 级 Agent 工作模型之一，目标是在 Pro 级复杂推理能力和 Flash-Lite 级高吞吐之间建立一个更适合生产环境的平衡点。

这也是为什么 Gemini 3.7 Flash 对实际开发者的意义，可能比一次普通模型版本升级更大。传统 LLM API 常见调用模式是：

输入 Prompt → 模型生成答案 → 请求结束

但 Agent 的工作方式更接近：

接收目标 → 分析任务 → 选择工具 → 调用 API → 获得结果 → 再推理 → 必要时继续调用工具 → 输出结果

当一次任务包含多个工具、多轮状态和大量上下文时，模型第一次选择正确工具的概率、工具参数准确率、失败后的恢复能力和 Token 消耗，都会直接决定 Agent 是否能真正进入生产环境。

Google 官方公布的信息显示，3.7 Flash 相比 3.6 Flash 在代码调试、Issue Resolution、Web 开发以及企业自动化任务上都有明显改进。这里需要注意：官方 Benchmark 可以帮助判断模型发展方向，但不能直接等价为你的业务系统一定会获得相同比例的提升。对于企业内部 Agent，仍建议使用自己的测试集做回归评测。

Gemini 3.7 Flash 最新价格怎么计算

Gemini API 不是简单按照“调用一次多少钱”收费，核心计费单位仍然是 Token，同时还要考虑 Thinking Token、Context Caching、Google Search Grounding、Google Maps、Batch 或 Priority 等不同调用模式。

Standard 标准调用价格

计费项目	截至 2026-12-31	2027-01-01 起
输入 Token	$0.75 / 100 万 Token	$1.50 / 100 万 Token
输出 Token（含 Thinking Token）	$3.75 / 100 万 Token	$7.50 / 100 万 Token
Context Caching	$0.075 / 100 万 Token	$0.15 / 100 万 Token
缓存存储	$0.50 / 100 万 Token/小时	$1.00 / 100 万 Token/小时

这里最容易忽略的一点是：Thinking Token 被计入输出 Token。也就是说，把 thinking_level 从 low 调整到 high 后，不能只看最终显示给用户的文字长度，还要关注模型内部推理所产生的计费 Token。

用一个实际例子计算 API 成本

假设一个 Agent 平均每次任务消耗 10,000 个输入 Token，并产生 2,000 个计费输出 Token。按照 2026 年优惠价格计算：

输入成本 = 10,000 ÷ 1,000,000 × $0.75 = $0.0075

输出成本 = 2,000 ÷ 1,000,000 × $3.75 = $0.0075

因此理论成本约为 $0.015/次，1,000 次约 $15。到 2027 年标准价格生效以后，在 Token 使用量完全不变的情况下，同一工作负载理论成本约为 $0.03/次。

这里只是用于理解计费方式的估算。真实 Agent 可能因为工具调用、多轮对话、Thinking Token、搜索请求和上下文增长而产生更多费用。因此生产环境不要只统计“最终答案 Token”，而应记录每个 Interaction 的 Usage。

Batch、Flex 和 Priority 怎么选

截至本文核验日期，Gemini 3.7 Flash 的 Batch 和 Flex 在优惠期内输入均为 $0.375/百万 Token、输出为 $1.875/百万 Token；Priority 则明显更贵。对于不要求立即返回结果的离线任务，例如批量摘要、数据分类、日志分析、内容标签生成，可以重点评估 Batch。实时聊天、在线 Agent 通常首先使用 Standard；对延迟和服务优先级有明确 SLA 要求时，再评估 Priority。

如果你正在设计批量 AI 自动化，可以继续查看 AI Stack Nav 的 Gemini API 相关教程，把实时调用和批处理任务拆成不同队列，通常比所有请求都走同一种推理模式更经济。

Gemini 3.7 Flash 模型参数：不要照搬旧版 Gemini 示例

Gemini 3.7 Flash 的一个重要变化是参数配置正在从传统采样参数转向更明确的“推理强度控制”。如果你从旧 Gemini 项目升级，不能简单把旧配置原样复制过来。

参数/能力	Gemini 3.7 Flash	使用建议
Model ID	gemini-3.7-flash	生产配置中显式指定
Context Window	1,048,576 Token	长文档、代码库、Agent 状态可充分利用
最大输出	65,536 Token	不要因为上限高就默认要求超长输出
thinking_level	low / medium / high	默认 medium
MINIMAL	不支持	设置后可能触发参数校验错误
Structured Output	支持	适合 JSON、表单和工作流节点
Function Calling	支持	构建 Agent 的核心能力
Google Search / Maps	支持	适合实时信息 Agent
Code Execution	支持	适合计算与数据分析
Computer Use	支持，Preview	生产使用前应单独验证稳定性
模型 Tuning	不支持	通过 Prompt、工具、RAG 等方式适配

thinking_level 应该怎么选

low：适合响应速度比深度推理更重要的任务，例如简单客服分类、文案初稿、快速数据解释、部分实时聊天场景。

medium：这是默认值，也是多数开发者最适合的起点。普通代码生成、工具选择、结构化工作流和中等复杂度 Agent 建议先用 medium 建立基线。

high：适合复杂代码审查、困难数学问题、多步骤规划以及需要多个工具协作的 Agent。它可能获得更强推理能力，但往往伴随更高延迟和更多 Thinking Token，因此不建议“所有请求全部 high”。

更合理的生产策略是按照任务复杂度路由。例如普通问题使用 low，中等任务使用 medium，只有代码修复、复杂决策或失败重试才升级到 high。

temperature、top_p、top_k 还要不要设置

这里尤其容易踩坑。Google 当前针对 Gemini 3.7 Flash 的迁移指南明确要求，从部分旧模型迁移时应移除 temperature、top_p 和 top_k 等已弃用的采样参数，并把旧的 thinking_budget 迁移为 thinking_level。

因此，新项目不建议复制旧版 Gemini 2.x 或早期 Gemini 3 示例中的一大串采样参数。先保持最小配置，只有官方当前接口明确支持且你的评测证明有价值时，再添加额外参数。

为什么新项目应该优先使用 Interactions API

2026 年 Gemini API 架构中最值得开发者关注的并不只是模型名称，而是 Interactions API。Google 已将其定义为构建 Gemini 模型和 Agent 的推荐接口，并表示新模型、多模态能力、工具和 Agentic 功能将优先在这一接口上推出。

传统 generateContent 并没有立即失效，官方仍然支持它，但对于全新 Agent 项目，Interactions API 的优势非常明显：

• 单一接口既可以调用普通 Gemini 模型，也可以调用专业 Agent。
• 原生支持工具编排和 Function Calling。
• 可以使用 previous_interaction_id 保存多轮任务状态。
• 可以看到执行步骤，便于调试 Agent 到底在哪一步失败。
• 支持长任务和 Background Execution。
• 服务器端状态管理有机会提高多轮上下文缓存命中率。

换句话说，过去开发者经常需要自己维护 Messages 数组、重复拼接历史上下文；Interactions API 开始把“Interaction”本身变成一个可持续管理的任务对象。

第一步：创建 Gemini API Key

配置 Gemini 3.7 Flash 并不需要先搭建复杂的 Google Cloud 架构。个人开发和原型阶段，可以直接从 Google AI Studio 创建 API Key。

1. 进入 Google AI Studio 的 API Key 页面。
2. 选择已有 Google Cloud Project，或者创建新项目。
3. 创建 Gemini API Key。
4. 不要把 Key 写死在 Python、JavaScript 或 GitHub 仓库中。
5. 将 API Key 保存到系统环境变量 GEMINI_API_KEY。
6. 生产环境启用 Billing、预算告警、Key 管理和调用日志。

Linux 或 macOS 可以设置：

export GEMINI_API_KEY="YOUR_API_KEY"

如果使用项目级 .env：

GEMINI_API_KEY=YOUR_API_KEY

同时应把 .env 写进 .gitignore：

.env
.env.*
*.key

尤其是在制作 Agent Demo 时，不要为了“示例方便”直接写：

client = genai.Client(api_key="AIza......")

代码一旦被提交到 GitHub、打包给客户或者写入日志，API Key 就可能泄露。开发环境和生产环境也建议使用不同凭据。

第二步：安装 Google Gen AI SDK 并完成第一次调用

Python 项目首先安装官方 SDK：

pip install -U google-genai

然后建立 hello_gemini.py：

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.7-flash",
    input="请用三句话解释什么是 AI Agent。"
)

print(interaction.output_text)

运行：

python hello_gemini.py

如果能够正常输出内容，说明至少以下四个环节已经打通：

1. Python 环境正常。
2. google-genai SDK 正常安装。
3. GEMINI_API_KEY 已被客户端读取。
4. gemini-3.7-flash 当前项目具有访问权限。

加入 thinking_level

接下来可以明确指定推理等级：

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.7-flash",
    input="分析一个电商订单系统中可能出现的重复扣款问题，并给出排查顺序。",
    generation_config={
        "thinking_level": "medium"
    }
)

print(interaction.output_text)

初学者不建议一开始就把所有任务设置成 high。更合理的方法是先建立 medium 基线，再比较成功率、延迟和 Token 消耗。

第三步：从“聊天机器人”升级成第一个 Agent

只让 Gemini 回答问题还不能充分体现 Agent 的价值。Agent 最重要的能力之一，是根据任务自主判断是否调用外部工具。

下面建立一个简单的“订单查询 Agent”。模型自身不知道企业内部订单 A102 的状态，因此我们向 Gemini 声明一个 get_order_status 工具。当用户询问订单时，Gemini 不应该编造状态，而应生成 Function Call。

from google import genai

client = genai.Client()

order_tool = {
    "type": "function",
    "name": "get_order_status",
    "description": "查询指定订单的最新状态",
    "parameters": {
        "type": "object",
        "properties": {
            "order_id": {
                "type": "string",
                "description": "订单编号，例如 A102"
            }
        },
        "required": ["order_id"]
    }
}

def get_order_status(order_id):
    demo_orders = {
        "A102": {
            "status": "已发货",
            "carrier": "Demo Express",
            "tracking_number": "DEMO-20260819-001"
        }
    }

    return demo_orders.get(
        order_id,
        {"status": "未找到订单"}
    )

first = client.interactions.create(
    model="gemini-3.7-flash",
    input="帮我查询订单 A102，并告诉我目前进展。",
    tools=[order_tool],
    generation_config={
        "thinking_level": "medium"
    }
)

function_call = next(
    (step for step in first.steps if step.type == "function_call"),
    None
)

if not function_call:
    print(first.output_text)
else:
    tool_result = get_order_status(
        **function_call.arguments
    )

    final = client.interactions.create(
        model="gemini-3.7-flash",
        previous_interaction_id=first.id,
        input=[
            {
                "type": "function_result",
                "name": function_call.name,
                "call_id": function_call.id,
                "result": tool_result
            }
        ],
        tools=[order_tool]
    )

    print(final.output_text)

这个示例虽然很短，但已经具备 Agent 的基本闭环：

1. 用户给出自然语言目标。
2. Gemini 判断需要查询订单系统。
3. Gemini 生成结构化 Function Call。
4. 你的 Python 程序真正执行企业函数。
5. 程序把 Function Result 返回给 Gemini。
6. Gemini 根据真实工具结果组织最终回复。

关键点在于：Gemini 决定“调用哪个工具以及使用哪些参数”，而实际业务动作仍由你的应用程序执行。这正是生产 Agent 中非常重要的安全边界。

把第一个 Agent 扩展成真实工作流

掌握 Function Calling 后，就可以逐渐把单工具 Agent 扩展为真实业务系统。例如给模型增加以下工具：

• search_customer()：查询客户资料。
• get_order()：查询订单。
• query_inventory()：检查库存。
• create_ticket()：创建售后工单。
• send_notification()：发送通知。

用户只需要说：“客户说昨天购买的设备还没发货，帮我查一下，如果缺货就创建售后工单。”

真正的 Agent 可能依次执行：

识别客户 → 找到订单 → 查询物流 → 查询库存 → 判断异常 → 创建工单 → 返回处理结果

这时，Gemini 3.7 Flash 的价值就不再是“写一段更好的回答”，而是承担任务规划和工具编排层。

如果准备继续搭建类似系统，可以参考 AI Stack Nav 的 AI Agent 与自动化工作流教程，进一步加入 MCP、数据库、n8n、Dify 或企业内部 API。

Google Search、Function Calling 和 Code Execution 如何组合

Gemini API 提供的 Tool 大致可以分为两类。

Google 托管工具

例如 Google Search、Google Maps、Code Execution、URL Context 和 File Search。部分工具由 Google 服务端直接执行，模型可以在一个 Interaction 中调用并使用结果。

自定义 Function Calling

例如订单系统、CRM、ERP、数据库、WordPress、企业审批 API 等。这些工具真正执行的位置是你的服务器，因此你可以控制身份验证、权限、审计以及是否允许某个操作。

Gemini 3 系列还支持组合内置工具和自定义 Function Calling。例如一个商业 Agent 可以先通过 Google Search 获得公开市场信息，再调用内部 CRM 获取客户数据，最后调用企业报价函数生成方案。

不过，官方目前仍将部分“内置工具 + 自定义工具组合”能力标记为 Preview。因此，对涉及付款、删除数据、发送正式邮件、创建订单等高风险动作，不应只依赖模型自主判断。

生产 Agent 必须增加的 7 个安全层

演示代码能够跑通，不等于可以立即上线。如果 Agent 可以操作真实业务系统，至少建议增加以下控制：

1. 最小权限：每个工具只开放执行当前任务所必需的权限。
2. 参数校验：不能直接相信模型产生的 Function Arguments。
3. 人工审批：付款、删除、发信、发布、账号变更等高风险动作增加 Approval Gate。
4. 调用超时：所有外部工具必须有 Timeout 和 Retry 上限。
5. 幂等控制：避免 Agent 重试时重复付款、重复发邮件或重复创建订单。
6. 日志审计：记录 Interaction ID、工具名称、参数摘要、执行状态和错误原因，但不要记录 API Key。
7. 成本限制：限制最大循环次数、最大 Token 和单任务预算，防止 Agent 陷入无限工具调用。

对于 Agent 来说，“模型能力更强”并不能替代安全架构。越能自主调用工具的模型，越需要把权限、审批、审计、超时和回退机制放到模型之外。

Gemini 3.7 Flash、3.6 Flash 与 Flash-Lite 怎么选

模型	更适合的任务	选择建议
Gemini 3.7 Flash	复杂 Agent、Coding、多步骤工具调用、多模态推理	新建 Agent 项目优先测试
Gemini 3.6 Flash	已有稳定 3.6 工作流	不必盲目切换，先做回归测试
Gemini 3.5 Flash-Lite	高吞吐、翻译、分类、简单数据处理、轻量子 Agent	成本敏感的大批量任务优先测试

截至 2026 年底，3.7 Flash 和 3.6 Flash 都享受同一档促销价格。因此对于新项目，3.7 Flash 的吸引力非常明显。但如果你的应用已经在 3.6 上通过完整评测并稳定运行，仍建议使用同一测试集比较准确率、工具成功率、延迟、输出 Token 和成本之后再迁移。

另一方面，把所有子任务都交给 3.7 Flash 也不一定是最经济的架构。成熟的多 Agent 系统往往会根据任务复杂度进行模型路由：复杂规划交给 3.7 Flash，大批量简单节点交给 Flash-Lite，从而控制总体 Token 成本。

常见报错与排查顺序

1. API Key 找不到

如果 SDK 提示缺少凭据，首先检查当前终端能否读取 GEMINI_API_KEY。修改环境变量后通常需要重新打开 Terminal 或重新启动服务。

2. Model not found

确认模型字符串使用的是 gemini-3.7-flash，不要继续填写早期 Preview 模型名称。同时检查项目、地区和账户权限。

3. thinking_level=MINIMAL 报错

Gemini 3.7 Flash 不支持 MINIMAL。改用 low、medium 或 high。

4. 从旧项目迁移后参数校验失败

检查是否还保留 temperature、top_p、top_k、candidate_count 或旧式 thinking_budget。按照当前 Gemini 3.7 Flash 迁移指南清理旧参数。

5. Function Call 出现但没有最终答案

Function Calling 并不意味着 Google 会自动执行你的企业函数。应用程序必须识别 function_call、执行真实函数，并将带有匹配 call_id 的 function_result 返回模型。

6. Agent Token 消耗突然升高

检查 Thinking Level、历史 Interaction、工具返回内容长度、重复失败重试以及是否把大型文档反复重新发送。高 Thinking Level 和长工具结果都可能显著增加成本。

适合哪些用户立即使用

Gemini 3.7 Flash 最值得以下几类开发者优先测试：

• 正在开发 Coding Agent 或自动修复代码工作流的团队。
• 需要连接 CRM、ERP、数据库、搜索或企业 API 的业务 Agent。
• 需要分析大量 PDF、图片、视频和长文档的多模态系统。
• 已经使用 Gemini 3.5/3.6 Flash，准备提升工具调用和复杂任务稳定性的项目。
• 希望使用 Interactions API 构建多轮、有状态 Agent 的开发者。

如果只是做简单摘要、分类或批量字段提取，则没有必要因为“版本号更高”就全部切换到 3.7 Flash。应同时测试 Flash-Lite，并按“成功完成一次任务的实际成本”而不是单纯模型 Benchmark 做选型。

事实依据与来源

本文所涉及的模型名称、发布日期、价格、上下文窗口、最大输出 Token、Thinking Level、API 架构以及 Function Calling 能力，均以 Google 官方 Gemini API、Google Cloud 和 Google 官方发布信息为主要依据。

• 官方已确认：Gemini 3.7 Flash 于 2026 年 8 月 13 日 GA，模型 ID 为 gemini-3.7-flash。
• 官方已确认：上下文窗口为 1,048,576 Token，最大输出 Token 为 65,536。
• 官方已确认：thinking_level 支持 low、medium、high，默认 medium；3.7 Flash 不支持 MINIMAL。
• 官方已确认：2026 年 12 月 31 日前 Standard 优惠价为输入 $0.75/百万 Token、输出 $3.75/百万 Token；2027 年 1 月 1 日起计划调整为 $1.50/$7.50。
• 官方已确认：Interactions API 已成为 Google 推荐的新项目 Gemini 模型和 Agent API。
• 编辑建议：模型路由、Approval Gate、权限隔离、Retry、幂等控制及不同 Thinking Level 的业务选型属于生产实施建议，应结合实际项目测试。
• 待实际项目验证：Gemini 3.7 Flash 在具体企业知识库、CRM、内容生产、代码仓库和多 Agent 系统中的成功率、延迟及综合成本。

内容核验日期：2026 年 8 月 19 日。

FAQ

Gemini 3.7 Flash 的模型 ID 是什么？

Gemini API 当前正式模型 ID 为 gemini-3.7-flash。该模型已于 2026 年 8 月 13 日 GA，可以用于生产应用。旧项目迁移时不要仅修改显示名称，应检查完整 API 参数和工具调用格式。

Gemini 3.7 Flash API 是免费的吗？

Google Gemini Developer API 当前提供 Free Tier，具体可用额度和 Rate Limit 会受项目、模型和账户状态影响。生产应用需要根据实际调用量升级 Paid Tier，并建议配置预算与使用量监控。

Gemini 3.7 Flash API 现在多少钱？

截至 2026 年 12 月 31 日，Standard Paid Tier 的官方优惠价格为输入 $0.75/百万 Token、输出 $3.75/百万 Token，输出计费包含 Thinking Token。自 2027 年 1 月 1 日起，Google 当前公布的标准价格为输入 $1.50、输出 $7.50/百万 Token。

Gemini 3.7 Flash 支持多长上下文？

官方模型规格给出的 Context Window 为 1,048,576 Token，最大输出为 65,536 Token。长上下文并不意味着每次请求都应该塞满窗口，生产系统仍应使用检索、缓存和上下文裁剪控制延迟与费用。

Gemini 3.7 Flash 的 thinking_level 怎么设置？

当前支持 low、medium 和 high，默认值为 medium。简单低延迟任务可测试 low，普通 Agent 建议从 medium 开始，复杂编码、数学和多工具任务再测试 high。

Gemini 3.7 Flash 支持 MINIMAL Thinking 吗？

不支持。Google 官方模型文档明确指出，Gemini 3.7 Flash 的 Thinking Level 只有 LOW、MEDIUM 和 HIGH。如果显式提交 MINIMAL，可能返回 API 参数验证错误。

现在还应该继续使用 generateContent API 吗？

已有系统无需因为 Interactions API 发布就立即重写，因为 Google 仍支持 generateContent。但对于 2026 年新建的 Gemini Agent 项目，官方已经推荐优先采用 Interactions API，新工具和 Agentic 功能也将重点围绕该接口发展。

Function Calling 就等于完整 Agent 吗？

不是。Function Calling 只是 Agent 的关键组成部分。真正可用于生产的 Agent 还需要任务状态、工具执行、权限、错误恢复、重试、审批、日志审计、成本控制和安全策略。

Gemini 3.7 Flash 和 Flash-Lite 应该选哪个？

如果任务需要复杂推理、编码、多步骤规划和多工具调用，优先测试 Gemini 3.7 Flash；如果任务主要是翻译、分类、字段抽取和大批量简单自动化，则应同时测试 Flash-Lite，并比较每个成功任务的综合成本。

参考来源

• Google AI for Developers：Gemini 3.7 Flash 模型规格
• Google AI for Developers：What’s new in Gemini 3.7 Flash
• Google AI for Developers：Gemini Developer API Pricing
• Google AI for Developers：Interactions API
• Google AI for Developers：Function Calling
• Google AI for Developers：Gemini API Key 配置
• Google AI for Developers：Gemini API Release Notes

会员充值教程

会员充值与订阅排查资料

适合阅读会员充值、订阅购买、权益对比和支付问题类文章后继续转化。

AI 订阅充值失败排查包 整理常见支付失败、地区限制、订单未到账和账号异常处理步骤。 查看资料包 会员权益对比表 对比不同 AI 工具会员权益、价格、适用人群和购买建议。 查看资料包