Gemini3.5API入门指南从获取密钥到首次多模态调用

最近在leadhi.cn这类AI工具聚合平台上对比各家模型的API接入体验，发现Gemini 3.5的多模态能力值得每个开发者关注。Google从设计阶段就把Gemini定位为原生多模态模型，不是把文本、图像、音频模块拼接在一起，而是从一开始就统一处理多种模态的数据。这篇文章从零开始，带你走通接入Gemini API的完整流程。

为什么值得试Gemini API

免费额度够入门。 Google AI Studio提供免费使用层，每位开发者可以获得每天30万token的免费额度，以及每分钟60个请求的速率限制。不需要信用卡就能开始。

多模态原生支持。 Gemini从一开始就在不同模态上进行预训练，然后利用额外的多模态数据进行微调。这种原生设计让它在跨模态任务时表现更好。一次API调用中能够处理图像、视频、音频和PDF等多种输入。

功能丰富。 不仅支持文本生成，还支持图像理解、音频处理、视频分析、函数调用。开发者可以传递函数说明，模型会返回匹配的函数和参数，然后在外部API中调用。

第一步：获取API密钥

访问Google AI Studio，用Google账号登录。在左侧面板找到API密钥管理入口，点击"Create API key in new project"即可。免费的API密钥可以多次生成。

这一步需要满足网络和区域条件。如果遇到区域不支持的报错，有开发者通过部署serverless代理项目来解决，把Gemini API转换为兼容格式。

获取密钥后，在项目环境文件中粘贴密钥并设置环境变量即可开始调用。Google承诺不会利用免费版用户的输入和输出数据进行模型训练。

第二步：选择模型

Gemini API提供多个模型变体：

Gemini Pro： 通用模型，适合各种基础任务。已集成到Google产品中，免费使用。

Gemini Flash： 快速且强大，拥有100万个token的上下文窗口。适合文档分析和内容生成等应用。

Gemini Flash-8B： 轻量版，功能全免费。适合聊天机器人或教育工具等简单任务。

Gemini Pro（高级版）： 配备200万token上下文窗口。适合需要处理大量数据的复杂场景。

选择逻辑：快速验证用Flash-8B，日常开发用Flash，深度分析用Pro。

第三步：文本生成调用

安装官方Python库后，配置环境变量填入API密钥，初始化Client实例即可开始。

文本生成是最基础的调用方式。支持多种调用方法：generate_text用于纯文本生成，chat方法实现带上下文记忆的连续对话，get_embedding用于获取文本向量表示。

关键参数说明：

temperature： 控制输出随机性。设为0输出最确定，设为1最有创造性。数据分析类任务建议0.2到0.4，创意写作建议0.7到0.9。

maxOutputTokens： 控制最大输出长度。根据实际需求设置，避免不必要的token消耗。

systemInstruction： 系统指令，用于设定模型的角色和行为规范。写得越具体，输出质量越高。不要只写"你是一个助手"，要写清楚角色、能力范围和输出格式要求。

第四步：多模态调用

这是Gemini API最核心的能力。

图像理解： Gemini Pro Vision支持图片输入。你可以上传一张截图，问"这张图片中有什么"，模型会识别图片内容并结合文字问题给出分析。Gemini在不使用OCR系统的情况下，图像基准测试表现优于之前最好的模型。

图片输入有两种方式：

URL引用——直接在请求中提供图片的URL地址，API会自动下载并分析。适合公开可访问的图片。

Base64编码——将图片文件转为Base64字符串，嵌入到请求体中。适合本地文件或者需要认证才能访问的图片。

PDF处理： 支持一次API调用中处理PDF等多种输入。上传PDF文件，让它提取关键信息或生成摘要。

函数调用： 开发者可以传递函数说明，模型返回匹配的函数和参数。适合需要实时数据查询的场景——比如查询数据库、调用外部接口、检索知识库。

在API请求中，多种模态的数据可以同时嵌入到请求体中。你可以同时发送多张图片、PDF文件和文字描述，模型会综合分析。这个能力在文档解读、图表分析、UI截图识别等场景下非常实用。

第五步：进阶能力

Google搜索接地： 通过在API请求中启用搜索接地功能，模型可以在回答中引用最新的网络信息，并提供来源。这让模型的回答不再局限于训练数据。

代码执行： Gemini API内置代码执行能力，可以直接在服务端运行Python代码进行数据计算。不需要自己搭建代码运行环境，特别适合数据分析和可视化的场景。

缓存优化： 对于重复发送的相同前缀内容（比如固定的系统提示词），Gemini API支持Prompt Caching机制。缓存命中后输入token的成本可以大幅降低。这对Agent场景下的token优化尤为关键。

和其他API的对比

对比OpenAI API： OpenAI的API生态更成熟，文档更丰富。但Gemini API在多模态输入方面更原生。而且Gemini的免费额度更慷慨。如果你的项目需要同时处理图片、视频、音频，Gemini的接口设计会更简洁。

对比Claude API： Claude在长文档理解和代码生成上有优势。但Claude API目前不支持图片生成和实时语音，这是Gemini的独有能力。

对比国内模型API： 国内模型在国内访问速度更快，中文理解更地道。但Gemini在多模态能力和免费额度上有优势。

选择的核心逻辑是看你的使用场景。国内业务优先考虑国内模型，国际化场景或多模态需求优先考虑Gemini。很多团队的做法是混合使用：简单任务用国内模型控制成本，复杂多模态任务用Gemini保证质量。

几个必须注意的坑

坑一：Token计算。 图片和视频的token消耗远高于文本。一张高清图片可能消耗几百个token，一段视频可能消耗数万token。在多模态场景下要特别注意成本控制。

坑二：速率限制。 免费层有每分钟请求次数限制。遇到429错误说明触发了限流。可以通过申请提升配额或者加入付费计划来解决。

坑三：输出格式不可控。 即使在提示词里要求JSON格式输出，模型偶尔也会输出带额外文字的非标准JSON。建议在代码层做格式校验和容错处理。

坑四：原生多模态的局限。 Gemini在精确对象定位、对象计数、长视频理解等方面仍有不足。在多轮多模态对话中表现也有待提升。在实际项目中要做好边界处理。

趋势判断

AI API市场的竞争正在从"谁更聪明"转向"谁更好用"。Google正在将Gemini集成到搜索、浏览器等核心产品中。随着更多产品接入Gemini，API的使用场景会持续扩大。

Gemini 3.5 Pro原生支持第三方工具接入，这意味着你可以把API直接接入到自己的Agent框架中，让模型自主决定调用哪些工具、按什么顺序执行。

对开发者来说，掌握一个AI API的接入能力，已经从加分项变成了基本功。

写在最后

Gemini 3.5 API的入门门槛不高——拿到密钥、选好模型、构造请求，三步就能跑通。多模态原生支持和函数调用是它区别于其他API的核心优势。

但API只是工具，真正决定项目成败的是你怎么用它。先从免费额度开始验证想法，确认可行后再考虑付费升级——这个节奏最稳妥。