跳转到主要内容

Gemini 3.1 Pro API 价格与接入指南:API 无免费层,仍是 Preview

Gemini 3.1 Pro API 仍是 Preview、无免费层:200k 内每百万 tokens 输入 $2、输出 $12。要免费额度或更低单价,选 3.8 Flash。

LaoZhang AI Team发布于更新于 22 分钟阅读
文章目录
聚焦当前模型路径、价格区间与 AI Studio 的 Gemini 3.1 Pro API 指南

截至 2026 年 10 月 10 日,Gemini 3.1 Pro 在 Gemini API 里仍然只有 Preview 版本:模型 ID 是 gemini-3.1-pro-preview,另有一个面向自定义工具的 gemini-3.1-pro-preview-customtools。Google 的 Gemini API 弃用时间表对它写的是“尚未公布停用日期”,也没有列出接替它的 Pro 模型;旧的 gemini-3-pro-preview 已在 2026 年 3 月 9 日停用。

按 Gemini API 定价页,3.1 Pro 的免费层每一行都是 Not available(不提供)。提示词在 200k tokens 以内时,每百万 tokens 输入 $2.00、输出 $12.00(输出含思考 token);超过 200k 时为 $4.00 和 $18.00;Batch 与 Flex 都是半价。如果你要的是免费额度或更低单价,应该看已经 GA 的 Gemini 3.8 Flash:它有免费层,付费标准价 $0.75 / $3.75 维持到 2026 年 12 月 31 日,2027 年 1 月 1 日起变为 $1.50 / $7.50。

TL;DR

  • 默认模型 ID:gemini-3.1-pro-preview。agent 同时用 bash 和你注册的自定义工具时,再考虑 gemini-3.1-pro-preview-customtools,两者价格相同。
  • 状态:Preview,2026 年 2 月 19 日发布,未公布停用日期。Google 对 Preview 模型的统一说明是:限额可能更严,停用前至少提前 2 周通知。
  • 免费:Gemini API 里没有 3.1 Pro 免费层。AI Studio 网页里能不能免费试,Google 各页面的说法不一致,见下一节。
  • 价格:200k 以内 $2 / $12,超过 200k 为 $4 / $18(每百万 tokens 输入 / 输出);Batch、Flex 半价;Priority 是标准价的 1.8 倍。
  • 付费方式:新账号默认预付费(Prepay),最少充值 $5;余额用完后,该结算账号下所有 key 都返回 HTTP 402。
  • 更便宜的选择:到 2026 年底,3.1 Pro 的输入单价是 3.8 Flash 的 2.67 倍、输出是 3.2 倍;2027 年 Flash 涨价后缩小到 1.33 倍和 1.6 倍。
  • 地区:Google 的 Gemini API 可用地区列表不包括中国大陆和香港。

Gemini 3.1 Pro API 免费吗:API 没有免费层

分两层回答。

通过 API 调用:不免费。定价页上 3.1 Pro 的免费层全部是 Not available;Google 的 Gemini 3 开发者指南 FAQ 也写明,gemini-3.1-pro-preview 在 Gemini API 里没有免费层(这页已标注弃用,内容转到 3.8 Flash 的新功能说明)。没有开通付费结算的项目,只能调用 3.8 Flash、3.6 Flash、Flash-Lite 这类有免费层的模型。另外两类常被当成“免费额度”的赠金也不能用:按 Gemini API 结算文档,Google Cloud 的 $300 免费试用从 2026 年 3 月起不再覆盖 Gemini API 用量,Cloud 欢迎赠金也不能支付 AI Studio 用量。

