Gemini API 的 v1 是稳定版且 Interactions API 已 GA，v1beta 放早期特性；SDK 默认 v1beta，http_options 可切 v1。（核验 2026-11-05，F6、F7、F67）

一、Gemini API 的版本怎么选：问题不是新旧，而是你要的能力在哪一版

SDK 装对了，第一条请求也通了，接下来会遇到一个看起来很小、实际会影响长期维护的选择：把 api_version 写成 v1 还是 v1beta。

多数人的处理方式是「默认值能用就不管」。这在演示阶段没问题，但两个场景会立刻反噬：一是你要用 Live API 这类只在 beta 的能力，默认值恰好帮了你；二是你要给团队一个稳定契约，默认值恰好坑了你——某天 beta 的字段改了，你的代码跟着塌。

官方对两版的定位写得很清楚（F6）。v1 是稳定版：这一大版本生命周期内特性完全支持，出现破坏性变更就开新的大版本，旧版本在合理期后弃用；v1beta 放的是仍在开发中的早期能力，会随反馈调整。同一页还写明：Interactions API 及其核心特性在 v1 已经 GA。

这句很关键，它推翻了一个常见假设——「新接口只在 beta」。不是的：本教程从头用的 Interactions API，在稳定版就能用。

二、按 Gemini API 能力选版本：最小可运行示例

与其记「该用哪版」，不如把判断写成函数：给一组你要用的能力，返回该选哪一版。

## EXPECT: 文本与结构化输出 → v1 | Live API → v1beta | Context Caching → v1beta
BETA_ONLY = {"live", "live_music", "ephemeral_token", "agents", "webhooks", "caching", "audio_out"}

def pick(features):
    return "v1beta" if set(features) & BETA_ONLY else "v1"

CASES = [
    ("文本与结构化输出", ["text", "structured_output"]),
    ("Live API", ["text", "live"]),
    ("Context Caching", ["text", "caching"]),
]
out = " | ".join(f"{name} → {pick(f)}" for name, f in CASES)
assert pick(["text"]) == "v1"
assert pick(["caching"]) == "v1beta"
assert pick(["live"]) == "v1beta"
print(out)

BETA_ONLY 这一组名字不是凭印象列的，它对应官方版本表里 v1 栏为空、v1beta 栏有标记的那些行（F10）：Live API、Live Music、Ephemeral Tokens、Agents API、Webhooks API、Context Caching，以及 Audio Output（Speech Config）。

三、解释与边界：四条容易搞反的事实

事实一：SDK 默认不是 v1。 官方明说 SDK 默认用 v1beta，目的是让你能用到预览特性；要稳定版得显式指定（F7）。这解释了为什么很多人「什么都没配，却用上了 beta 才有的东西」。

显式切换只有一行，两版语言都给了：

## Python
client = genai.Client(http_options={"api_version": "v1"})

## JavaScript
const ai = new GoogleGenAI({ httpOptions: { apiVersion: "v1" } });

事实二：模型不分版本，特性才分。 版本表上方有一句注：所有模型在 v1 与 v1beta 都支持，那张表跟踪的是特性（端点路由与 schema 参数），不是模型（F67）。所以「新模型必须上 beta」是错的，真正要上 beta 的是 Live API、缓存这类特性。

事实三：beta 独占清单比想象中窄。 函数调用、结构化输出、思考、系统指令、代码执行、搜索接地、URL Context、File Search、Computer Use、MCP、Models API、Files 路由，这些在 v1 全都有。真正只在 beta 的是上面那七项（F10）。

事实四：REST 路径的两种写法并存。 版本页给的端点是 POST .../v1/interactions（F8），而入门页的 REST 示例写的是 .../v1beta/interactions。两处都在官方站内，谁也没说可以互换——这属于待核（F58）。本教程的处理是：按你实际选的版本抄对应示例，不推导「把 v1beta 换成 v1 就行」。

边界。 本节只解决「选哪版」。至于某个特性在两版里的字段差异，属于各章内容；真做迁移时字段对照见 12.1。

四、预期输出与异常分支

真跑输出：

文本与结构化输出 → v1 | Live API → v1beta | Context Caching → v1beta

三个分支，三种后果。判定为 v1 却用了 beta 能力：请求会失败或字段被忽略，这是最隐蔽的一类——不同特性表现不同，有的报错，有的静默降级。判定为 v1beta 但团队要稳定契约：能跑，但某天 beta 改字段你被动挨打。忘了显式指定：SDK 默认 v1beta（F7），你以为在用稳定版，实际没有。

还有一个只在真机上才暴露的分支：把 api_version 传成了 httpOptions（JS 的驼峰写法）混进 Python 代码里，Python 侧不会报「未知参数」，而是直接忽略——这种情况建议在启动时打一行日志把生效版本打出来，见 3.4 的配置校验写法。

五、判据卡：什么时候必须留在 v1beta

该这么做	不该这么做
生产环境显式写 api_version: v1	依赖 SDK 默认值，以为默认是稳定版
要用 Live API／缓存／Agents 才上 beta	认为「新模型只能上 beta」
按选定版本抄对应 REST 示例	把示例里的 v1beta 手动改成 v1 就发
启动日志打出生效版本	上线后靠报错倒推用了哪版

六、来源与核验

• https://aistudio.google.com/api-reference/api-versions.md（核验 2026-11-05，F6、F7、F8、F10、F67）
• https://aistudio.google.com/docs/get-started.md（核验 2026-11-05，F64）

v1 与 v1beta 的 REST 路径是否可互换属于待核（F58）：版本页写 /v1/interactions，入门页示例写 /v1beta/interactions，官方未说明两者关系，正文因此只按原文各自标注，不做替换推导。版本相关事实属「限流／版本／API 结构」档，复核周期三个月，见 1.3。

七、动手试

1. 把 BETA_ONLY 里的 "caching" 删掉，重跑。会先在第 49 行抛 AssertionError，这不是你改错了——那行断言写死「caching 必须判成 v1beta」，规则一删它就该失败，这正是断言的作用。把该行改成 assert pick(["caching"]) == "v1" 再跑，输出变成 Context Caching → v1；验收标准是你能指出这条改动会造成什么线上后果，并说明为什么它不该进提交。
2. 给 pick 加一条规则：当特性集合为空时返回 "v1beta" 并附一句提示。预期输出里第一个用例会变；验收标准是说清「空集合为什么不该一律当成安全默认」。
3. 在你自己的项目里显式写上 api_version，然后在启动时打印生效版本。验收标准：日志里能看到版本值；看不到就说明配置没生效，别急着往下写业务代码。