Gemini API 接入教程：AI Studio、API Key 与第一次调用（2026）

接入 Gemini API 的最短路径是：用 Google 账号打开 AI Studio，创建一个 API Key，装好 SDK，发出第一条 generateContent 请求。顺利的话，整个过程不超过二十分钟。真正容易卡住的地方不在“能不能调通”，而在选错入口、模型 ID 写错、免费额度与付费档混淆，以及把 Key 放进了不该放的位置。

本文按实际接入顺序走一遍：先分清 AI Studio 和 Vertex AI，再创建 Key、安装 SDK、发 curl 与 Python 请求，然后处理模型命名、系统指令、流式输出和安全设置，最后列出 400、403、429 的常见原因和 Key 安全清单。

说明：Google、Gemini 是 Google LLC 的商标。模型名称、免费额度与计费规则可能调整，本文以 2026 年 10 月的常见流程为例，具体以 Google 官方文档和站内模型价格页为准。

一、先分清 AI Studio 和 Vertex AI

Gemini API 有两个常用入口，账号体系和管理方式不同，选错会在权限或结算上返工。

对比项	Google AI Studio	Vertex AI
入口	浏览器控制台，面向开发者快速试用	Google Cloud 控制台，面向项目化使用
账号要求	Google 账号即可开始	Cloud 项目、结算账号与 IAM 权限
凭据	AI Studio 生成的 API Key	服务账号或受控 Key，配合 IAM
计费	免费档与付费档并存	按 Cloud 项目结算
区域与数据	以 AI Studio 条款为准	可选区域，受 Cloud 条款与项目配置约束
适合场景	原型、学习、小规模验证	生产系统、审计与权限要求高的团队

个人开发者和小团队通常先用 AI Studio 把流程跑通；涉及合同、数据区域、统一审计时，再评估 Vertex AI。两边的 Key、配额和账单不要混用，也不要拿 AI Studio 的 Key 去调用 Vertex AI 的接口。

二、创建第一个 API Key

1. 用 Google 账号登录 Google AI Studio。
2. 进入 API Key 管理页面，选择创建 API Key。
3. 选择一个 Google Cloud 项目；没有项目时按页面提示新建。
4. 复制生成的 Key，立即存入服务端环境变量或密码管理器。
5. 在 Playground 里发一条测试消息，确认 Key 和模型可用。
6. 给 Key 起一个能看出用途的名字，方便以后轮换和吊销。

AI Studio 提供免费档用于试用，可用模型、请求速率和额度会随账号与时期变化；在关联的 Cloud 项目开启结算后，可以进入付费档。不要把旧文章里的额度数字当成当前承诺，一切以控制台实际显示和官方说明为准。

创建 Key 后，先确认它属于哪个 Cloud 项目。额度通常按项目计算，测试与生产混用会让他人耗尽额度；需要更高配额时，在 Cloud 项目里开启结算并设置预算告警，再观察一周实际用量。

三、安装 SDK 并发出第一条请求

Python 环境建议使用 3.10 及以上版本，并在虚拟环境中安装官方 SDK。

python3 -m venv .venv
source .venv/bin/activate
pip install -U google-genai
export GEMINI_API_KEY="你的 Key"

先用 curl 排除 SDK 因素。模型 ID 用占位符代替，实际名称从模型列表或站内价格页获取。

curl "https://generativelanguage.googleapis.com/v1beta/models/<模型ID>:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "用一句话解释什么是 API 网关"}]}
    ],
    "generationConfig": {"maxOutputTokens": 256, "temperature": 0.7}
  }'

curl 返回 200 后，再换 Python SDK：

import os
from google import genai

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

resp = client.models.generate_content(
    model="<模型ID>",
    contents="用一句话解释什么是 API 网关",
)
print(resp.text)

model 要写完整的模型 ID，不要只写系列名。不同模型支持的输入类型和参数不同，写错会在 400 或 404 里体现。

四、模型命名、系统指令与生成参数

Gemini 的模型 ID 通常由系列和版本组成。最稳妥的做法是先查询当前账号可用的模型列表：

curl "https://generativelanguage.googleapis.com/v1beta/models" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

列表里没有的型号不要靠猜。选型时按任务分工：轻量任务用低延迟档，复杂推理和长文档再用高档位，具体档位与价格以模型价格页为准。

模型 ID 会随版本更新，旧 ID 可能被标记为弃用或直接下线。把模型名写进配置文件，不要散落在各处代码里，升级时只改一处，并用回归样本确认输出没有明显变化。

系统指令用于固定角色和输出规则，适合翻译、抽取、客服等场景：