在 AI Studio 网页里试用:Google 的说法不一致。

  • 前面提到的 Gemini 3 指南(已标注弃用)写着,可以在 Google AI Studio 里免费试用 Gemini 3.1 Pro。
  • Google AI 方案与 AI Studio 的说明页把“使用 Gemini Pro 等高级模型”列为 Google AI Pro 订阅的权益,免费账号只有“适度配额”。
  • 截至 2026 年 10 月 10 日,未订阅 Google AI 方案、也没有绑定 API key 的个人账号打开 AI Studio,Playground 默认选中 Gemini 3.1 Pro Preview,模型卡上没有锁定标记,但侧栏提示“升级以解锁更多:更高限额、Pro 模型等”,页面没有写出免费次数。
  • 2026 年 2 月 19 日 3.1 Pro 上线时,Google AI 开发者论坛有免费用户反映看到“今天的免费生成次数已用完,可以改用自己的 API key 继续”。

所以,免费账号在 AI Studio 网页里也许能少量试用 3.1 Pro,但次数没有公开,随时可能用完,而且这和 API 是否免费无关。Google AI Pro / Ultra 订阅的权益只在 AI Studio 网页里有效,直接调用 Gemini API 另外计费;Gemini 应用里选的“Pro”同样不包含 API 额度。

哪些 Gemini 模型现在还有免费层、免费层限额去哪里看,见 Gemini API Key 免费额度与速率限制。

最快跑通 Gemini 3.1 Pro 请求的方式

按这个顺序做:

  1. 在 Google AI Studio 创建项目和 API key。创建 key 不收费,key 属于某个 Google Cloud 项目。按 Gemini API key 文档,2026 年 5 月 28 日以后在 AI Studio 新建的 key 是绑定服务账号、只能调用 Gemini API 的 auth key;不加限制的旧式标准 key 会被 Gemini API 拒绝。
  2. 给项目开通付费结算并充值。绑定结算账号后项目进入 Tier 1;新账号默认是 Prepay,先充值(最少 $5)才能扣费。3.1 Pro 没有免费层,这一步跳不过。
  3. 在本地设置环境变量 GEMINI_API_KEY,官方 SDK 会自动读取。
  4. 带着明确的模型 ID 和思考级别发第一条请求。

下面的 Python、JavaScript 和 REST 示例都用当前模型 ID 和 generateContent 接口写成,发布前没有实际运行。Google 新版文档的示例已改用 Interactions API(Python 里是 client.interactions.create,REST 是 POST /v1beta/interactions),多轮对话推荐用服务端管理的 previous_interaction_id;单轮请求用 generateContent 仍然可以。

python
from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.1-pro-preview",
    contents="Review this API design and list the main tradeoffs.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="medium")
    ),
)

print(response.text)
javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const response = await ai.models.generateContent({
  model: "gemini-3.1-pro-preview",
  contents: "Review this API design and list the main tradeoffs.",
  config: {
    thinkingConfig: {
      thinkingLevel: "medium",
    },
  },
});

console.log(response.text);
bash
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Review this API design and list the main tradeoffs."}]
    }],
    "generationConfig": {
      "thinkingConfig": {
        "thinkingLevel": "medium"
      }
    }
  }'

示例里显式写了 medium。不写的话,3.1 Pro 默认用 high(动态思考),思考 token 按输出价计费,延迟和账单都会跟着默认值走。示例中也没有 temperature、top_p 这类采样参数,原因见后面的迁移清单。

在优化之前,先选对 model ID

从 AI Studio 进入 gemini-3.1-pro-preview,并分叉到 customtools 或 Flash 路径的路线图

截至 2026 年 10 月 10 日,Gemini API 模型列表里和这个选择有关的 ID 如下:

模型 ID状态什么时候用
gemini-3.1-pro-previewPreview,2026 年 2 月 19 日发布,未公布停用日期需要 Pro 级推理时的默认选择
gemini-3.1-pro-preview-customtoolsPreview,价格与标准版相同agent 同时有 bash 和注册的自定义工具,且“先用哪个工具”是可靠性问题
gemini-3-pro-preview2026 年 3 月 9 日已停用,Google 列出的替代是 gemini-3.1-pro-preview只用于迁移:代码里还写着它,就改成新 ID
gemini-3.8-flashGA,2026 年 9 月 2 日要免费层、要更低单价,或想先试 Flash 够不够用
gemini-3.6-flashGA,2026 年 7 月 21 日,上一代 Flash,价格与 3.8 Flash 相同3.8 Flash 在复杂任务上用的 token 偏多时的替代

