Gemini 3.5 Flash API 接入方法：从密钥获取到生产部署的完整指南

Gemini 3.5 Flash 是谷歌在2026年I/O大会上发布的新一代旗舰级智能体与编程模型，5月19日正式上线，已通过 Gemini API、Google AI Studio、Antigravity 2.0 和 Vertex AI 全面开放。它用Flash级的成本做到了超越上一代Pro旗舰的性能——MCP Atlas多步骤智能体基准测试拿下83.6%，定价仅为同类前沿模型的不到一半。本文从零开始，覆盖密钥获取、SDK安装、API调用、旧版迁移、常见问题排查和进阶路径，帮你用最短时间完成接入。

本文大纲

• 🔑 第一步：获取 API 密钥
• 📦 第二步：安装 SDK 与环境配置
• ⚡ 第三步：首次调用——最简单的代码示例
• 🔄 从旧版迁移：必知的破坏性变更
• 🧠 配置 Thinking 思考等级
• ⚠️ 常见问题与排错
• 🚀 进阶路径：从测试到生产

图源：AI生成示意图

一、第一步：获取 API 密钥

两种入口可以获取 Gemini 3.5 Flash 的 API 密钥，开发者可以根据使用场景灵活选择。

Google AI Studio 是官方推荐的快速体验入口。访问 https://aistudio.google.com，登录Google账号，点击“Get API Key”或在左侧导航栏找到API密钥管理页面，即可创建免费的API Key。免费层级每天约1500次请求，适合个人开发、原型验证和轻量测试。

Google Cloud Console / Vertex AI 适合企业级和生产部署场景。在Cloud Console中启用Vertex AI API，创建服务账号并下载JSON密钥，新注册用户可获得300美元免费额度（有效期90天）。Vertex AI提供更高的并发配额和企业级SLA，适合流量较大的生产环境。

密钥安全提醒：不要将API密钥硬编码在代码中或提交到版本控制系统。建议通过环境变量管理。Google Cloud Console支持设置API密钥的引用来源限制（HTTP引荐来源、IP地址或应用包名），可以有效防止密钥泄露后被恶意调用。

二、第二步：安装 SDK 与环境配置

谷歌推荐使用最新版 google-genai SDK（v2.0.0或更高版本），官方代码示例均基于全新的 Interactions API。

Python 安装：在终端中执行以下命令即可完成安装，系统要求Python 3.9及以上版本。

pip install -U google-genai

Node.js 安装：谷歌为Node.js提供了官方SDK，也可以通过npm一键安装，同时支持服务端与浏览器环境。

npm install @google/generative-ai

配置API密钥：将API Key写入环境变量是最简单的安全实践。

# macOS / Linux
export GOOGLE_API_KEY="你的API密钥"

# Windows PowerShell
$env:GOOGLE_API_KEY="你的API密钥"

重要提醒：google-genai v2.0.0包含了Interactions API的重大变更，旧项目直接升级可能会导致代码失效，必须同步修改调用逻辑。

三、第三步：首次调用——最简单的代码示例

以下示例基于官方推荐的 Interactions API。如果你的项目使用了旧版 GenerateContent API，可以继续使用但建议逐步迁移。

Interactions API 示例：

from google import genai

# 创建客户端（自动读取 GOOGLE_API_KEY 环境变量）
client = genai.Client()

# 创建一次交互并获取输出
interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="用三句话解释什么是并行智能体执行。"
)

# 打印结果
print(interaction.output_text)

GenerateContent API 示例（兼容旧版写法） ：

from google import genai

client = genai.Client()
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="AI是如何工作的？"
)
print(response.text)

模型ID：稳定版为 gemini-3.5-flash，当前快照版本为 3.5-flash-05-2026。

上下文窗口：100万Token输入，支持文本、图像、视频、音频和PDF多模态输入。

四、从旧版迁移：必知的破坏性变更

如果你正在使用 gemini-3-flash-preview 或 gemini-3.1-pro，迁移到3.5 Flash时有以下四点必须同步修改，否则应用会静默降级或报错。

1. Thinking参数类型变更（最关键的破坏性变更）

这是最容易导致静默降级的改动。旧版使用整数 thinking_budget（如2048），新版改为字符串枚举 thinking_level，支持 minimal、low、medium、high 四个值，默认值从 high 调整为 medium。如果只替换模型名而不改参数名，Thinking机制将完全失效。