resp = client.models.generate_content(
    model="<模型ID>",
    contents="把这句话翻译成英文：接入完成",
    config={"system_instruction": "你是一名技术文档译者，只输出译文。"},
)

常用生成参数包括 temperature、maxOutputTokens 和 topP。需要结构化结果时，可以让模型返回 JSON，并在代码里做解析与校验；不要假设模型一定遵守格式，失败重试和兜底逻辑要提前写好。

五、流式输出与安全设置

流式输出适合聊天界面和长回答。REST 接口在方法后加 :streamGenerateContent 并带上 alt=sse，Python SDK 用 generate_content_stream：

for chunk in client.models.generate_content_stream(
    model="<模型ID>",
    contents="分三点说明什么是限流",
):
    print(chunk.text, end="")

安全设置可以按类别调整拦截阈值，常见类别包括骚扰、仇恨、色情和危险内容。默认阈值适合多数业务；调低拦截会放宽内容范围，需要结合产品政策和当地法规评估。不要为了“通过测试”而整体关闭安全设置，尤其是面向公众的产品。

六、400、403、429 怎么排查

状态码	常见原因	处理方向
400	JSON 结构错误、参数不支持、模型 ID 与接口不匹配	对照请求体逐字段检查，先用最小请求
403	Key 无效或受限、API 未启用、项目或地区限制	换 Key 验证，检查项目权限与账号状态
404	模型 ID 拼错、接口版本或路径不对	查模型列表，确认 v1beta 与方法名
429	免费档额度用尽、每分钟请求过多、并发过高	指数退避重试，降并发，评估付费档
500/503	服务端临时故障	有限次重试，持续失败则降级或切换通道

429 不要立即重发。正确做法是退避加随机抖动，设置最大重试次数，并把失败请求记录到日志。免费档的速率限制通常更紧，压测和批量任务要单独安排。

七、Key 安全清单

• Key 只放在服务端环境变量或密钥管理服务中，不进前端、不进仓库、不进聊天记录。
• 生产、测试、开发各用一把 Key，按环境隔离额度与权限。
• 定期轮换，人员离职或项目结束时立即吊销。
• 在云端控制台限制 Key 可调用的 API，缩小泄露后的影响面。
• 打开用量告警，发现异常调用先停 Key 再排查。
• 不要在截图、录屏和工单里暴露完整 Key。

八、通过 OpenAI 兼容入口接入 Gemini

如果团队已经有 OpenAI SDK 和一整套调用代码，可以走中商起航 AI 网关的 OpenAI 兼容入口，Base URL 是 https://ai.zhongshangqihang.com/v1，只需改 base_url、api_key 和 model 三处：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

resp = client.chat.completions.create(
    model="<价格页上的 Gemini 模型名>",
    messages=[{"role": "user", "content": "只回复 OK"}],
)
print(resp.choices[0].message.content)

这种方式适合需要统一多模型账单、人民币结算和国内网络环境的团队。原生 Gemini 的参数和多模态字段不保证完全兼容，迁移前用真实请求逐项验证。注册入口在这里，模型与价格以模型价格页为准。

常见问题

Gemini API 有免费额度吗？

AI Studio 提供免费档，但可用模型、速率和额度会变，且数据条款与付费档可能不同。原型验证可以用免费档，正式业务建议按付费档重新评估配额和成本。

API Key 泄露了怎么办？

先在控制台吊销或轮换 Key，再查用量日志确认异常调用范围，最后排查泄露渠道。只删除代码里的 Key 不够，已经泄露的凭据要视为失效处理。

国内网络能直接调用 Gemini API 吗？

链路质量因地区和运营商而异，可能出现超时或连接失败。常见做法是把请求放在可稳定访问的服务器上，或使用支持 OpenAI 兼容接口的网关，具体限制以实际链路和官方说明为准。

为什么 curl 能通、Python SDK 报错？

先看 SDK 版本和依赖是否最新，再确认 model 写法、代理设置和环境变量是否一致。SDK 报 404 时，重点检查模型 ID 和接口路径，不要同时改多个变量。

Gemini API 能直接用 OpenAI SDK 调用吗？

Google 提供 OpenAI 兼容入口，国内网关也普遍提供兼容层，但参数支持范围不同。多模态、工具调用和结构化输出要用真实请求验证，不能假设完全等价。

下一步

先按本文流程把最小请求跑通，再接入业务日志、重试和用量监控。需要在一个后台管理 Gemini 与其他模型的调用量、人民币账单和 Key 权限，可以先注册中商起航 AI 网关，价格见模型价格。

相关阅读：

• Gemini API 常见报错排查：401、404、429、地区限制
• Gemini API 国内访问方案：直连、代理与配额
• Gemini 免费额度与限制：免费 API 够用吗？