如何使用 Gemini 3.7 Flash API？

Google 于 2026 年 8 月 13 日（即 3.6 Flash 发布三周后）推出了 Gemini 3.7 Flash，并称其为“我们最智能的主力模型”。对开发者而言，最核心的亮点是：Agent 编码（agentic coding）评分大幅飙升（DeepSWE v1.1 从 49.0% 提升至 65.3%），促销期起步价仅为 3.6 Flash 发布价的一半，且 API 结构保持不变。如果你已经在调用 Gemini，只需更换一个模型 ID 即可。如果你还没有调用过，这是 Google 迄今为止为如此强大性能的模型提供的最便宜的入门门槛。

本指南是一份实操快速入门教程。你将获取一个 API 密钥，使用 cURL 发起第一次调用，然后将其移植到 Python 和 Node.js，实现流式传输响应，微调 generationConfig，并将整套流程接入到 Apifox，以便在不通过代码循环消耗 Token 的情况下迭代提示词（prompt）。官方公告中的技术参数包括：1M Token 上下文、64k 输出限制、多模态输入、函数调用（function calling）、搜索工具以及电脑操作（computer use）。

如果你是基于上一代模型构建的，请求结构与我们的 Gemini 3 Flash Preview API 指南中介绍的相同；本文将重点介绍 3.7 工作流中的所有新变化。

AI Coding 交流群

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

TL;DR

模型 ID 为 gemini-3.7-flash。接口：POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:generateContent，带有 header x-goog-api-key: <KEY>。
促销价格持续至 2026 年 12 月 31 日，每 100 万输入 Token 为 0.75 美元，每 100 万输出 Token 为 3.75 美元。自 2027 年 1 月 1 日起，价格将翻倍至 1.50 美元和 7.50 美元。
规格参数：1M Token 输入上下文，64k Token 输出限制。输入支持文本、图片、视频、音频和 PDF，输出为文本。
相比 3.6 Flash 的基准测试提升：DeepSWE 从 49.0% 提升至 65.3%，FrontierCode 从 34.4% 提升至 43.6%，AutomationBench 从 17.0% 提升至 30.4%，WebDev Arena Elo 从 1538 提升至 1588。
流式传输使用 :streamGenerateContent?alt=sse。请求 body 保留了 Google 的 contents 以及 generationConfig 数据模型。
在编写应用程序代码之前，先在 Apifox 中测试接口：导入接口规范，将密钥存为环境变量，并实时查看 SSE 分块的渲染效果。

Gemini 3.7 Flash 的适用场景

Flash 模型通常会牺牲少许巅峰智能来换取速度和价格优势，而 3.7 版本比以往任何版本都进一步缩小了这一差距。仅仅三周的时间跨度，相比 3.6 Flash 的基准测试提升却异常显著：DeepSWE v1.1 从 49.0% 飙升至 65.3%，FrontierCode 1.1 Main 从 34.4% 提升至 43.6%，AutomationBench 从 17.0% 提升至 30.4%，WebDev Arena Elo 也攀升了 50 分，从 1538 达到 1588。

请将这些数据视为工作负载匹配度的参考指标。在以下情况下，建议选择 3.7 Flash：

你需要运行 agent 循环。 AutomationBench 的得分几乎翻了一倍，Google 表示该模型在“多步规划和工具调用方面思考得更加勤勉”。拥有许多短小且重度依赖工具的轮次的 Agent 流水线是其目标使用场景。
你需要生成或调试代码。 Google 声称 3.7 在调试方面表现更好，并且更有能力在第一次尝试时就生成可部署的代码。DeepSWE 和 FrontierCode 的得分增长证实了这一点。
你需要处理文档。 GDP.pdf 的准确率从 22.0% 飙升至 34.0%，且 PDF 是一等输入类型。长上下文检索能力同样坚挺：在 128k-needle 测试中达到了 97.0%。
你在预算有限的情况下需要多模态输入。 文本、图像、视频、音频和 PDF 都可以通过同一个 contents 数组传入。

欲了解完整的特性列表，包括法律领域的 Harvey LAB-AA 得分（90.7%）以及更新后的 CBRN（化学、生物、放射和核）和网络安全防护，请参阅 Gemini 3.7 Flash 的新功能介绍。值得了解的背景是：Gemini 3.5 Pro 依然延期，且 Axios 报道 Google 正刻意在发布下一个旗舰模型之前先推出 Flash 更新。

