Gemini API 接入：5 分钟跑通两种端点

接入 Gemini 时最先遇到的岔路口不是 Key，而是端点：一个 /v1/chat/completions，一个 /v1beta/models/{model}:generateContent。两条路都能调通 gemini-3.1-flash-lite-preview，但你能拿到的能力并不一样。这篇把两条路径的差别、各自的最小可运行代码、真实价格和常见报错一次讲完，照着做 5 分钟能跑出第一个响应。

两条端点到底差在哪#

OpenAI 兼容端点做的事情是「翻译」：它把你的 messages 数组翻译成 Gemini 的 contents，再把结果翻译回 OpenAI 的响应结构。翻译层带来兼容性，也带来损耗。原生端点没有翻译，你写什么，模型就收到什么。

一句话结论：工具链优先走兼容端点，要用 Gemini 独有能力时切原生。两套 Key 是同一个，随时可以并存。

第一步：把 Key 和端点定下来#

注册后在控制台创建一个 sk- 开头的令牌，然后记住两个地址：

• 兼容端点 base_url：https://api.zaimod.com/v1
• 原生端点：https://api.zaimod.com/v1beta/models/{model}:generateContent

详细的开户流程见 快速开始，这里直接进代码。

第二步：用兼容端点发第一条请求#

如果你已经在用 openai 这个包，只需要改两行：

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-zaimod-key",
    base_url="https://api.zaimod.com/v1",   # 只改这一行
)

resp = client.chat.completions.create(
    model="gemini-3.1-flash-lite-preview",
    messages=[{"role": "user", "content": "用三句话解释什么是向量检索"}],
)
print(resp.choices[0].message.content)
print(resp.usage)   # prompt_tokens / completion_tokens，对账用

不想装 SDK 就先 curl 验一下网络和 Key：

curl https://api.zaimod.com/v1/chat/completions \
  -H "Authorization: Bearer $ZAIMOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-lite-preview",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 256
  }'

返回 200 并且 usage 里有 token 数，说明链路是通的。这一步能排掉 80% 的「接不上」问题——绝大多数失败是 Key 复制带了空格，或者模型名拼错。

第三步：切到原生端点拿独有能力#

兼容端点的翻译层会吃掉一些字段，下面四件事只有原生端点做得干净。

系统提示与多轮历史#

Gemini 没有 system 角色，系统提示放在 systemInstruction，历史对话整体带在 contents 里，role 只有 user 和 model：

{
  "systemInstruction": {"parts": [{"text": "你是一个严谨的技术编辑，只输出结论和依据。"}]},
  "contents": [
    {"role": "user", "parts": [{"text": "润色这句话：接口很慢。"}]},
    {"role": "model", "parts": [{"text": "接口平均响应时间超过 2 秒。"}]},
    {"role": "user", "parts": [{"text": "再短一点"}]}
  ],
  "generationConfig": {"temperature": 0.2, "maxOutputTokens": 512}
}

多模态：parts 里混排文本和文件#

{
  "contents": [{
    "role": "user",
    "parts": [
      {"text": "这张截图里的报错是什么原因？"},
      {"inlineData": {"mimeType": "image/png", "data": "<base64>"}}
    ]
  }]
}

图片、音频、视频都走同一套 parts，URL 形式用 fileData。视频分析对分组有要求，Gemini 优质分组支持最完整，但该分组价格倍率是 ×1.5，长视频任务要先算账。

流式：必须带 alt=sse#

curl -N "https://api.zaimod.com/v1beta/models/gemini-3.1-pro-preview:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $ZAIMOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents": [{"parts": [{"text": "写一段 100 字的 product hunt 文案"}]}]}'

漏掉 alt=sse 会拿到一个 JSON 数组，前端按 SSE 解析就会一片空白——这是原生端点最高频的坑。

思考预算与 JSON 输出#

{
  "contents": [{"parts": [{"text": "从这段合同里抽取甲方、金额、签署日期"}]}],
  "generationConfig": {
    "responseMimeType": "application/json",
    "thinkingConfig": {"thinkingBudget": 2048}
  }
}

thinkingBudget 直接决定推理深度和成本，抽取类任务给 1024–2048 通常够，数学证明类才需要拉高。完整的字段说明在 Gemini 原生端点文档。

价格：先算清一篇文章的成本#

平台挂单价（美元 / 百万 tokens，输入 / 输出，default 分组）：

按「每天 2000 次调用、每次输入 1500 tokens、输出 500 tokens」估算，一天消耗 3M 输入 + 1M 输出：

• flash-lite：3 × 0.25 + 1 × 1.50 = $2.25/天，月成本约 $68
• 2.5-pro：3 × 1.80 + 1 × 15.30 = $20.70/天，月成本约 $621
• 3.1-pro：3 × 4.00 + 1 × 24.00 = $36.00/天，月成本约 $1080

同一个业务逻辑，选错模型是 30 倍的成本差。做法也简单：先用 flash-lite 跑通全链路，只把确实答不好的那部分请求路由到 pro。完整实时价见 价格页，别背这张表，价格会变。

4 个高频报错#

429 限流和余额不足的处理方式不一样，前者退避重试，后者充值才恢复，判定逻辑写在 计费与错误码 里。

该走哪条：一张决策表#

• 用 Cursor、Cline、Cherry Studio、LangChain：兼容端点，这些工具只认 OpenAI 协议
• 需要视频理解、thinkingBudget、responseMimeType：原生端点
• 多厂商混跑（GPT + Claude + Gemini 一个 key）：兼容端点做默认，原生做特例
• 已有大量 OpenAI 代码不想改：兼容端点，改 base_url 一行

兼容层的边界在哪，OpenAI 兼容协议详解 讲得比这里细。

结语#

Gemini 接入的难点从来不是鉴权，而是知道自己在哪一层。兼容端点给你迁移速度，原生端点给你能力上限。先用兼容端点把业务跑通，再用原生端点替换掉那些真正需要多模态和思考预算的调用点，是最省事的顺序。

注册后自带测试额度，两个端点都可以直接试；跑通之后按量计费，余额不过期。想先看成本再决定用哪个模型，从 价格页 挑两个候选做 A/B 就行。

延伸阅读#

• Gemini 原生端点：generateContent 完整用法
• 快速开始：5 分钟发出第一次请求
• API 中转站跑路前的 5 个信号