Gemini API入门指南：Google AI接入

Google 的 Gemini 是大模型赛道里不可忽视的一极。它原生支持多模态（文本、图像、音频、视频），上下文窗口最高可达百万级 token，并且 Google 提供了相当慷慨的免费额度，对开发者非常友好。不过 Gemini 的 API 经历过从 PaLM API 到 Gemini API 的演进，加上 Google AI Studio 和 Vertex AI 两套接入入口，新手很容易混淆。

本指南会帮你理清这些概念，从模型选型、获取密钥到写出第一段调用代码，完整走一遍 Gemini API 的接入流程。我们会同时演示原生 Google Gen AI SDK和通过 EnlyAI 用 OpenAI 兼容格式调用 Gemini两种方式，让你能根据项目情况灵活选择。

一、从 PaLM API 到 Gemini API

先理清历史脉络。Google 早期的对话模型叫 PaLM，对应的接口是 PaLM API，主要通过 google-generativeai 这个包调用。2023 年底 Google 发布 Gemini 系列后，PaLM API 逐步被 Gemini API 取代，PaLM 2 模型也进入维护阶段，不再获得能力更新。

现在的标准做法是使用 Gemini API，官方推荐通过新的 google-genai SDK（即 Google Gen AI SDK）接入。如果你项目里还在用老的 google-generativeai 包调用 PaLM，建议尽早迁移到 Gemini，否则无法用到最新的多模态和长上下文能力。

一句话总结：PaLM API 是过去式，Gemini API 是现在和未来。新项目直接上 Gemini API 即可。

二、Gemini 模型能力与选型

Gemini 系列同样采用多档模型策略，覆盖从极致性能到极致速度的不同需求。理解每个模型的定位，是平衡效果与成本的关键。

模型	定位	上下文窗口	典型场景
Gemini 2.0 Flash	快速多模态	1M	实时应用、高并发
Gemini 2.5 Pro	能力旗舰	1M+	复杂推理、长文档
Gemini 1.5 Pro	长上下文	2M	超长文档、视频理解
Gemini 1.5 Flash	轻量高效	1M	高频调用、摘要

Gemini 的几个突出能力：

• 原生多模态：可以直接传入图片、音频、视频文件，模型理解多模态内容，不需要额外接 OCR 或语音转文字。
• 超长上下文：Gemini 1.5 Pro 支持 200 万 token，能处理整部小说或数小时视频，是目前上下文最长的主流模型之一。
• 免费额度充足：Google AI Studio 提供可观的免费调用额度，适合开发调试和小流量应用。
• 与 Google 生态集成：可结合 Google Search、代码执行等工具，构建更强大的应用。

三、获取 Gemini API Key

Gemini API 的密钥可以通过两个渠道获取：

方式一：Google AI Studio。访问 Google AI Studio，登录 Google 账号后点击“Get API key”即可创建。这是最简单的途径，适合个人开发者和原型验证，有免费额度。

方式二：Vertex AI。企业级接入走 Google Cloud 的 Vertex AI，需要绑定 GCP 项目和计费账号，适合生产环境大规模调用，支持更高配额和 SLA 保障。

方式三：通过 EnlyAI 接入。如果你不想单独注册 Google 账号、配置 GCP，或者希望用一套密钥同时调用 Gemini、GPT、Claude，可以选择 EnlyAI 聚合平台。EnlyAI 兼容 OpenAI API 格式，把 base_url 指向 https://enlyai.com/v1 就能用熟悉的 OpenAI SDK 调用 Gemini，所有模型调用汇总在一份账单里。

四、原生 Google Gen AI SDK 调用

使用官方 SDK 调用 Gemini，需要安装 google-genai 包。这是 Google 推出的新一代统一 SDK，同时支持 Google AI Studio 和 Vertex AI 两种后端。

# 安装 Google Gen AI SDK
pip install google-genai

最基础的文本调用：

from google import genai
import os

client = genai.Client(api_key=os.environ.get("GEMINI_API_KEY"))

response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents="用三句话解释什么是向量数据库"
)

print(response.text)

带系统指令和对话历史的调用：

from google import genai

client = genai.Client(api_key="YOUR_GEMINI_API_KEY")

response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=[
        {"role": "user", "parts": [{"text": "Python 里列表和元组有什么区别？"}]},
        {"role": "model", "parts": [{"text": "列表可变，元组不可变。"}]},
        {"role": "user", "parts": [{"text": "那什么时候该用元组？"}]}
    ],
    config={
        "system_instruction": "你是一位耐心的编程导师",
        "temperature": 0.7,
        "max_output_tokens": 1024
    }
)

print(response.text)

对应的 cURL，注意 Gemini 的 REST 接口把模型名和操作放在 URL 路径里，密钥通过 query 参数或 header 传递：

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "system_instruction": {"parts": [{"text": "你是一位简洁的助手"}]},
    "contents": [{"role": "user", "parts": [{"text": "用三句话解释什么是向量数据库"}]}],
    "generationConfig": {"temperature": 0.7, "maxOutputTokens": 1024}
  }'