获取 API key

有两种途径，且它们并不等价。

AI Studio（快速通道）。 打开 aistudio.google.com/apikey，点击 Get API key，选择一个 Google Cloud 项目，然后复制该字符串。该密钥可以立即用于请求 generativelanguage.googleapis.com，并且免费层提供了足够的配额供你进行原型设计。Gemini 3.7 Flash 已在 160 多个国家/地区可用。

Vertex AI（生产通道）。 如果你的基础设施部署在 GCP 上，请使用 Vertex。身份验证从 API key 切换为 OAuth（服务账号或短期 Token），调用路由通过 aiplatform.googleapis.com，并且你将获得 IAM、审计日志和区域接口。模型 ID 和请求 body 保持完全一致；只有 URL 和 auth 机制发生了变化。

先在 AI Studio 上进行原型设计，在上线生产流量之前迁移到 Vertex。无论哪种方式，都只需导出一次密钥：

export GEMINI_API_KEY="AIza..."

切勿在生产环境中硬编码该密钥，或将其作为 ?key= query 参数进行传递；query 字符串最终会记录在服务端日志中。

接口与身份验证

同步调用的基础接口如下：

POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:generateContent

流式传输则需要更换方法后缀并添加 SSE 标识：

POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:streamGenerateContent?alt=sse

auth 仅需一个 header：x-goog-api-key: $GEMINI_API_KEY。这就是整个握手过程。无需 Bearer Token，无需签名方案，也无需建立会话。

你的第一个 cURL 请求

以下是一个完整的可用调用：

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{ "text": "Review this SQL for injection risk: SELECT * FROM orders WHERE id = ${orderId}" }]
    }],
    "generationConfig": {
      "temperature": 0.3,
      "maxOutputTokens": 1024
    }
  }'

响应会返回一个 candidates 数组。每个 candidate 都包含一个带有 parts（如果您声明了工具，则为文本或函数调用）和 finishReason 的 content object。Token 计数位于顶层的 usageMetadata 中；请注意该数据块，因为在初始费率下，输出 Token 的成本是输入 Token 的五倍。

请注意数据模型：Google 使用包含角色和 parts 的 contents，而不是 OpenAI 的 messages 结构。如果您正从其他服务商迁移，请先搞定这个映射关系。

Python 快速入门

安装或升级官方 SDK：

pip install --upgrade google-generativeai

包含系统指令的基础调用：

import os
import google.generativeai as genai

genai.configure(api_key=os.environ["GEMINI_API_KEY"])

model = genai.GenerativeModel(
    model_name="gemini-3.7-flash",
    system_instruction="You are a code reviewer. Flag issues as blocking or non-blocking.",
    generation_config={
        "temperature": 0.3,
        "max_output_tokens": 2048,
    },
)

response = model.generate_content(
    "Review this Flask route for security issues:\n\n"
    "@app.route('/user/<id>')\n"
    "def get_user(id):\n"
    "    return db.execute(f'SELECT * FROM users WHERE id = {id}')"
)

print(response.text)
print("input tokens:", response.usage_metadata.prompt_token_count)
print("output tokens:", response.usage_metadata.candidates_token_count)

多模态输入同样使用 contents 数组。若要发送 PDF，请通过 Files API 上传并将其作为 part 进行引用：

invoice = genai.upload_file("q3-invoice.pdf")

response = model.generate_content([
    invoice,
    "Extract the invoice number, total, and due date as JSON.",
])
print(response.text)

GDP.pdf 基准测试的提升（从 22.0% 提高到 34.0%）正好体现在这一工作负载中：从混乱的真实世界文档中进行结构化提取。

Node.js 快速入门

Node SDK 为 @google/generative-ai，其结构与 Python 类似：

import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);

const model = genAI.getGenerativeModel({
  model: "gemini-3.7-flash",
  generationConfig: {
    temperature: 0.3,
    maxOutputTokens: 2048,
    responseMimeType: "application/json",
    responseSchema: {
      type: "object",
      properties: {
        severity: { type: "string", enum: ["blocking", "non-blocking"] },
        issues: { type: "array", items: { type: "string" } },
      },
      required: ["severity", "issues"],
    },
  },
});