Gemini 3 系列里,3.1 Pro 是唯一的 Pro 文本模型:Gemini API 上没有 3.6 Pro、3.8 Pro 或 Gemini 4。2026 年 10 月 8 日起,gemini-3.7-flash 的请求被转到 gemini-3.8-flash,gemini-3.5-flash 被转到 gemini-3.6-flash;已停用的 2.5 Pro 预览版(03-25、05-06、06-05),Google 列出的替代模型也是 gemini-3.1-pro-preview。

gemini-3.1-pro-preview 的模型页列出的规格:

  • 输入上限 1,048,576 tokens,输出上限 65,536 tokens。
  • 输入支持文本、图片、视频、音频和 PDF,输出只有文本。
  • 支持 Batch API、Flex 推理、Priority 推理、上下文缓存、代码执行、函数调用、使用 Google 搜索和 Google 地图建立依据、结构化输出、思考和网址上下文;文件搜索只在 AI Studio 里支持。
  • 不支持图片生成、音频生成和 Live API。要图片输出或实时语音,从一开始就该换模型系列。

-customtools 不是更强或上下文更长的版本,而是同价的另一个端点:Google 模型页说它会更倾向调用你注册的自定义工具(例如 view_file、search_code),而不是直接走 bash;在不依赖这类工具的场景里,质量可能有波动。所以普通推理、聊天和文档分析留在标准版。具体怎么判断,见 Gemini 3.1 Pro Customtools 指南。

不靠猜的定价与限额理解方式

展示 Gemini 3.1 Pro 长上下文价格带、Batch、缓存和 AI Studio 限额入口的示意图

Gemini 3.1 Pro 价格表:200k 是分界线

截至 2026 年 10 月 10 日的 Gemini API 定价页(付费层,每百万 tokens,-customtools 同价):

档位输入 ≤200k输入 >200k输出 ≤200k输出 >200k缓存读取 ≤200k / >200k
Standard$2.00$4.00$12.00$18.00$0.20 / $0.40
Batch$1.00$2.00$6.00$9.00$0.20 / $0.40
Flex$1.00$2.00$6.00$9.00$0.20 / $0.40
Priority$3.60$7.20$21.60$32.40$0.36 / $0.72
  • 是否超过 200k 按提示词长度判断;超过后输入和输出单价一起上涨。
  • 输出价包含思考 token。
  • 缓存另收存储费:每百万 tokens 每小时 $4.50,Priority 为 $8.10。
  • 使用 Google 搜索或 Google 地图建立依据:免费层不可用;付费层每月 5,000 次免费请求,由所有 Gemini 3 及以后的模型共用,超出后每 1,000 次 $14。

全部 Gemini 模型的价格对照见 Gemini API Key 购买前先看:价格、免费额度与 2027 年 Flash 涨价。

限额与计费层级:数字在 AI Studio 里看

Google 没有公开按层级列出的 RPM / TPM / RPD 表。Gemini API 速率限制文档只说明规则:限额按项目计算,不按 API key 计算,多建 key 不会多出额度;你项目当前生效的数字在 AI Studio 的速率限制页面查看;Preview 模型的限额可能更严。

层级跟着结算账号走,满足条件后自动升级,通常 10 分钟内生效:

层级条件每月花费上限10 分钟滚动花费上限
Tier 1设置并绑定有效结算账号$250$10
Tier 2首次成功付款后累计付费 $100 且满 3 天$2,000$50
Tier 3首次成功付款后累计付费 $1,000 且满 30 天$20,000 至 $100,000+$200

超过 10 分钟滚动上限返回 429 RESOURCE_EXHAUSTED;碰到每月上限时,该结算账号下所有项目暂停到下个结算周期。

