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

截至 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 请求的方式
按这个顺序做:
- 在 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 拒绝。
- 给项目开通付费结算并充值。绑定结算账号后项目进入 Tier 1;新账号默认是 Prepay,先充值(最少 $5)才能扣费。3.1 Pro 没有免费层,这一步跳不过。
- 在本地设置环境变量
GEMINI_API_KEY,官方 SDK 会自动读取。 - 带着明确的模型 ID 和思考级别发第一条请求。
下面的 Python、JavaScript 和 REST 示例都用当前模型 ID 和 generateContent 接口写成,发布前没有实际运行。Google 新版文档的示例已改用 Interactions API(Python 里是 client.interactions.create,REST 是 POST /v1beta/interactions),多轮对话推荐用服务端管理的 previous_interaction_id;单轮请求用 generateContent 仍然可以。
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)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);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

截至 2026 年 10 月 10 日,Gemini API 模型列表里和这个选择有关的 ID 如下:
| 模型 ID | 状态 | 什么时候用 |
|---|---|---|
gemini-3.1-pro-preview | Preview,2026 年 2 月 19 日发布,未公布停用日期 | 需要 Pro 级推理时的默认选择 |
gemini-3.1-pro-preview-customtools | Preview,价格与标准版相同 | agent 同时有 bash 和注册的自定义工具,且“先用哪个工具”是可靠性问题 |
gemini-3-pro-preview | 2026 年 3 月 9 日已停用,Google 列出的替代是 gemini-3.1-pro-preview | 只用于迁移:代码里还写着它,就改成新 ID |
gemini-3.8-flash | GA,2026 年 9 月 2 日 | 要免费层、要更低单价,或想先试 Flash 够不够用 |
gemini-3.6-flash | GA,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 价格表: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 更新日志):
- 模型 ID:
gemini-3-pro-preview已于 2026 年 3 月 9 日停用,改成gemini-3.1-pro-preview,不要依赖任何别名。 - 思考参数:把
thinking_budget换成字符串枚举thinking_level,两者不能同时出现(否则返回 400)。 - 采样参数:删除
temperature、top_p、top_k(2026 年 7 月 21 日起已弃用)、candidate_count(Gemini 3 及以后不支持)和预填的模型回合(prefill)。暂时删不掉temperature的,旧版 Gemini 3 指南的提醒仍然适用:低于 1.0 可能导致循环输出等异常。 - 多轮对话与思考签名:Gemini 3 模型用思考签名在多次调用之间保留推理上下文。用 Interactions API 的
previous_interaction_id时由服务端管理;自己拼接对话历史时,必须把带签名的思考块原样传回后续请求。细节见 Gemini API 思考签名文档。 - 函数调用:如果继续用
generateContent,确认每个FunctionResponse都带有call_id和name。 - 成本与回归:用上面的价格表重算预算,再用几条代表性提示词在新模型上跑一遍,比对结果后再切生产流量。
用 OpenAI SDK 调用。Google 的 Gemini OpenAI 兼容文档说明,Gemini 模型可以通过 OpenAI 的 Python 或 JavaScript 库访问,只需改三处:API key、base URL 和模型名。OpenAI 的 reasoning_effort 会自动映射到 Gemini 对应的 thinking_level;用了 reasoning_effort 就不要再另加一套 Gemini 思考配置。下面的示例同样没有实际运行:
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 Pro | Gemini 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 |
| 默认思考级别 | high | medium |
| 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.00 | 5 × $12.00 = $60.00 | $160.00 |
| 3.1 Pro Batch | 50 × $1.00 = $50.00 | 5 × $6.00 = $30.00 | $80.00 |
| 3.8 Flash(2026 年内) | 50 × $0.75 = $37.50 | 5 × $3.75 = $18.75 | $56.25 |
| 3.8 Flash(2027 年起) | 50 × $1.50 = $75.00 | 5 × $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日。
参考来源14
本文引用的外部页面,按正文出现顺序排列。最后更新于 2026年10月10日。
- 1.Gemini API 弃用时间表ai.google.dev/gemini-api/docs/deprecations
- 2.Gemini API 定价页ai.google.dev/gemini-api/docs/pricing
- 3.Gemini API 可用地区列表ai.google.dev/gemini-api/docs/available-regions
- 4.Gemini 3 开发者指南 FAQai.google.dev/gemini-api/docs/gemini-3
- 5.Gemini API 结算文档ai.google.dev/gemini-api/docs/billing
- 6.Google AI 方案与 AI Studio 的说明页ai.google.dev/gemini-api/docs/google-ai-plans
- 7.Gemini API key 文档ai.google.dev/gemini-api/docs/api-key
- 8.Gemini API 模型列表ai.google.dev/gemini-api/docs/models
- 9.模型页ai.google.dev/gemini-api/docs/models/gemini-3.1-pro-preview
- 10.Gemini API 速率限制文档ai.google.dev/gemini-api/docs/rate-limits
- 11.Gemini 3.8 Flash 新功能页ai.google.dev/gemini-api/docs/latest-model
- 12.Gemini API 更新日志ai.google.dev/gemini-api/docs/changelog
- 13.Gemini API 思考签名文档ai.google.dev/gemini-api/docs/thought-signatures
- 14.Gemini OpenAI 兼容文档ai.google.dev/gemini-api/docs/openai





