Google python-genai发布v3.0.0：Gemini Developer API默认版本改为v1，HTTP客户端换为httpx2
该版本标记为破坏性变更：使用Gemini Developer API的客户端现在默认请求v1，而非此前的v1beta；Vertex AI/Enterprise客户端默认仍为v1beta1。SDK默认HTTP客户端改为httpx2，httpx不再随包默认安装。
AI解读：python-genai 3.0.0（2026-11-05）有两项破坏性变更：Gemini Developer API默认版本由v1beta改为v1；默认HTTP客户端由httpx改为httpx2，httpx不再默认安装。
Gemini Enterprise（Vertex AI）默认值不受影响，vertexai=True或enterprise=True的客户端继续默认使用v1beta1。
恢复旧默认值可通过环境变量GOOGLE_GENAI_API_VERSION设置，也可以在代码中通过HttpOptions的api_version指定，后者的优先级更高。
要切回httpx，需要同时安装google-genai[httpx] 并设置GOOGLE_GENAI_HTTP_CLIENT=httpx；官方称多数情况下把导入改为import httpx2 as httpx即可迁移。
release notes还列出新功能与修复，包括在AudioTranscriptionConfig中增加source_text、FinishReason增加MALFORMED_RESPONSE、interactions中CodeExecutionResultStep.result改为联合类型等。
Google的python-genai发布 3.0.0 版本（2026-11-05），release notes将其中的两项标为破坏性变更：客户端连接Gemini Developer API时默认使用v1而非v1beta；默认HTTP客户端从httpx改为httpx2，且httpx不再随包默认安装。
Gemini Developer API默认版本改为v1，Enterprise不受影响
release notes说明，使用Gemini Developer API的客户端现在默认请求API版本v1，此前为v1beta。vertexai=True或enterprise=True的客户端不受该变更影响，仍默认使用v1beta1。
- 恢复旧默认：设置环境变量GOOGLE_GENAI_API_VERSION=beta，在Gemini Developer API上恢复为v1beta，在Enterprise/Vertex AI上恢复为v1beta1。
- 也可以设置具体的版本字符串，例如GOOGLE_GENAI_API_VERSION=v1beta。
- 在代码中通过HttpOptions传入api_version，优先级高于环境变量。
默认HTTP客户端换为httpx2
第二个破坏性变更将默认HTTP客户端改为httpx2，httpx不再是默认安装的依赖，httpx2成为必需依赖。release notes称多数情况下把导入改为import httpx2 as httpx即可迁移。
在SSL证书验证上，当SSL_CERT_FILE和SSL_CERT_DIR未设置时，httpx2默认使用操作系统证书信任库（经truststore / httpx2.create_ssl_context()），而非certifi。
- 要恢复httpx作为默认客户端，需要同时安装httpx扩展并设置GOOGLE_GENAI_HTTP_CLIENT=httpx。
- 也可以在安装google-genai[httpx] 后，通过HttpOptions传入httpx.Client / httpx.AsyncClient。
- 传入HttpOptions(client_args=..., async_client_args=...) 的包特定对象（Timeout、Limits、MockTransport / BaseTransport、自定义Auth子类）以及捕获的传输异常，必须与当前启用的HTTP客户端匹配。
- 当GOOGLE_GENAI_HTTP_CLIENT未设置或为auto时，若已安装google-genai[httpx]，传入httpx对象会自动选择httpx后端。
其他功能与修复
除上述破坏性变更外，release notes还列出新增功能、修复和文档更新。
- interactions：CodeExecutionResultStep.result由string改为CodeExecutionResultStepResult联合类型；读取result为字符串的代码需要先判断变体。纯文本结果的JSON不变。
- interactions新增对Office和OpenDocument MIME类型的支持，并支持CodeExecutionResultStep.result中的多模态内容。
- AudioTranscriptionConfig和SmartTranscriptionMode增加source_text。
- FinishReason增加MALFORMED_RESPONSE。
- CLI的transcribe命令默认模型改为gemini-3.5-transcribe。
- 在Gemini API上禁用GenerateVideos，并更新测试与README。
- 修复interactions重试次数（retries = attempts - 1），保留Interactions模型中的未知字段与开放联合变体，并让Gemini API文件上传遵循配置或默认的API版本。
- 文档方面，嵌入示例从gemini-embedding-2-preview更新为gemini-embedding-2，其余文档链接从ai.google.dev更新为aistudio.google.com。