const result = await model.generateContent(
  "Review this Express handler: app.get('/search', (req, res) => res.send(eval(req.query.q)))"
);

console.log(JSON.parse(result.response.text()));

responseSchema 这行代码的作用比表面上看起来更重要。它强制将候选响应转化为一个可解析的 object，这样下游代码就永远不会接触到自由格式的文本。请注意，它必须与 responseMimeType: "application/json" 配合使用，否则会被忽略。

流式传输 (Streaming)

对于聊天 UI 以及任何面向用户的界面，建议使用流式传输。在 Python 中，添加 stream=True：

stream = model.generate_content(
    "Explain the N+1 query problem with a concrete ORM example.",
    stream=True,
)

for chunk in stream:
    if chunk.text:
        print(chunk.text, end="", flush=True)

如果通过原生 HTTP，请求 :streamGenerateContent?alt=sse 并解析服务器发送事件（SSE）。每个 data: 行都包含部分 candidates 负载；最后一个数据块（chunk）包含 usageMetadata，因此 Token 计费统计只有在流关闭后才是准确的。

调整 generationConfig

以下是您最常接触的 parameter，按影响大小大致排序：

输出 Token 的价格在推广期为每百万个 3.75 美元，从 2027 年 1 月起为 7.50 美元，因此请根据您的使用场景需求来限制输出，而不是直接设为 64k 的上限。关于完整的 Token 算法以及每个工作负载的具体示例，请参阅我们的 Gemini 3.7 Flash 定价分析。

除了 generationConfig 之外，request body 还接受 tools（函数声明、搜索工具、电脑使用）和用于强制进行工具调用的 toolConfig。工具使用（Tool use）是 3.7 Flash 改进最大的地方，值得单独进行介绍：请参阅 Gemini 3.7 Flash 函数调用教程，了解声明、并行调用和响应循环模式（response-loop pattern）。

在编写应用代码前，先在 Apifox 中测试接口

在 Python 脚本中进行 Prompt 迭代既慢又昂贵：编辑、重新运行、滚动、重复，而且每个循环都会产生 Token 费用。更高效的迭代流程是，先在 API 客户端中锁定请求结构，一旦响应符合预期，再将其移植到代码中。

Apifox 原生支持 Gemini 的请求数据模型。配置步骤如下：

创建一个项目，并从 Google 的接口文档导入 Generative Language API OpenAPI 规范。导入后集合已自动命名，只需搜索 generateContent 即可找到。
添加一个环境变量，命名为 GEMINI_API_KEY，并在环境级别将其绑定到 x-goog-api-key header。每个请求都会继承它，且该密钥永远不会出现在已保存的请求 body 中。
将模型 ID 存为变量，并将其值设为 gemini-3.7-flash。当你想与 gemini-3.6-flash 进行 A/B 测试时，只需修改这一个变量，而无需逐个编辑十几个已保存请求中的 URL。
在可视化 JSON 编辑器中构建 contents 数组。 嵌套部分渲染清晰，且数据模型校验能在你因为 400 错误消耗任何 Token 之前，就捕获到格式错误的 body。
调用流式接口。 Apifox 会实时渲染 SSE 分块，因此你可以直观地看到回答的组装过程，其效果与你的 SDK 接收到的完全一致（包括延迟）。
将理想的响应保存为示例。 后续的测试运行将直接请求该固定数据（fixture），而不是调用真实的 API。这是整个工作流中最节省 Token 的方法。

一旦请求保存成功，即可将它们串联到测试场景中，并对 finishReason、响应数据模型以及 usageMetadata 中的 Token 数量设置断言。这能将手动的冒烟测试转化为回归测试套件，让你在每次修改 prompt 时都能运行；QA 团队使用的这种模式，在我们的面向 QA 工程师的 API 测试指南中有详细介绍。

错误处理与速率限制

Gemini 错误会返回一个包含 code、status 和 message 的顶级 error object。你可能会遇到的错误如下：

