简介:Gemini API 是 Google 面向开发者开放的多模态大模型接口,一个 API Key 加一个 SDK 就能把 Gemini 系列模型(目前已迭代到 Gemini 3.1 Pro)接入自己的应用,支持文本、图像、音频、视频的输入理解与内容生成,并提供多轮对话、函数调用、结构化输出、上下文缓存等能力^[原文]^。本文按"跑通—进阶—选型—控成本—排错"的顺序展开;如果你正卡在模型选型和多模型统一接入上,可以先看看[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article),它提供模型能力对比、价格对比和统一 API 接入,能省掉逐个平台试错的时间。
第一步,拿 Key。 打开 Google AI Studio(aistudio.google.com),在 Get API key 中创建密钥。个人验证和原型开发走这条通道即可;如果是要上生产、需要私有网络、审计日志和配额隔离,则应走 Vertex AI,用服务账号做鉴权。
第二步,装 SDK。 官方现在主推统一 SDK google-genai,Python 和 Node 都有对应包,旧的 google-generativeai 已不再是演进主线,新项目建议直接用新包。
pip install google-genai
第三步,发起调用。
from google import genaiclient = genai.Client(api_key="YOUR_API_KEY")resp = client.models.generate_content(model="gemini-2.5-flash",contents="用三句话解释什么是多模态大模型",)print(resp.text)
Node.js 写法基本一致:
import { GoogleGenAI } from "@google/genai";const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });const res = await ai.models.generateContent({model: "gemini-2.5-flash",contents: "用三句话解释什么是多模态大模型",});console.log(res.text);
不想引入 SDK 时,直接打 REST 接口也可以:https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent,鉴权头用 x-goog-api-key。
两个容易踩的坑:Key 千万不要写进前端代码或提交到仓库,统一放环境变量或密钥管理服务;免费额度是有每分钟/每天请求数上限的,压测前先确认自己所在的是哪一档。
小文件(图片、短音频)可以直接内联为 base64;超过约 20MB 的文件、以及视频和长音频,先用 File API 上传拿到 URI 再引用,上传的文件默认 48 小时后过期。
from google.genai import typesresp = client.models.generate_content(model="gemini-2.5-pro",contents=[types.Part.from_bytes(data=open("chart.png", "rb").read(),mime_type="image/png",),"这张图的转化率环比变化是多少?给出结论和判断依据。",],)print(resp.text)
长上下文是 Gemini 系列比较突出的能力,整本合同、一整盘会议录像、几十页 PDF 可以一次性投喂,省掉了先切块再检索的一层工程。但要注意:上下文越长,输入 token 成本越高,且长文档中段的召回效果通常不如首尾,关键指令建议放在开头或结尾并显式复述。
结构化输出 用 response_mime_type 加 response_schema 约束,让模型直接吐合法 JSON,避免自己写正则去”抢救”markdown 代码块:
resp = client.models.generate_content(model="gemini-2.5-flash",contents="从下面这段合同中提取甲乙方、金额、生效日期:...",config=types.GenerateContentConfig(response_mime_type="application/json",response_schema={"type": "object","properties": {"party_a": {"type": "string"},"party_b": {"type": "string"},"amount": {"type": "number"},"effective_date": {"type": "string"},},"required": ["party_a", "party_b", "amount"],},),)
函数调用(Function Calling) 的流程是:你在请求里声明可用工具的 name/description/parameters,模型判断需要调用时返回一个 function_call 结构,你的代码真正执行这个函数,再把结果作为 function_response 回传,模型基于结果继续生成。关键点在于——API 只负责”决定调谁、传什么参”,执行和权限校验必须由你自己的代码完成,涉及写操作的工具一定要加人工确认或二次校验。
| 模型档位 | 典型定位 | 适用场景 |
|---|---|---|
| Gemini 3.1 Pro / 2.5 Pro | 旗舰,复杂推理与长文档 | 深度分析、代码生成、跨文档推理 |
| Gemini 2.5 Flash | 性价比主力 | 对话产品、内容审核、常规抽取 |
| Flash-Lite 一类轻量档 | 高并发低成本 | 分类、打标、路由判断 |
| 图像生成模型 | 文生图/图生图 | 素材生产、海报与配图 |
| 向量(Embedding)模型 | 文本向量化 | RAG 检索、语义聚类 |
三条实操经验:先用轻量模型把链路和评测集跑通,再逐步升级看效果增量是否值那个价;成本要用”单价 × 自己业务的实测 token 量”算,而不是看榜单;延迟敏感的场景重点看输出速度和首 token 时间,Pro 类模型在长输出任务上耗时差异很明显。
计费逻辑本身不复杂:
单次调用成本 = 输入 token 数 × 输入单价 + 输出 token 数 × 输出单价(命中缓存的部分按缓存单价计,通常明显低于常规输入价)
三个必须注意的细节:一是 Pro 类模型普遍采用 阶梯定价 ,单次请求 prompt 超过某个 token 阈值后单价跳档,长上下文场景要专门算这笔账;二是 输出 token 通常比输入贵 ,控制 max tokens 和回答长度对账单影响最直接;三是 缓存能省很多 ,固定的 system prompt、产品手册、长文档适合做 context caching,按 TTL 续期。
优化手段按性价比排序:精简 prompt 里的冗余示例 → 抽取/分类类任务下沉到轻量模型 → 稳定前缀做缓存 → 离线批处理走 Batch 通道 → 上线前用 token 计数接口预估单次消耗,避免上线后才发现成本模型算错。
除了网络和结算的门槛,更麻烦的是 多模型共存 :业务上往往要同时用 Gemini、文心、DeepSeek 等不同厂商的模型,各家 SDK 不同、鉴权方式不同、账单口径不同,代码里到处是 if-else 分支,想做个 A/B 或灰度切换成本极高。
这时候一个统一接入层就很有价值。词元所的做法是把模型服务供应方和消费方撮合到一起:你可以在上面横向对比不同模型的能力定位和调用价格,做选型与成本评估;确定后用统一 API 接入,把多套 SDK 收敛成一套调用方式;上线后再通过调用管理看清各模型的用量分布,为下一轮降本提供依据。对需要”同一套代码跑多家模型”的团队,这条路比逐个平台对接要省事得多。
| 现象 | 常见原因 | 处理方式 |
|---|---|---|
| 429 / RESOURCE_EXHAUSTED | 触发 RPM 或每日配额 | 指数退避重试,申请提额,或分流到其他模型 |
| 400 INVALID_ARGUMENT | 模型名写错、字段结构不符 | 核对模型 ID 与请求体 schema |
| 403 PERMISSION_DENIED | Key 无效、API 未启用、区域不支持 | 检查 Key 权限与项目 API 启用状态 |
| 503 / 500 | 服务端瞬时故障 | 幂等重试,设置超时与熔断 |
resp.text 为空 |
被安全策略拦截或达到 max tokens | 看 finish_reason 与 prompt_feedback,而非盲目重试 |
最后一条最值得强调:拿到空响应时先读 finish_reason,是安全拦截就调整输入或安全阈值配置,是长度截断就调大输出上限,两种情况的处理方式完全不同,盲目重试只会浪费配额。
如果你正在做技术选型或成本测算,建议先在大模型 API 服务平台上把候选模型的单价和能力定位拉齐对比,再用统一 API 接入做小流量灰度,用真实业务数据决定最终用哪家、用哪一档——这比凭榜单拍板要稳得多。