SupaStore

返回博客列表

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 中转调用教程(OpenAI SDK / 原生接口,2026)

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,国内开发者通常会遇到两个问题:

  1. 地区限制:Google AI Studio 和 Gemini API 不向中国大陆提供服务,申请 Gemini API Key 和调用接口都可能被拒绝;
  2. 网络:直连 Google 的接口容易超时,生产环境难以保证稳定。

通过中转站调用,Key 和接口地址都由中转站提供,代码和官方写法基本一致。


第一步:获取 API Key

  1. 登录 SupaStore,进入【令牌管理】→【添加令牌】;
  2. 勾选要使用的 Gemini 模型(例如 gemini-3.5-flash-lite),并设置额度上限;
  3. 复制 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+ 主流大模型》。