# ❌ 旧版写法（gemini-3-flash-preview）
response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents=prompt,
    config=genai.types.GenerateContentConfig(
        thinking_config=genai.types.ThinkingConfig(
            thinking_budget=2048  # 整数，不再支持
        ),
        temperature=0.7  # 不再推荐
    )
)

# ✅ 新版写法（gemini-3.5-flash + SDK v2.0.0）
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=prompt,
    config=genai.types.GenerateContentConfig(
        thinking_config=genai.types.ThinkingConfig(
            thinking_level="low"  # 字符串枚举
        )
        # temperature 参数已移除，不再推荐
    )
)

2. SDK版本必须同步升级：必须使用 google-genai v2.0.0或更高版本，旧版SDK不支持 thinking_level 参数。

3. 思考上下文默认保留：跨轮次思考保留功能默认开启，推理上下文在对话轮次之间延续，能提升多轮任务效果，但会增加Token消耗。

4. 函数调用需添加id字段：所有 FunctionResponse 部分现在需要包含 id 字段和匹配的名称，旧代码中的函数调用返回格式需要同步更新。

关于 low 的含义：它并不意味着“跳过推理”，谷歌专门针对代码和智能体任务重新调校了 low 档位。如果你的应用在迁移后出现过多的工具调用，可以先降低思考等级再观察效果。

五、配置 Thinking 思考等级

Thinking机制是3.5 Flash性能大幅提升的核心因素，四档思考等级让开发者根据任务复杂度灵活调节推理深度。

使用原则：简单任务用 minimal 或 low 省钱提效，复杂智能体工作流用 medium 或 high 保证准确率。

六、常见问题与排错

• API Key报 "403 Forbidden"：检查API Key是否已在Cloud Console启用 Generative Language API，且未超出配额。
• 请求报 "429 Resource Exhausted"：表示已触及RPM/TPM配额上限，建议降低调用频率或申请提升配额。可以在代码中实现指数退避重试（等待1秒→2秒→4秒→8秒）。
• 模型输出质量下降：检查是否已同步升级SDK至v2.0.0，旧版SDK可能无法正确传递 thinking_level 参数导致静默降级。
• 温度参数不生效：temperature、top_p、top_k 在3.5 Flash中已不再推荐使用，即使传入也可能被忽略，建议从配置中移除。
• 密钥安全：建议使用环境变量存储API密钥，Cloud Console支持设置密钥的引用来源限制。

七、进阶路径：从测试到生产

• Google AI Studio Playground：https://aistudio.google.com，零代码环境，可在Web界面直接测试提示词、调节参数并导出SDK代码。
• Managed Agents API：一次API调用即可在云端创建一个持久化运行的Agent，支持多轮会话和代码执行，适合构建复杂的智能体工作流。
• Antigravity 2.0：谷歌版Agent开发平台，支持动态子Agent并行调度和定时后台任务，与3.5 Flash深度协同可实现12倍加速。
• Vertex AI：企业级生产部署入口，提供更高的并发配额、SLA保障和细粒度的权限控制。

总结

Gemini 3.5 Flash 的接入路径清晰：aistudio.google.com 获取免费密钥，pip install google-genai 安装SDK，gemini-3.5-flash 一行模型ID即可调用。关键在于正确处理旧版迁移中的破坏性变更。对于需要将大模型 Agent 的推理能力与企业内部复杂业务系统深度结合、在严格安全合规下实现自动化的团队，实在Agent 通过“TARS大模型+ISSUT智能屏幕语义理解+RPA引擎”三位一体架构，弥补了Agent“思考”与“执行”之间的断层。它不依赖软件接口，可跨系统操控各类新旧业务应用，尤其适合金融、电商、跨境、制造业等流程复杂的行业。已通过中国信通院智能体平台最高等级评估，支持私有化部署与全链路操作审计。重复性读取、填表由RPA引擎执行，不消耗大模型Token；企业可自由选用DeepSeek、智谱AI、通义千问、Kimi等国产大模型进行私有化部署，从源头控制AI支出。目前已服务超5000家企业。

预约实在Agent企业效能顾问

深度诊断企业痛点，定制专属 AI 自动化办公方案

联系我们 →立即试用