Gemini API 国内怎么调用?Gemini API 中转调用教程(OpenAI SDK / 原生接口,2026)
Gemini API 国内怎么调用?本文演示三种 Gemini API 国内调用方法:OpenAI SDK 兼容调用、Gemini 原生 generateContent 接口与 google-genai SDK 自定义 base_url,并讲清 Gemini API Key 怎么配置、x-goog-api-key 请求头、模型选择与常见报错排查。
SupaStore 开发者体验组 ·

Gemini API 国内调用最省事的方式,是通过兼容 Gemini 接口的中转站:一个 API Key,既可以用 OpenAI SDK 的写法调用 Gemini,也可以继续用 Gemini 原生的 generateContent 接口和 google-genai SDK,只需要把接口地址换掉。
本文分别演示这三种 Gemini API 调用方法,并讲清 Gemini API Key 的配置、请求头写法和常见报错。还在挑选服务商的话,可以先看《API中转站是什么?AI中转站选型避坑指南》。
为什么国内调用 Gemini API 需要中转
直接使用 Google 官方的 Gemini API,国内开发者通常会遇到两个问题:
- 地区限制:Google AI Studio 和 Gemini API 不向中国大陆提供服务,申请 Gemini API Key 和调用接口都可能被拒绝;
- 网络:直连 Google 的接口容易超时,生产环境难以保证稳定。
通过中转站调用,Key 和接口地址都由中转站提供,代码和官方写法基本一致。
第一步:获取 API Key
- 登录 SupaStore,进入【令牌管理】→【添加令牌】;
- 勾选要使用的 Gemini 模型(例如
gemini-3.5-flash-lite),并设置额度上限; - 复制
sk-开头的密钥。
可用的 Gemini 模型和实时价格以模型广场为准。以 2026-10-29 的默认分组价格为例,gemini-3.5-flash-lite 输入 $0.3、输出 $2.5(每百万 Token),适合低成本的批量处理。
方法一:用 OpenAI SDK 调用 Gemini(推荐)
如果项目已经在用 OpenAI SDK,这是改动最小的方法:只换 model,其他代码不变。
from openai import OpenAI
client = OpenAI(
base_url="https://api.supastore.cc/v1",
api_key="sk-your-supastore-api-key",
)
resp = client.chat.completions.create(
model="gemini-3.5-flash-lite",
messages=[{"role": "user", "content": "用一句话解释什么是多模态模型"}],
)
print(resp.choices[0].message.content)
这样一个客户端就能在 Gemini、Claude、GPT、DeepSeek 之间切换,OpenAI SDK 的完整用法见《OpenAI API 国内怎么调用?》。
方法二:Gemini 原生 generateContent 接口
已有代码使用 Gemini 原生 REST 接口时,把地址里的 generativelanguage.googleapis.com 换成中转站地址即可,路径格式不变:
curl "https://api.supastore.cc/v1beta/models/gemini-3.5-flash-lite:generateContent" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: sk-your-supastore-api-key" \
-d '{
"contents": [{"parts": [{"text": "用一句话解释什么是多模态模型"}]}]
}'
返回结果中的 candidates[0].content.parts[0].text 就是模型的回答。
鉴权方式和官方一致:Key 放在 x-goog-api-key 请求头里,也可以作为 URL 参数 ?key= 传入。推荐用请求头,避免 Key 出现在日志和浏览器历史里。
方法三:google-genai SDK 自定义 base_url
Google 官方的 Python SDK google-genai 也支持修改接口地址,通过 HttpOptions 的 base_url 指向中转站:
pip install -U google-genai
from google import genai
from google.genai import types
client = genai.Client(
api_key="sk-your-supastore-api-key",
http_options=types.HttpOptions(base_url="https://api.supastore.cc"),
)
resp = client.models.generate_content(
model="gemini-3.5-flash-lite",
contents="用一句话解释什么是多模态模型",
)
print(resp.text)
注意这里的 base_url 不带 /v1:SDK 会自己拼接 /v1beta/models/... 路径。这和 OpenAI SDK 的写法不同,是最容易填错的地方,各类工具的地址规则见《Base URL 是什么?API Base URL 怎么填》。
三种方法怎么选
| 方法 | 适合 | 接口地址 |
|---|---|---|
| OpenAI SDK | 新项目、需要切换多家模型 | https://api.supastore.cc/v1 |
| 原生 REST | 已有 Gemini REST 代码、其他语言直接发 HTTP | https://api.supastore.cc/v1beta/models/{模型}:generateContent |
| google-genai SDK | 已有 google-genai 代码,想保留 Gemini 特有写法 | https://api.supastore.cc |
没有历史包袱时,优先用 OpenAI SDK:一套代码可以调用所有模型,换模型只改一个字符串。
Gemini API 国内调用常见报错
| 现象 | 常见原因 | 处理方法 |
|---|---|---|
| 401 / API key not valid | 用了 Google 官方 Key,或密钥复制错误 | 改用中转站的 Key |
| 404 Not Found | google-genai 的 base_url 多写了 /v1,或 OpenAI SDK 的少写了 /v1 |
按上表分别填写 |
| 模型不存在 | 模型 ID 拼写错误,或 Key 未勾选该模型 | 在模型广场核对 ID,检查 Key 的可用模型 |
| 连接超时 | 地址仍指向 generativelanguage.googleapis.com |
检查代码和环境变量中的地址 |
| 429 Too Many Requests | 并发过高或额度用完 | 降低并发、加重试,或调高 Key 额度 |
更多错误码的含义见《Claude API 报错怎么办?》。
常见问题 (FAQ)
Q: 国内能申请 Gemini API Key 吗?
答: Google AI Studio 不向中国大陆提供服务,直接申请官方 Gemini API Key 通常会被拒绝。通过中转站可以拿到能调用 Gemini 的 Key,不需要 Google 账号。
Q: 用中转站调用 Gemini,原生接口和 OpenAI 兼容接口的结果一样吗?
答: 模型本身相同,回答质量一样。区别只在请求和响应的格式:原生接口用 contents 和 candidates,OpenAI 兼容接口用 messages 和 choices。
Q: google-genai SDK 的 base_url 为什么不带 /v1?
答: 因为 SDK 会自动在地址后面拼接 /v1beta/models/模型名:generateContent。如果 base_url 里再带 /v1,最终路径就会出错,返回 404。
Q: Gemini 能和 Claude、GPT 用同一个 Key 吗?
答: 可以。同一个 Key 在 OpenAI 兼容接口下切换 model 即可调用不同厂商的模型,统一接入的思路见《如何通过单 API Key 统一接入 40+ 主流大模型》。