计费方式方面,新用户默认 Prepay:先买额度(最少 $5,余额最多 $5,000),额度 12 个月后过期且不退款;余额归零时,该结算账号关联的所有项目、所有 key 同时返回 HTTP 402,充值后恢复。原来用后付费(Postpay)的账号正在被迁到 Prepay,且不能从 Prepay 改回 Postpay。据 Impress Watch 2026 年 8 月 13 日的报道,Google 通知已有付费账号在 2026 年 10 月 12 日前切换并购买额度,否则服务会中断;Google 文档只写“以你账号通知里的切换日期为准”,请看自己收到的通知。层级、402 和“没有额度”的排查见 Gemini API 计费层级详解,429 的分类见 Gemini API 速率限制指南。

真正影响成本和延迟的,是 thinking、长上下文与缓存

思考级别。按 Google 的 Gemini 3 指南,3.1 Pro 支持 low、medium、high 三档,不指定时默认 high(动态思考);minimal 在 3.1 Pro 上不支持。thinking_level 和旧的 thinking_budget 不能出现在同一个请求里,否则返回 400。thinking_budget 目前仍为向后兼容保留,但 Google 的迁移清单要求换成 thinking_level。作为对照,3.8 Flash 默认是 medium,也不支持 minimal。

思考 token 按输出价计费,所以思考级别就是成本开关。一个可行的起点:日常任务先用 medium;抽取、分类、短文本改写先试 low;复杂分析、大代码库审阅、多步推理再显式开 high。这是按定价关系和文档行为给出的建议,不是 Google 的规定,最终用你自己的提示词比较输出质量和账单。

长上下文。1M token 窗口是选 3.1 Pro 的重要理由,但提示词一旦超过 200k,输入单价从 $2 变成 $4,输出从 $12 变成 $18。能拆分、摘要或检索后再送入的上下文,尽量控制在 200k 以内。

缓存。缓存读取单价是普通输入的十分之一($0.20 对 $2.00),但要按小时付存储费。以一份 150k tokens、每次请求都要带上的参考文档为例:

  • 每次命中缓存省下:0.15 ×($2.00 − $0.20)= $0.27
  • 缓存每小时的存储费:0.15 × $4.50 = $0.675
  • 回本次数:$0.675 ÷ $0.27 = 2.5,也就是这份文档每小时被复用 3 次以上,缓存才划算(未计首次写入缓存的费用)。

思考级别和任务类型的对应关系,见 Gemini 3.1 Pro 思考级别:LOW/MEDIUM/HIGH 区别。

如果你之前用的是 Gemini 3 Pro Preview 或 OpenAI SDK,该怎么迁移

从 gemini-3-pro-preview、2.5 Pro 预览版或更早的 Gemini 代码迁过来,按这份清单逐项改(依据 Google Gemini 3.8 Flash 新功能页里的迁移清单和 2026 年 7 月 21 日的Gemini API 更新日志):

  1. 模型 ID:gemini-3-pro-preview 已于 2026 年 3 月 9 日停用,改成 gemini-3.1-pro-preview,不要依赖任何别名。
  2. 思考参数:把 thinking_budget 换成字符串枚举 thinking_level,两者不能同时出现(否则返回 400)。
  3. 采样参数:删除 temperature、top_p、top_k(2026 年 7 月 21 日起已弃用)、candidate_count(Gemini 3 及以后不支持)和预填的模型回合(prefill)。暂时删不掉 temperature 的,旧版 Gemini 3 指南的提醒仍然适用:低于 1.0 可能导致循环输出等异常。
  4. 多轮对话与思考签名:Gemini 3 模型用思考签名在多次调用之间保留推理上下文。用 Interactions API 的 previous_interaction_id 时由服务端管理;自己拼接对话历史时,必须把带签名的思考块原样传回后续请求。细节见 Gemini API 思考签名文档。
  5. 函数调用:如果继续用 generateContent,确认每个 FunctionResponse 都带有 call_id 和 name。
  6. 成本与回归:用上面的价格表重算预算,再用几条代表性提示词在新模型上跑一遍,比对结果后再切生产流量。

