Gemini 3.8 Flash Python 教程：从安装到第一次调用，附 thinking_level 参数避坑清单

Gemini 3.8 Flash 已于 2026 年 9 月 2 日正式 GA，model id 就是 gemini-3.8-flash。如果你打算把旧代码里的模型名一换直接上线，大概率会撞上报错：这一代不只是换了模型名，参数体系也动了大手术。thinking_budget 整数预算被 thinking_level 枚举取代，temperature、top_p、top_k、candidate_count 全部废弃，旧代码原样迁移几乎必然触发 400 类错误。

先给结论：跑通第一次调用只需要三步——安装 google-genai SDK（2.3.0 及以上版本）、设置 GEMINI_API_KEY 环境变量、用 model id gemini-3.8-flash 调用 client.interactions.create。迁移旧代码只需要记住两件事：thinking_budget 换成 thinking_level（取值 low / medium / high，默认 medium），temperature、top_p、top_k、candidate_count 直接删掉。

这篇教程解决两件事：一是用最短路径跑通第一次调用，包括纯文本和 text+image 多模态两个示例；二是给一份从报错现象出发的迁移避坑清单，每个参数变更都配「旧写法 vs 新写法」代码对比。Google 官方对这款模型的定位表述是 "most intelligent Flash model"，主打长周期软件工程、自主智能体和复杂企业级任务，本文不展开能力评测，只管把它调通。

跑通第一个调用前，需要准备什么？

只需要两样东西：一个 API key，一个装好 SDK 的 Python 环境。

第一步：拿 API key。 到 Google AI Studio 免费创建一个 API key，然后设为环境变量 GEMINI_API_KEY。macOS 和 Linux 在终端执行：

export GEMINI_API_KEY="你的 API Key"

Windows 用户可以在系统设置里添加同名环境变量，或用 set 在当前会话临时设置。key 不要写死在代码里，尤其是会提交到仓库的项目。

第二步：装 SDK。

pip install -U google-genai

版本上有两个数字需要留意：调用 Gemini 3.8 Flash 使用的 Interactions API，官方要求 google-genai 包不低于 2.3.0；截至本文核验时（2026 年 9 月 3 日），PyPI 上已发布到 2.22.0，直接 pip install -U 装到的就是可用版本。Python 版本要求 3.10 及以上。不确定自己装的版本，用 pip show google-genai 查一下。

别装错包：google-generativeai 和 google-genai 是两个不同的包。前者是旧 SDK，官方已停止在其上开发新功能；调 Gemini 3.8 Flash 用的是后者。项目里如果还留着旧包，建议顺手清理，避免 import 混淆。

gemini-3.8-flash 的最小文本调用怎么写？

先确认 model id：gemini-3.8-flash，GA 版本，没有 preview 后缀。官方模型页标注的输入上限约 100 万 tokens（1,048,576），最大输出 65,536 tokens，支持文本、图片、视频、音频、PDF 五种输入模态。另外，同期发布的 Gemini 3.8 Flash Cyber 是另一个模型，不在本文范围内，别把 model id 搞混。

写第一行代码之前，有一个结构性差异必须先点破：官方 quickstart 文档的示例已经全面改用 Interactions API，调用入口是 client.interactions.create——这是官方文档当前主推的调用范式，一次调用对应一个 interaction 对象，纯文本结果从 interaction.output_text 取。而网上大量还在流传的教程（多是 Gemini 2.5 时代的文章）用的是 client.models.generate_content。旧接口依然存在，但本文所有「新写法」统一用 Interactions API，旧接口只会在下文的「旧写法」对照里出现。照抄旧教程学调用方式，会和官方文档对不上。

下面是最小可运行示例，来自官方 quickstart 与 What's new 文档：

from google import genai

client = genai.Client()  # 自动读取环境变量 GEMINI_API_KEY

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="用一句话解释什么是 API 的上下文窗口",
)

print(interaction.output_text)

第一次调用失败，按这个顺序排查：

1. 代码在 client.interactions 这一步就报属性不存在：大概率是 SDK 版本低于 2.3.0，回到上一步升级。
2. 认证失败：环境变量 GEMINI_API_KEY 没设置，或者变量名拼错。
3. 模型不存在：model id 拼错，正确写法是 gemini-3.8-flash，注意没有 preview 后缀。

genai.Client() 不传参数时会自动读取环境变量，这是官方 quickstart 的默认做法；需要 thinking tokens 用量等结构化数据时，官方文档另有说明。

text+image 多模态输入怎么发？