几个需要注意的点：

• 角色命名不同：Gemini 用 user 和 model，而不是 OpenAI 的 user 和 assistant。
• 内容结构嵌套：每条消息的文本要包在 parts 数组里的 text 字段中，多模态内容也放在 parts 里。
• 系统指令：通过 system_instruction 传递，不在 contents 数组里。
• 参数命名：用 max_output_tokens 而非 max_tokens，generationConfig 而非顶层参数。

五、通过 EnlyAI 用 OpenAI 兼容格式调用 Gemini

Gemini 原生 API 的请求结构与 OpenAI 差异较大，parts、model 角色这些细节会让迁移成本变高。EnlyAI 把 Gemini 接口转译成 OpenAI 兼容格式，你只需把 base_url 指向 https://enlyai.com/v1，就能用 OpenAI SDK 直接调用 Gemini，角色名、参数名都和调用 GPT 一致。

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-enlyai-key",
    base_url="https://enlyai.com/v1"
)

response = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[
        {"role": "system", "content": "你是一位简洁的助手"},
        {"role": "user", "content": "用三句话解释什么是向量数据库"}
    ]
)

print(response.choices[0].message.content)

对应的 cURL，格式与调用 GPT 完全一致：

curl https://enlyai.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-enlyai-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.0-flash",
    "messages": [
      {"role": "system", "content": "你是一位简洁的助手"},
      {"role": "user", "content": "用三句话解释什么是向量数据库"}
    ]
  }'

这种统一接入方式的核心价值：

• 一套代码调所有模型：GPT、Claude、Gemini 用同一套 OpenAI SDK，只改 model 字段。
• 统一密钥与账单：不用分别管理 Google、Anthropic、OpenAI 三套账号和付款。
• 故障可切换：某个模型服务波动时，改个 model 名就能临时切到其他模型。
• 零迁移成本：已有 OpenAI SDK 代码几乎不用改，只换 base_url。

六、多模态与流式输出

Gemini 的一大卖点是原生多模态。通过 EnlyAI 调用时，可以用 OpenAI 的多模态消息格式传入图片：

import base64

with open("chart.png", "rb") as f:
    img_b64 = base64.b64encode(f.read()).decode()

response = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "描述这张图表里的数据趋势"},
            {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{img_b64}"}}
        ]
    }]
)

print(response.choices[0].message.content)

流式输出与 OpenAI 完全一致，适合做实时聊天界面：

stream = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[{"role": "user", "content": "写一段 200 字的科幻故事开头"}],
    stream=True
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

七、成本控制与最佳实践

Gemini 按 token 计费，输入输出价格不同，长上下文还会按区间阶梯定价。控制成本的几个要点：

1. 善用 Flash 系列：Flash 模型速度快、价格低，绝大多数摘要、分类、抽取任务用 Flash 就够了，Pro 留给真正需要深度推理的场景。
2. 警惕长上下文成本：百万 token 上下文虽然强大，但输入越长费用越高。做长文档处理时优先用 RAG 检索相关片段，而不是整篇塞进去。
3. 设置 max_output_tokens：明确限制输出长度，避免冗长回复浪费 token。
4. 利用免费额度：Google AI Studio 的免费额度适合开发调试，正式上线再切到付费或 EnlyAI 聚合接入。
5. 监控用量：响应里的 usage 字段记录了 token 消耗，务必落库统计。

resp = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[{"role": "user", "content": "你好"}]
)

usage = resp.usage
print(f"输入 token: {usage.prompt_tokens}")
print(f"输出 token: {usage.completion_tokens}")
print(f"总计: {usage.total_tokens}")

八、常见问题排查

接入 Gemini API 时的高频问题：

• 403 区域不可用：Gemini API 在部分地区受限。通过 EnlyAI 接入可规避区域限制，统一从国内访问。
• 400 角色错误：原生 API 中角色必须是 user 或 model，不能用 assistant。用 EnlyAI 则统一用 assistant。
• 429 配额超限：免费额度有 RPM（每分钟请求数）限制，降低频率或升级套餐。
• SDK 版本混乱：确认用的是 google-genai（新）还是 google-generativeai（旧），两者 API 不兼容。
• 多模态文件过大：大文件建议先上传到 File API 拿到引用，再传给模型，避免 base64 内联超限。

掌握以上内容，你已经能独立完成 Gemini API 的接入。无论是用原生 Google Gen AI SDK 追求最新多模态特性，还是通过 EnlyAI 用 OpenAI 兼容格式统一管理多模型，都能根据项目需求灵活选择。Gemini 的超长上下文和原生多模态能力，配合统一接入的便利，能让你的 AI 应用开发事半功倍。