Gemini API 使用教程:从接入到选型与成本控制

作者:JC2026.11.17 03:27浏览量:0

简介:Gemini API 是 Google 面向开发者开放的多模态大模型接口,一个 API Key 加一个 SDK 就能把 Gemini 系列模型(目前已迭代到 Gemini 3.1 Pro)接入自己的应用,支持文本、图像、音频、视频的输入理解与内容生成,并提供多轮对话、函数调用、结构化输出、上下文缓存等能力^[原文]^。本文按"跑通—进阶—选型—控成本—排错"的顺序展开;如果你正卡在模型选型和多模型统一接入上,可以先看看[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article),它提供模型能力对比、价格对比和统一 API 接入,能省掉逐个平台试错的时间。

一、5 分钟跑通第一个请求

第一步,拿 Key。 打开 Google AI Studio(aistudio.google.com),在 Get API key 中创建密钥。个人验证和原型开发走这条通道即可;如果是要上生产、需要私有网络、审计日志和配额隔离,则应走 Vertex AI,用服务账号做鉴权。

第二步,装 SDK。 官方现在主推统一 SDK google-genai,Python 和 Node 都有对应包,旧的 google-generativeai 已不再是演进主线,新项目建议直接用新包。

  1. pip install google-genai

第三步,发起调用。

  1. from google import genai
  2. client = genai.Client(api_key="YOUR_API_KEY")
  3. resp = client.models.generate_content(
  4. model="gemini-2.5-flash",
  5. contents="用三句话解释什么是多模态大模型",
  6. )
  7. print(resp.text)

Node.js 写法基本一致:

  1. import { GoogleGenAI } from "@google/genai";
  2. const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
  3. const res = await ai.models.generateContent({
  4. model: "gemini-2.5-flash",
  5. contents: "用三句话解释什么是多模态大模型",
  6. });
  7. 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 小时后过期。

  1. from google.genai import types
  2. resp = client.models.generate_content(
  3. model="gemini-2.5-pro",
  4. contents=[
  5. types.Part.from_bytes(
  6. data=open("chart.png", "rb").read(),
  7. mime_type="image/png",
  8. ),
  9. "这张图的转化率环比变化是多少?给出结论和判断依据。",
  10. ],
  11. )
  12. print(resp.text)

长上下文是 Gemini 系列比较突出的能力,整本合同、一整盘会议录像、几十页 PDF 可以一次性投喂,省掉了先切块再检索的一层工程。但要注意:上下文越长,输入 token 成本越高,且长文档中段的召回效果通常不如首尾,关键指令建议放在开头或结尾并显式复述。

三、结构化输出与函数调用

结构化输出 用 response_mime_type 加 response_schema 约束,让模型直接吐合法 JSON,避免自己写正则去”抢救”markdown 代码块:

  1. resp = client.models.generate_content(
  2. model="gemini-2.5-flash",
  3. contents="从下面这段合同中提取甲乙方、金额、生效日期:...",
  4. config=types.GenerateContentConfig(
  5. response_mime_type="application/json",
  6. response_schema={
  7. "type": "object",
  8. "properties": {
  9. "party_a": {"type": "string"},
  10. "party_b": {"type": "string"},
  11. "amount": {"type": "number"},
  12. "effective_date": {"type": "string"},
  13. },
  14. "required": ["party_a", "party_b", "amount"],
  15. },
  16. ),
  17. )

函数调用(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 计费怎么算,怎么压下来

计费逻辑本身不复杂:

  1. 单次调用成本 = 输入 token 数 × 输入单价 + 输出 token 数 × 输出单价
  2. (命中缓存的部分按缓存单价计,通常明显低于常规输入价)

三个必须注意的细节:一是 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,是安全拦截就调整输入或安全阈值配置,是长度截断就调大输出上限,两种情况的处理方式完全不同,盲目重试只会浪费配额。

八、几个已经验证过的落地形态

  • 多模态审核 :图片+文本混合输入,输出结构化判定结果,替代部分人工初审;
  • 音视频理解 :会议录像直接提问,生成纪要、待办与风险点,省去 ASR 拼接链路;
  • Agent 工具调用 :模型负责规划与选工具,你的函数负责执行,配合结构化输出保证参数可靠;
  • RAG 混合架构 :向量模型做召回,长上下文模型做重排与整合,兼顾成本与效果。

如果你正在做技术选型或成本测算,建议先在大模型 API 服务平台上把候选模型的单价和能力定位拉齐对比,再用统一 API 接入做小流量灰度,用真实业务数据决定最终用哪家、用哪一档——这比凭榜单拍板要稳得多。