代码	状态	含义	解决方法
400	`INVALID_ARGUMENT`	格式错误的 body、角色（role）不正确或 contents 为空。	在发送前，先在 Apifox 中校验 body。
401	`UNAUTHENTICATED`	密钥缺失或已失效。	重新导出 `GEMINI_API_KEY`；确认该密钥在 AI Studio 中处于激活状态。
403	`PERMISSION_DENIED`	项目缺少访问权限或未绑定账单。	检查项目设置和账单状态。
429	`RESOURCE_EXHAUSTED`	达到速率限制或每日配额上限。	使用带抖动的退避策略（jittered backoff）、批量发送请求，或升级套餐层级。
500	`INTERNAL`	临时的服务端故障。	使用指数退避策略进行重试。
503	`UNAVAILABLE`	服务过载。	等待几秒后重试；如果使用 Vertex，请尝试其他区域。

保持生产环境稳定的三个习惯：

将每次调用封装在重试助手函数中，通过带抖动的指数退避策略来处理 429 和 5xx 错误。尽管 SDK 自身会进行几次重试，但一个轻量级的封装能让你自主控制日志记录和熔断机制。
不要凭空臆测速率限制数值。 限制额度因套餐层级而异，且会随时间变化；请从 Gemini API 价格与限制页面获取最新的实时数值，并在达到配额的 80% 时设置告警。
将模型 ID 绑定到环境变量中。 如果 3.7 版本的行为变化破坏了原有的 prompt，回滚到 gemini-3.6-flash 只需要修改配置，而无需重新部署。

FAQ

Gemini 3.7 Flash 可以免费使用吗？

AI Studio 提供免费层，每日配额足够用于原型开发，且在 2026 年 12 月 31 日之前，付费推广价格为每 100 万输入 Token 0.75 美元。如果您想进一步挖掘免费额度的潜力，我们的 Gemini API 免费获取指南详细介绍了各个层级及其限制。

通过 AI Studio 和 Vertex AI 调用有什么区别？

模型相同，请求 body 相同，但底层调用方式不同。AI Studio 使用针对 generativelanguage.googleapis.com 的 API 密钥；而 Vertex 则使用针对 aiplatform.googleapis.com 的 OAuth，并增加了 IAM、审计日志以及区域级接口。您可以在 AI Studio 上开始，待流量真正增长时再迁移至 Vertex。

我可以向 Gemini 3.7 Flash 发送图像、音频和 PDF 吗？

是的。输入是多模态的：文本、图像、视频、音频和 PDF 都作为 contents 数组中的一部分进行传输，既可以直接内联为 base64，也可以通过 Files API 进行引用传输。输出则仅支持文本。

上下文窗口和输出限制有多大？

输入 100 万 Token，输出 6.4 万 Token。128k “大海捞针”（needle-in-a-haystack）检索评分高达 97.0%，这表明其长上下文召回能力非常可靠，远超大多数应用的需求。不过，对长输入进行分块（chunking）仍然可以节省资金，因为每一个输入 Token 都是要收费的。

我应该从 Gemini 3.6 Flash 升级吗？

对于 Agent 和编码工作负载，基准测试的差距足够大，因此答案通常是肯定的，而且更换模型 ID 只需要一行代码。在切换生产流量之前，有哪些行为差异值得进行回归测试，这已在 3.6 到 3.7 Flash 迁移指南中进行了介绍。

3.7 Flash 在您的技术栈中的位置

Gemini 3.7 Flash 属于罕见的“加量还降价”的发布版本。在 2026 年底前，您只需支付 3.6 Flash 发布价的一半，就能使用这款在 DeepSWE 上高出 16 分、在 AutomationBench 上得分几乎翻倍的模型。一个合理的默认策略是：现在就将 Agent 循环、代码任务和文档提取路由到 3.7 Flash，在预算规划中考虑到付费推广期的时间窗口，并通过环境变量保留回滚到 3.6 的路径。

先从上文的 cURL 调用开始，确认响应结构，在编写应用程序代码之前将请求移入 API 客户端。下载 Apifox 导入 Gemini 接口规范，只需绑定一次密钥，即可在同一个工作区中测试同步、流式传输和工具调用请求。当 prompt 调整合适后，移植到 Python 或 Node 只需要几分钟，因为您已经清楚实际的网络传输流量是怎样的。