概要

Google Gemini 3.1 Pro是2026年上半年热度较高的多模态大模型之一。Google I/O 2026刚结束，Gemini 3.5 Flash已经发布，但3.1 Pro作为推理旗舰在API调用场景中仍然有大量开发者在用。本文从零开始完整走一遍Gemini 3.1 Pro的API接入流程，覆盖密钥获取、SDK安装、首次调用、多模态输入、思维模式配置等核心环节。适合没有Gemini开发经验的开发者快速上手。如果需要横向对比多个模型的API接入差异，可以用库拉c.877ai.cn这类AI模型聚合平台一站接入，省去分别注册的麻烦。

---

整体架构流程

Gemini API的整体调用架构分四层：

text

text

客户端应用 → Google AI SDK → Gemini API Endpoint → Gemini 3.1 Pro模型 

客户端通过SDK向API Endpoint发送请求，请求中包含模型名称、消息内容、思维模式配置等参数。Endpoint返回模型生成的文本、代码或多模态内容。

支持的接入方式有三种：Google AI Studio网页端直接调用、Python SDK接入、Node.js SDK接入。Android开发还可以通过Android Studio内置的Gemini集成直接使用。

API密钥通过Google AI Studio生成。官方提醒：请安全使用密钥，不要分享也不要嵌入公众可查看的代码中。

---

技术名词解释

Gemini 3.1 Pro：Google DeepMind推出的推理旗舰模型。ARC-AGI-2得分77.1%，GPQA Diamond得分94.3%。支持100万token上下文窗口和Low/Medium/High三级思维配置。

Google AI Studio：Google提供的在线AI开发平台，支持模型测试、API密钥管理和prompt调试。目前提供免费的API访问额度。

google-genai SDK：Google官方提供的Python SDK包名。通过pip安装，封装了API认证、请求构建和响应解析的完整逻辑。

思维模式（Thinking Mode）：Gemini 3.1 Pro支持Low、Medium、High三档配置。Low模式响应最快适合简单任务，High模式推理最深适合复杂分析。Medium是默认推荐档位。

多模态输入：Gemini支持文本、图像、音频、视频作为输入。不是先转文字再处理，而是原生多模态统一处理。这个设计在读PDF和分析图表时有结构性优势。

上下文窗口（Context Window）：模型单次请求能处理的最大token数量。Gemini 3.1 Pro支持100万token，大约相当于500页PDF或11小时音频。

SynthID：Google开发的水印技术，能在AI生成内容中嵌入不可感知的标识。Gemini 3.5 Flash生成的所有音频都采用SynthID进行水印标记。

---

技术细节

第一步：获取API Key

访问Google AI Studio，用谷歌账号登录。点击"Get API Key"按钮，选择"Create API key in new project"或在现有项目中创建。生成后立即复制保存，页面关闭后无法再次查看。

Google Cloud新用户有免费额度可以直接体验。Gemini 3.1 Pro定价每百万输入token 2美元、输出12美元。对比GPT-5.5的5美元输入和Claude Opus 4.6的15美元输入，性价比优势明显。

第二步：安装SDK

Python环境一行命令安装：

bash

bash

pip install google-genai 

Node.js环境：

bash

bash

npm install @google/genai 

安装完成后验证版本号确认安装成功。如果网络环境受限，可以配置镜像源加速下载。

第三步：首次调用

Python示例代码：

python

python

from google import genai  client = genai.Client(api_key="你的API_KEY")  response = client.models.generate_content(  model="gemini-3.1-pro",  contents="用Python写一个读取CSV并统计每列均值的函数" )  print(response.text) 

几行代码就能收到Gemini的响应。如果报错先检查Key是否复制完整，再确认网络环境。模型名称不要搞混，gemini-3.1-pro和gemini-3.5-flash是不同模型。

第四步：配置思维模式

python

python

from google.genai import types  response = client.models.generate_content(  model="gemini-3.1-pro",  contents="分析这段代码的性能瓶颈",  config=types.GenerateContentConfig(  thinking_config=types.ThinkingConfig(  thinking_budget=4096 # High模式  )  ) ) 

简单任务设thinking_budget=512（Low），日常任务设2048（Medium），复杂推理设4096以上（High）。High模式消耗的token大约是Low的3到4倍，响应时间也更长。建议先用Medium试，不够再切High。

第五步：多模态输入

上传图片分析：

python

python

from google.genai import types import PIL.Image  image = PIL.Image.open("screenshot.png")  response = client.models.generate_content(  model="gemini-3.1-pro",  contents=[image, "分析这张图表的数据趋势"] ) 

上传PDF文档：

python

python

pdf_data = open("report.pdf", "rb").read()  response = client.models.generate_content(  model="gemini-3.1-pro",  contents=[  types.Part.from_bytes(data=pdf_data, mime_type="application/pdf"),  "总结这份报告的核心观点"  ] ) 

Gemini的原生多模态架构让它能直接"看"到PDF的原始布局和图表信息。100万token窗口意味着500页PDF可以一次性处理，不需要分段。

支持的模型类型

模型名称	定位	输入价格	输出价格	速度
gemini-3.1-pro	推理旗舰	$2/M	$12/M	中等
gemini-3.5-flash	速度旗舰	$1.5/M	$9/M	289 tokens/s
gemini-3.1-flash	轻量版	$0.5/M	$2/M	较快

Gemini 3.5 Flash输出速度289 tokens/s，是3.1 Pro的数倍。日常编码和快速任务用Flash更划算，深度推理用Pro。

常见踩坑

Key暴露在前端是最常见的安全问题，密钥必须存在后端。model参数不要搞混，不同版本的能力和价格差异很大。system_instruction超过2048字符会被静默截断且不报错，效果不好先检查是不是被截了。

Grounding功能通过接入外部数据源可以减少幻觉。对需要基于特定知识库回答的场景，这个功能比单纯调参更有效。

---

小结

Gemini 3.1 Pro的API接入门槛不高，5分钟拿到Key，5分钟跑通首次调用。100万token上下文窗口和原生多模态能力是它的结构性优势。三级思维模式让开发者能根据任务复杂度灵活控制成本和质量。

定价方面Gemini 3.1 Pro每百万输入2美元，对比GPT-5.5的5美元和Claude Opus 4.6的15美元，性价比优势明显。Google AI Studio目前提供免费的API访问额度，但有速率限制。

迭代速度很快。Gemini 3.5 Flash已经发布，输出速度289 tokens/s，编码能力超过3.1 Pro。3.5 Pro预计下个月推出。选型时要看场景不看版本号。混合使用多个模型按任务类型分配是当前比较务实的策略。

拿自己的真实项目跑一遍测试，比看任何排行榜都靠谱。有问题欢迎评论区讨论。