用 OpenAI SDK 调用。Google 的 Gemini OpenAI 兼容文档说明,Gemini 模型可以通过 OpenAI 的 Python 或 JavaScript 库访问,只需改三处:API key、base URL 和模型名。OpenAI 的 reasoning_effort 会自动映射到 Gemini 对应的 thinking_level;用了 reasoning_effort 就不要再另加一套 Gemini 思考配置。下面的示例同样没有实际运行:

python
from openai import OpenAI

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)

response = client.chat.completions.create(
    model="gemini-3.1-pro-preview",
    reasoning_effort="medium",
    messages=[
        {"role": "user", "content": "Summarize the migration risks in this API design."}
    ]
)

print(response.choices[0].message.content)

兼容层适合先在现有 OpenAI 客户端里试 Gemini。需要思考签名、Interactions API 或 Gemini 专有功能时,改用官方 GenAI SDK 更直接。

什么时候应该用 Gemini 3.1 Pro,什么时候不该用

最常见的取舍是 3.1 Pro 和 3.8 Flash。截至 2026 年 10 月 10 日:

对比项Gemini 3.1 ProGemini 3.8 Flash
状态Preview,未公布停用日期GA(2026 年 9 月 2 日)
API 免费层无有
标准价(输入 / 输出,每百万 tokens)$2.00 / $12.00(≤200k)2026 年 12 月 31 日前 $0.75 / $3.75;2027 年 1 月 1 日起 $1.50 / $7.50
Batch / Flex$1.00 / $6.00(≤200k)$0.375 / $1.875,2027 年起 $0.75 / $3.75
默认思考级别highmedium
Google 的定位更好的思考与 token 效率,面向软件工程和需要精确调用工具的 agent“最智能的 Flash 模型”,面向长周期软件工程、自主 agent 和复杂企业工作流;复杂任务上会多用 token

单价倍数的算法:2026 年内,输入 $2.00 ÷ $0.75 ≈ 2.67 倍,输出 $12.00 ÷ $3.75 = 3.2 倍;2027 年起,输入 $2.00 ÷ $1.50 ≈ 1.33 倍,输出 $12.00 ÷ $7.50 = 1.6 倍。3.6 Flash 的价格与 3.8 Flash 相同。

换成一个具体工作量:1,000 次请求,每次输入 50k tokens、输出 5k tokens(含思考),两边假设用量相同,按标准价计算:

方案输入费用输出费用合计
3.1 Pro 标准50 × $2.00 = $100.005 × $12.00 = $60.00$160.00
3.1 Pro Batch50 × $1.00 = $50.005 × $6.00 = $30.00$80.00
3.8 Flash(2026 年内)50 × $0.75 = $37.505 × $3.75 = $18.75$56.25
3.8 Flash(2027 年起)50 × $1.50 = $75.005 × $7.50 = $37.50$112.50

表里的 50 和 5 是以百万 tokens 计的总量。Google 自己说明 3.8 Flash 在长时间运行的复杂任务上会多用 token,所以实际差距可能小于表中数字;Google 也没有发布 3.8 Flash 与 3.1 Pro 的直接基准对比,各家第三方的对比结论互相矛盾。最可靠的办法是拿你自己的任务两边各跑一批,比较质量和实际账单。

据此可以这样分:

  • 用 3.1 Pro:在 Flash 上试过、质量确实不够的复杂推理;需要把大量文档或代码库放进 1M 窗口一起分析;agent 需要精确调用工具;能接受 Preview 的限额和变动。后台任务优先走 Batch 或 Flex,直接省一半。
  • 用 3.8 Flash:需要免费层;对成本或吞吐敏感;更看重 GA 模型的稳定性。2026 年 12 月 31 日前的价格是它最便宜的窗口,做 2027 年预算时按 $1.50 / $7.50 算。
  • 用 3.6 Flash:3.8 Flash 在你的任务上用的 token 偏多时,Google 建议调低思考级别或改用 3.6 Flash,两者价格相同。
  • 换模型系列:需要图片生成、音频生成或 Live API 时,3.1 Pro 和这两个 Flash 都不是答案。

只想找免费的 API 先试,就不要从 Pro 开始,先看 Gemini API Key 免费额度与速率限制和 Gemini API 速率限制指南。