多模态调用和纯文本的区别只在 input：纯文本传一个字符串，多模态传一个列表，文本和图片各占一项。下面的示例结构来自官方 quickstart，原例的模型是 gemini-3.5-flash 且包含音频输入，这里替换为 gemini-3.8-flash 并裁掉了音频部分：

import base64
from google import genai

client = genai.Client()

with open("example.jpg", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "简要描述这张图片的内容"},
        {
            "type": "image",
            "data": image_data,
            "mime_type": "image/jpeg",
        },
    ],
)

print(interaction.output_text)

图片以 base64 编码传入，mime_type 按实际文件类型填。视频、音频、PDF 走同样的 input 列表结构，具体字段写法以官方文档为准，本文不展开。图片的格式与大小限制同样以官方文档为准，这里不给出具体数字，避免过期或误导。

thinking_budget 报 400 了，怎么改成 thinking_level？

从旧版 Flash 迁移代码，这是撞得最多的一个坑，单独拆开讲。先明确新参数是什么：thinking_level 是一个枚举档位参数，用来控制模型在回答前「想多深」，取代了过去按 token 数量设预算的 thinking_budget。

报错现象有两种。

第一种好识别：旧代码里写着 thinking_budget=1024 之类的整数预算，模型名换成 gemini-3.8-flash 后直接调用报错。

第二种更隐蔽：你已经改用了 thinking_level，但旧参数没删干净，两个同时出现在请求里。官方文档对此有明确表述：thinking_level 与旧 thinking_budget 不能用在同一个请求中，同时使用会返回 400 错误。所以迁移时要把旧的 thinking_budget 行删掉，而不是注释掉留着备用。

原因：控制方式从「预算」变成了「档位」。

旧参数 thinking_budget 是整数 token 预算，你告诉模型最多想多少 token；新参数 thinking_level 是枚举档位，你告诉模型想多深。合法取值只有三个：low、medium、high，不设置时默认 medium。

特别提醒：minimal 不被支持，传入会报错，官方模型页对此有明确说明。从旧模型迁移的用户最容易拿 0 或 minimal 去试，这两个都会直接失败，别在这上面浪费时间。

改法：旧写法 vs 新写法。

旧写法，Gemini 2.5 时代的 generate_content 范式，整数预算：

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="分析这段服务日志，找出可能的性能瓶颈",
    config=types.GenerateContentConfig(
        thinking_budget=2048,  # 整数 token 预算
    ),
)
print(response.text)

新写法，Interactions API 加 thinking_level 枚举：

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="分析这段服务日志，找出可能的性能瓶颈",
    generation_config={"thinking_level": "high"},  # low / medium / high
)
print(interaction.output_text)

三档怎么选。 官方给出的场景描述如下：

迁移时可以按这个原则换算：过去的 thinking_budget 给得越低（0 或几百 token），越应该选 low；给得越高（几千 token），越应该选 high；拿不准就什么都不填，走默认 medium。官方推荐 medium 用于复杂代码与 agent 场景，这正好是 Gemini 3.8 Flash 的主打方向。

temperature、top_p、top_k、candidate_count 为什么全不能用了？

先给结论：这四个参数在 Gemini 3 系列上不是换名字，是直接移除。改法只有一个动作：删。

官方 changelog 的废弃公告写得很直白：采样参数 temperature、top_p 与 top_k 现已废弃。迁移清单同时要求移除 candidate_count，这个参数在 Gemini 3 系列模型上不被支持。注意这是 Gemini 3 系列的统一行为，不是 3.8 Flash 独有的限制，意味着从 Gemini 2.5 迁移过来的代码几乎必然要清理一轮参数。

报错现象：请求里带着这些参数调用 gemini-3.8-flash，典型报错形态是 400 Invalid Argument 类错误。官方没有文档化具体的报错字符串，所以排查时别去逐字比对错误文本，直接检查请求里是否残留废弃参数更快。

旧写法，采样参数控制输出风格（import 与 client 初始化同上一节的旧写法示例）：

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="给这段产品文案起三个备选标题",
    config=types.GenerateContentConfig(
        temperature=0,
        top_p=0.9,
        top_k=40,
        candidate_count=1,
    ),
)
print(response.text)

新写法，采样参数全部移除，由模型自行决定采样策略：

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="给这段产品文案起三个备选标题",
)
print(interaction.output_text)

三个容易漏掉的点：

