Gemini 的 reasoning_effort 和 thinking_level 怎么对应
数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。
一句话结论：reasoning_effort 不是 Gemini 的原生参数，它是 OpenAI 兼容层给你留的一个转接口。你在兼容层里传它，Gemini 侧接收到的其实是 thinking_level（Gemini 3.x）或者 thinking_budget（Gemini 2.5）——两代模型对应的目标字段名不是同一个，而 thinking_budget 具体接受什么形态的取值，官方文档里没有找到说明。正因为是同一件事的两种写法，官方明确说这两者功能重叠、不能同时使用。更容易翻车的是关闭思考：Gemini 2.5 系列可以把 reasoning_effort 设成 "none"，但官方明文写着 Gemini 2.5 Pro 与 Gemini 3 系列无法关闭推理。而思考消耗的 token 是算在输出价格里的，所以这个参数调高调低，最终落点是你的输出账单。
下面按你真正会碰到的顺序讲：先是映射本身，再是互斥规则，再是默认值，再是关不掉的那批模型，最后是账单侧的后果。
这层映射发生在哪一层，别搞错作用域
先划清边界：这套 reasoning_effort 的说法，是在 OpenAI 兼容层里才成立的。它的存在理由很直白——让本来就写着 OpenAI SDK 的那套代码，不用改参数名就能跑到 Gemini 上。
兼容层的接入点，官方给的是 base URL 换成 https://generativelanguage.googleapis.com/v1beta/openai/，鉴权沿用 OpenAI 那一套 Authorization: Bearer 加上你的 Gemini API 密钥。官方对整个迁移量的原话是「只需改三行」——api_key、base_url、model。而 Gemini 的原生 REST 接口鉴权用的是另一个请求头 x-goog-api-key，两条路的鉴权形态并不一样。
这个区分对本文的意义在于：如果你走的是原生 API 而不是兼容层，那你面对的参数名从头到尾就是 thinking_level / thinking_budget，根本不存在「映射」这回事。所谓的映射，只对从 OpenAI SDK 那边过来的调用生效。官方在兼容层文档里还额外给了一句建议：如果你还没有在用 OpenAI 库，那推荐直接调用 Gemini 原生 API，而不是绕道兼容层。换句话说，兼容层的定位是迁移用的缓冲垫，不是新项目的推荐入口。
一个参数名，映射到两个不同的目标字段
映射关系本身是分代的：
- Gemini 3.x：
reasoning_effort→thinking_level - Gemini 2.5：
reasoning_effort→thinking_budget
这里要先按住一个很容易脱口而出的说法。thinking_level 和 thinking_budget 这两个名字摆在一起，读起来像是「一个是档位、一个是预算」，官方在讲不传这个参数时的默认行为时，用的措辞也确实是「默认级别或默认预算」，级别和预算这两个词是并列出现的。但官方文档里没有找到 thinking_budget 到底接受什么形态取值的说明——所以「档位对预算」这个对照只是从字面读出来的印象，别把它当成官方结论写进你们团队的技术文档。你能确定下来的只有映射本身：同一个 reasoning_effort，在 3.x 上落到 thinking_level，在 2.5 上落到 thinking_budget。
官方给出的档位是 minimal、low、medium、high 四档。这四档到底各自对应多少思考预算，官方文档里没有找到逐档的换算说明，而且这类数值本身也属于会随模型更新变动的东西，不值得记死。你真正需要记住的只有一件事：同一段代码里写死 reasoning_effort="high"，换个模型代际之后，它对应到的目标字段就换了一个。跨代升级模型时，这个参数属于必须回头复查的那一类——因为你改的是模型名，参数名一个字没动，代码 diff 看上去干干净净，这类改动在代码评审里最容易被放过去。
两个参数功能重叠，不能同时传
官方对这条说得很硬：reasoning_effort 与 thinking_level / thinking_budget 功能重叠，不能同时使用。
这条规则的现实杀伤力，在于它踩中的是一个很自然的写法。团队从 OpenAI 迁过来，代码里原本就带着 reasoning_effort；后来有人想用 Gemini 的专有能力，又在 extra_body 里补了一个 thinking_config。两处都写上了，谁也没觉得不对，因为从 OpenAI SDK 的类型检查角度看，这两个字段一个是顶层参数、一个是塞在 extra_body 里的透传内容，静态检查根本拦不住。
那同时传了会怎么样？官方文档里没有找到关于同时传入时具体返回哪个错误码、或者哪一个字段优先生效的说明。 这里我不做任何猜测——你能拿到的确定信息只有「不能同时使用」这一句。可以顺带记一下的是，官方错误码参考里确实有一个 parameter_unknown（HTTP 400，请求中含未知参数），官方给的处置是移除无法识别的参数后重试；但把这个码直接对号入座到「同时传了两个思考参数」这个场景上，属于我的推断而不是官方说法，所以别照着这个思路去排查。
稳妥的做法是从代码规范上直接堵死：在同一个项目里只允许一种写法。要么全项目走兼容层的 reasoning_effort，要么全项目走 Gemini 侧字段，评审时 grep 一遍两个关键字，同时出现就打回。
不指定的时候走什么
如果你压根没传 reasoning_effort，官方的说法是走模型的默认级别或默认预算。注意这里官方用的也是「级别或预算」的双形态措辞，跟上面那条映射对得上。
具体默认到哪一档，以官方文档当前版本为准——这类默认值是典型的会跟着模型版本变的东西，把它抄进你的技术文档里，过几个版本就成了错的。真要控制这件事，就显式传值，别依赖默认。
想传 Gemini 专有字段，走 extra_body
兼容层不可能把 Gemini 的所有能力都映射成 OpenAI 的字段，剩下那些走 extra_body 透传。官方给的路径是：
extra_body.google.thinking_config.{thinking_level, include_thoughts}
也就是说，在 google 这个命名空间下的 thinking_config 里，官方点名了两个字段：thinking_level 和 include_thoughts。前者就是上一节说的那个跟 reasoning_effort 互斥的档位字段；后者从字面上是控制思考内容是否包含在返回里，但官方文档里没有找到关于 include_thoughts 返回结构的进一步说明，具体返回什么形态、放在响应的哪个位置，以官方文档为准，我这里不替它补。
另外，Gemini 3 支持在 chat completions API 中使用 OpenAI 兼容的思考签名（thought signatures）。这一条之所以值得单独记住，是因为官方的生成结构错误码里有一个 missing_thought_signature，含义是响应缺少必需的 thought 签名。官方给的只有这个码的含义本身，什么样的调用方式会导致签名缺失、缺了之后要怎么把它补回去，官方文档里没有找到说明，所以真碰上它别顺着别人的猜测排查，回官方错误码参考页对。相关的还有 malformed_function_call、unexpected_tool_call、too_many_tool_calls 等几个，同属生成结构错误族。这一族和前面那些请求级错误码的区别值得记一下：parameter_unknown、invalid_request 这类指向的是你发出去的请求本身格式有问题，而生成结构这一族，官方的归类是模型输出本身有结构问题——两者的排查起点完全不在一处，一个查自己的请求体，一个查模型返回的内容结构。
这个参数的账单落点在输出栏
调这个参数的时候容易只盯着效果，忘了它是有价签的。Gemini 定价页的表头写得很直白：输出价格（包括思考 token）。
这句话的含义是：思考过程消耗的 token，不单列一栏，直接并进输出 token 计费。所以把 reasoning_effort 往上调，账单上不会出现一个叫「思考费用」的新条目，你只会看到输出 token 数变多——排查账单的时候极容易归错因，以为是回答变长了。
配合官方给的另一组计费事实一起看会更清楚：Gemini 的计费依据是四项——输入 token 数、输出 token 数、缓存的 token 数、缓存 token 的存储时长。思考 token 藏在第二项里。至于结算延迟，官方明确写了结算流水线有分钟级的延迟，期间可能产生超额用量，而批量模式与 Agent 这类长时间运行的任务尤其容易在系统停止之前继续消耗。一个把 reasoning_effort 拉满的 Agent 长跑，正好同时踩中「思考 token 计入输出」和「结算延迟期间继续消耗」这两条。
想把这块管起来，可以对着通用的 API 成本监控做法搭一层自己的用量统计，别只依赖平台账单页——官方还提到总费用明细图表的更新是有滞后的。更省的方向可以参考输入侧成本优化的思路，以及 Gemini 自己的隐式缓存命中办法。这两件事在账单结构上落在不同的项：官方给的计费依据四项里，「缓存的 token 数」和「缓存 token 的存储时长」是单独的两项，而思考 token 是并进「输出 token 数」那一项的。至于把缓存做起来之后会不会连带影响思考 token 这一侧，官方文档里没有找到相关说明，所以别预设两边能互相抵消，分开各算各的账更稳。
关不掉推理的那批模型
这是本文最该记住的一条硬事实，官方把它写成了明文限制，值得原样抄走。
官方给的关闭方式是：Gemini 2.5 系列可以把 reasoning_effort 设为 "none"。但紧接着有一条明文限制——Gemini 2.5 Pro 与 Gemini 3 系列无法关闭推理。
注意这条限制的边界：它不是「2.5 都能关、3 都不能关」这么整齐。2.5 系列里的 Pro 单独被排除在外，跟 Gemini 3 系列站在同一边。所以那种「我们统一给所有模型加个 none 把思考关掉降本」的方案，从一开始就不成立——它在一部分模型上是有效开关，在另一部分模型上不是。
再往下一步，很多人会想问：那在关不掉推理的这批模型上，仍然把 reasoning_effort 传成 none 会怎么样，是被忽略、报错，还是别的行为？官方文档里没有找到关于这一点的说明，我这里也不替它猜。你能拿到的确定信息只有「无法关闭推理」这一句，那就按这一句来做方案设计：不要把「传了 none 就不产生思考 token」当成成本测算的前提。真要在这批模型上控成本，方向只能是换档位、缩输入、缩输出，而不是指望有开关能一键关掉。
收尾：三个最容易栽的坑
第一，别在项目里同时出现 reasoning_effort 和 thinking_config。官方只说了不能同时用，没说同时用会怎样，所以你也别指望报错能提醒你，靠代码规范堵。
第二，换模型代际时必须复查这个参数。同一个值在 3.x 上落到 thinking_level、在 2.5 上落到 thinking_budget，目标字段换了一个，行为不会自动等价。
第三，别把 none 当成通用降本开关。2.5 Pro 和 Gemini 3 系列关不掉推理是官方写死的，方案设计阶段就得把这批模型摘出来单独处理。
再补一句方向性的：如果你不是从 OpenAI SDK 迁过来的存量项目，官方自己的建议是直接用原生 API。少一层映射，就少一整类「我传的参数到底被翻译成了什么」的排查成本。