FAQ

Gemini 3.1 Pro API 免费吗?
不免费。截至 2026 年 10 月 10 日,Google 定价页上 3.1 Pro 的免费层全部是 Not available,调用必须开通付费结算。AI Studio 网页里也许能用免费账号少量试用,但 Google 各页面说法不一、次数没有公开,而且这不是 API 额度。

Gemini 3.1 Pro 价格是多少?
标准价每百万 tokens:提示词 200k 以内输入 $2.00、输出 $12.00,超过 200k 为 $4.00 和 $18.00;Batch 和 Flex 半价,Priority 是标准价的 1.8 倍。输出价包含思考 token。

gemini-3-pro-preview 现在还能用吗?
不能。它已在 2026 年 3 月 9 日停用,Google 列出的替代是 gemini-3.1-pro-preview,代码里应直接写新 ID。

Gemini 3.1 Pro 什么时候正式发布或停用?
截至 2026 年 10 月 10 日,Google 既没有公布 GA 日期,也没有公布停用日期,也没有列出接替它的 Pro 模型。Google 对 Preview 模型的承诺是停用前至少提前 2 周通知。

Gemini 3.6 Flash、3.8 Flash 和 3.1 Pro 选哪个?
成本敏感或需要免费层,选 3.8 Flash(3.6 Flash 同价,适合 3.8 Flash 用 token 偏多的任务);在 Flash 上质量不够的复杂推理和长上下文分析,再用 3.1 Pro。到 2026 年底,3.1 Pro 输入单价是这两个 Flash 的 2.67 倍、输出 3.2 倍。

是不是所有项目都应该用 gemini-3.1-pro-preview-customtools?
不是。只有当 agent 同时有 bash 和注册的自定义工具、且工具优先级本身是问题时才值得用。Google 模型页提醒,在不依赖这类工具的场景里,它的质量可能有波动。

真正属于我的 RPM、TPM、RPD 去哪里看?
去 AI Studio 的速率限制页面。Google 没有公开按层级列出的数字,限额按项目计算,取决于你的层级和账号状态。

能不能用 OpenAI SDK 调 Gemini 3.1 Pro?
可以。按 Google 的 OpenAI 兼容文档,改 API key、base URL(https://generativelanguage.googleapis.com/v1beta/openai/)和模型名即可,reasoning_effort 会映射到 thinking_level。

Gemini 3.1 Pro 支持图片生成或 Live API 吗?
不支持。模型页把图片生成、音频生成和 Live API 都列为不支持,输出只有文本。

参考来源14

本文引用的外部页面,按正文出现顺序排列。最后更新于 2026年10月10日。

  1. 1.Gemini API 弃用时间表ai.google.dev/gemini-api/docs/deprecations
  2. 2.Gemini API 定价页ai.google.dev/gemini-api/docs/pricing
  3. 3.Gemini API 可用地区列表ai.google.dev/gemini-api/docs/available-regions
  4. 4.Gemini 3 开发者指南 FAQai.google.dev/gemini-api/docs/gemini-3
  5. 5.Gemini API 结算文档ai.google.dev/gemini-api/docs/billing
  6. 6.Google AI 方案与 AI Studio 的说明页ai.google.dev/gemini-api/docs/google-ai-plans
  7. 7.Gemini API key 文档ai.google.dev/gemini-api/docs/api-key
  8. 8.Gemini API 模型列表ai.google.dev/gemini-api/docs/models
  9. 9.模型页ai.google.dev/gemini-api/docs/models/gemini-3.1-pro-preview
  10. 10.Gemini API 速率限制文档ai.google.dev/gemini-api/docs/rate-limits
  11. 11.Gemini 3.8 Flash 新功能页ai.google.dev/gemini-api/docs/latest-model
  12. 12.Gemini API 更新日志ai.google.dev/gemini-api/docs/changelog
  13. 13.Gemini API 思考签名文档ai.google.dev/gemini-api/docs/thought-signatures
  14. 14.Gemini OpenAI 兼容文档ai.google.dev/gemini-api/docs/openai