Google Gemini API 开发指南：模型、多模态与 SDK

Google 官方把 Gemini API 定位为"从提示到生产的快速通道"：通过官方 SDK，几分钟内就能拿到 API Key 并完成第一次调用。相比纯文本模型，Gemini 系列最大的差异点是原生的多模态能力——图片、视频、音频、文档和文本可以混在同一个请求里。对想在网站或产品里加入 AI 能力、又希望一次接入多种输入类型的开发者，这条路线值得系统了解。

一、Gemini 3 模型矩阵

Gemini API 当前主推 Gemini 3 系列，不同模型按"智能程度 × 速度 × 成本"划分：

Gemini 3.1 Pro：最智能的多模态理解模型，适合复杂推理、深度分析与编程任务。
Gemini 3.5 Flash：以远低于大模型的成本提供接近前沿的性能，兼顾速度与智能，适合智能体和编程场景。
Gemini 3 Flash / 3.1 Flash-Lite：高吞吐、成本敏感的轻量任务首选，适合大体量低延迟流量。
多模态创作：Nano Banana（原生图像生成与编辑）、Veo 3.1（视频生成）、Lyria 3（音乐创作）等媒体模型。
工具与智能体模型：Computer Use（操作数字屏幕）、Gemini Deep Research（自主多步研究）、Antigravity Agent（在隔离沙盒里自主运行代码）。
专业任务模型：Gemini Embedding（多模态嵌入，用于语义搜索与 RAG，可参考 RAG 实现指南）。

版本命名规则值得注意：模型分稳定版（stable）、预览版（preview）、最新版（latest）与实验版（experimental）。生产环境应固定到具体稳定版本，避免 latest 别名热切换带来的行为漂移；实验版不适合线上使用。

日常选型可以对照这张简表：

模型	定位	适合任务	成本档位
Gemini 3.1 Pro	最强理解	复杂推理、深度分析	高
Gemini 3.5 Flash	速度与智能平衡	智能体、编程	中
Gemini 3 Flash / Flash-Lite	高吞吐轻量	分类、抽取、批量	低
Gemini Embedding	多模态嵌入	语义搜索、RAG	低

二、多模态与长上下文

Gemini 的原生多模态是核心卖点：一次请求可以同时输入文字、图片、PDF、视频片段，模型直接理解视觉内容而不需要额外的 OCR 或转写管线。配合百万 token 级的长上下文窗口，可以把整份文档、整段会议录像一次性放入上下文。

实际使用建议：长文档优先走"文件上传 + 上下文"而不是逐段拼接；对海量私有知识，仍建议先做向量化检索（RAG），再让模型基于检索结果回答，兼顾效果与成本。

三、官方 SDK 与 Interactions API

Google 官方维护 google-genai（Python/JavaScript 等）SDK。文档现在推荐用 Interactions API 作为与 Gemini 交互的主要方式：一次调用即可拿到结构化输出，代码非常精简：

from google import genai
client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="Explain how AI works in a few words",
)
print(interaction.output_text)

其他常用能力包括：结构化输出（约束 JSON 格式）、函数调用（把模型接到外部 API 与工具，构建智能体工作流）、流式输出、上下文缓存（Context Caching，降低重复输入的 token 成本）。

函数调用是构建智能体最常用的一环。给模型声明一个工具，模型会在需要时返回结构化的调用参数，由你的代码去执行真实逻辑，再把结果回传，形成闭环：

@client.interactions.tool
def get_stock_price(symbol: str) -> float:
    """查询指定股票的最新价格。"""
    return query_market_data(symbol)  # 你的真实数据源

response = client.interactions.create(
    model="gemini-3.5-flash",
    input="NVDA 今天涨了多少？",
    tools=[get_stock_price],
)
print(response.output_text)

在 AI Studio 里点击右侧的 Tools 面板即可边写边调试函数声明，确认模型何时触发调用、参数是否贴合 JSON Schema。

四、Google AI Studio 与 Vertex AI 双路线

Gemini 提供两条接入路线，开发者按"原型 vs 生产"来选：

Google AI Studio：免费/低成本的快速体验环境，浏览器里直接调试提示词、生成 API Key、跑通第一个调用，适合学习与小规模验证。
Vertex AI：Google Cloud 的企业级平台，提供托管部署、IAM 权限、审计日志、数据驻留与 SLA，适合有合规和运维要求的生产系统。

建议：先在 AI Studio 里验证效果与成本，再迁到 Vertex AI 上线；两条路线使用同一套模型与 SDK，迁移成本很低。

五、定价与成本策略

Gemini 定价同样按输入/输出 token 计费，Flash 系列显著便宜，Pro 系列更贵但能力更强。控制成本的思路与主流平台一致：轻量任务用 Flash 系列、非实时批量任务用 Batch API、固定上下文用 Context Caching、大数据量优先 RAG 而不是全量喂入。多模型并行时建议引入统一网关做预算与日志治理，可参考 AI 网关预算上限实践。

六、16IDC 落地建议

一个具体的落地例子：为多语言站点做客服机器人时，可以用 Embedding 把 FAQ 向量化入库，用户提问后先检索出 3-5 条候选，再用 Gemini 3.5 Flash 结合检索结果生成回答，最后用结构化输出约束回答的语言与来源字段。这样既发挥了 Gemini 的多语言能力，又把每次请求的 token 消耗压在可接受范围。

把 Gemini 接入网站或业务时，最有性价比的路径是"AI Studio 验证 + 官方 SDK 接入 + 长上下文与 RAG 结合"。如果你做的是多语言站点或智能客服，Gemini 的多模态与翻译能力可以直接复用到内容生成与客服机器人上，相关实践可参考网站接入 AI 聊天机器人。别忘了为服务器选型留出向量检索与日志处理的算力——多模态请求的预处理和缓存层仍然落在你自己的基础设施上。

参考：Gemini API 定价页 https://ai.google.dev/gemini-api/pricing
参考：官方函数调用文档 https://ai.google.dev/gemini-api/docs/function-calling

原文来源：https://ai.google.dev/gemini-api/docs

Google Gemini API 开发指南：模型、多模态与 SDK