• top_k 别漏。 部分迁移资料只提 temperature 和 top_p，官方清单里 top_k 同样废弃，搜索代码库时三个一起查。
• temperature=0 的老习惯没法延续。 过去靠调零温度求稳定输出的做法，在 Gemini 3 系列上不再可用，官方给出的迁移做法就是移除参数。如果业务强依赖输出一致性，需要在应用层自己做结构校验或重试。
• candidate_count 同理。 需要多个候选结果的场景，改成多次调用，或在提示里明确要求模型一次给出多个方案。

改完代码，对着这张迁移自查清单过一遍：

调用一次多少钱？thinking_level 怎么选才省钱？

以下为截至 2026-12-31 的优惠价，以官方计价页和实际账单为准：

两个对成本有实际影响的细节：

thinking tokens 计入输出费用。 模型思考得越多，输出侧的 token 消耗越大，所以 thinking_level 的三档选择直接就是成本开关：低延迟、简单任务用 low 天然更省；high 档留给真正需要深度推理的调用。官方把 medium 设为默认档，多数任务照默认走就行，不必额外配置。

2027 年起价格翻倍。 优惠期结束后输入输出都涨到两倍。如果项目在优惠期内跑批量任务，长期成本测算要按 2027 年的标准价做，别按优惠价线性外推。

免费层可用，但官方定价页注明：免费层的数据会用于改进产品。对数据敏感的生产场景，直接走付费层。

跑通之后，下一步看什么？

最小示例跑通后，按这个顺序继续：

1. 清理旧参数。 对照上面的迁移自查清单，把 thinking_budget、temperature、top_p、top_k、candidate_count 全部清掉，再接业务逻辑。
2. 多轮对话。 官方迁移清单对多轮对话另有要求，上下文由服务端通过 previous_interaction_id 维护，写法与旧版把历史拼在请求里不同，细节以官方文档为准。
3. 官方资源。 Gemini API 官方文档站有完整的参数说明和各语言示例；官方 cookbook 仓库有可直接运行的示例代码；需要更高能力档位时，官方模型列表页可以查同系列其他模型。

如果团队需要跨多家模型统一调用与容灾，可以了解 LiteLLM 这类多模型网关方案，它是否已支持 gemini-3.8-flash 需自行确认。站内另有两篇同类指南可以接着看：混元 Hy4 preview 的 reasoning_effort 设置指南，讲的是另一家模型同类的推理档位参数；Claude Fable 5.1 的 API Breaking Changes 迁移指南，结构与本文的避坑清单类似，适合正在做多模型迁移的读者。

谁适合现在就接：需要长上下文、多模态输入的 Python 项目；agent 和代码类场景，这是官方对这款模型的推荐方向；优惠期内有批量处理需求的团队。

谁可以先观望：产品逻辑强依赖采样参数精细调控的团队，迁移前需要评估移除 temperature 后的输出稳定性；对免费层数据政策敏感且预算有限的个人开发者，先读一遍官方定价页的数据说明再做决定。

下一步：跑通文本和图片两个示例，把旧项目的模型调用层按避坑清单过一遍，再决定是否把 thinking_level 作为可配置项暴露给业务层。

常见问题

旧代码 thinking_budget=1024 怎么改？
删掉整数预算，按任务复杂度换成 thinking_level="low"、"medium" 或 "high"。原预算低就选 low，原预算高就选 high，拿不准就不填，默认 medium。

为什么传 temperature=0、top_p=0.9 会报错？
Gemini 3 系列已废弃采样参数，改法是直接移除，不是换名。报错形态通常是 400 Invalid Argument 类。

不设置 thinking_level 会怎样？
默认 medium，官方推荐用于复杂代码与 agent 场景，多数任务可以不设。

thinking_level 能设成 minimal 或 0 吗？
不能。官方模型页明确说明 minimal 不被支持，传入会报错。合法取值只有 low、medium、high。

thinking_level 和 thinking_budget 能同时传吗？
不能。官方文档明确：两者同时出现在一个请求里会返回 400 错误。迁移时把旧的 thinking_budget 行删干净。

旧包 google-generativeai 还能调 3.8 Flash 吗？
官方已停止在该包上开发新功能，应迁移到 google-genai。Interactions API 要求 google-genai 2.3.0 及以上版本。

有免费额度吗？免费层数据会怎么处理？
有免费层。官方定价页注明免费层数据会用于改进产品，数据敏感场景走付费层。

想省钱有什么调用方式？
三个方向：低延迟任务用 low 档减少 thinking tokens 消耗；批量任务走 Batch / Flex，优惠期半价；重复使用的长上下文用上下文缓存，优惠期读取价 $0.075 / 百万 tokens。