Google Gemini SDK — 本平台
用 Google Gemini SDK 调用本网关 (Python / TypeScript / curl),并可跨厂商调用 GLM / Grok / DeepSeek 等模型
适用场景: 已经在用 Google
genaiSDK 的项目可直接切换 base URL,代码零改动。 也可以用 Gemini SDK 调用部分非 Gemini 模型 (GLM / Grok / DeepSeek / Kimi 等,完整范围见下方「支持的模型」一节)。
端点#
| 项 | 值 |
|---|---|
| Base URL | https://qd.zsopc.com |
| 端点 | /v1beta/models/{model}:generateContent (兼容 Gemini Native API) |
| 流式端点 | /v1beta/models/{model}:streamGenerateContent |
| 鉴权 | 四种位置按序识别: x-api-key → x-goog-api-key → ?key= → Authorization: Bearer。google-genai SDK 默认发 x-goog-api-key header,零改造直接可用 |
| 协议 | Google Generative AI Native (HTTP / SSE 流式) |
推荐用 header 方式 (
x-goog-api-key或x-api-key) 而非?key=query —— 避免 API Key 进入 URL 访问日志。
安装#
pip install google-genai # Python
npm install @google/genai # TypeScript
Google 在 2024-2025 把 SDK 从
google-generativeai切到了新的google-genai。本文档用新 SDK。
示例里写了
api_version: v1beta,与 Google 文档一致。不写也可以:新版 SDK(如 google-genai / @google/genai 3.3)默认请求/v1/...,本平台/v1和/v1beta两套路径都接(生成、流式、count_tokens、模型列表)。只能填 base URL 的第三方工具也因此可用。
Python#
基础调用#
from google import genai
client = genai.Client(
api_key="sk-gpushare-xxx",
http_options={"base_url": "https://qd.zsopc.com", "api_version": "v1beta"},
)
response = client.models.generate_content(
model="gemini-2.5-pro",
contents="Say hello in one word.",
)
print(response.text)
流式输出#
stream = client.models.generate_content_stream(
model="gemini-2.5-pro",
contents="Stream a haiku about latency",
)
for chunk in stream:
print(chunk.text, end="", flush=True)
跨厂商调用 (重点)#
Gemini SDK 可以调用 Gemini Native 端点支持的跨厂商模型 —— 不只是 Gemini:
# 调 GLM
response = client.models.generate_content(
model="glm-5.1",
contents="Hello",
)
# 调 Grok
response = client.models.generate_content(
model="grok-4-fast-reasoning",
contents="Hello",
)
# 调 DeepSeek
response = client.models.generate_content(
model="deepseek-v3.2",
contents="Hello",
)
# 调 Kimi
response = client.models.generate_content(
model="kimi-k2.5",
contents="Hello",
)
只有「支持的模型」表中列出的模型可从本端点到达,表外模型返回 503
UNAVAILABLE。 Claude 系列虽在通道声明内,但 Gemini → Anthropic 的协议转换在上游通道存在已知缺陷,可能返回 500;调 Claude 建议直接用 Anthropic SDK / Messages 端点。
多模态 (图像输入)#
from google.genai import types
with open("photo.jpg", "rb") as f:
image_bytes = f.read()
response = client.models.generate_content(
model="gemini-2.5-pro",
contents=[
types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg"),
"Describe this image",
],
)
print(response.text)
System Instruction#
response = client.models.generate_content(
model="gemini-3-pro-preview",
config=types.GenerateContentConfig(
system_instruction="You are a terse expert. Answer in one sentence.",
),
contents="Why is the sky blue?",
)
print(response.text)
TypeScript#
基础调用#
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({
apiKey: process.env.PLATFORM_API_KEY,
httpOptions: { baseUrl: "https://qd.zsopc.com", apiVersion: "v1beta" },
});
const response = await client.models.generateContent({
model: "gemini-2.5-pro",
contents: "Say hello in one word.",
});
console.log(response.text);
流式输出#
const stream = await client.models.generateContentStream({
model: "gemini-2.5-pro",
contents: "Stream a haiku",
});
for await (const chunk of stream) {
process.stdout.write(chunk.text ?? "");
}
跨厂商调用#
// 调 GLM
await client.models.generateContent({
model: "glm-4.7",
contents: "Hello",
});
// 调 DeepSeek
await client.models.generateContent({
model: "deepseek-v4.1-flash",
contents: "Hello",
});
curl#
非流式#
curl "https://qd.zsopc.com/v1beta/models/gemini-2.5-pro:generateContent" \
-H "x-goog-api-key: $PLATFORM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{"parts": [{"text": "Say hello in one word."}]}
]
}'
?key=$PLATFORM_API_KEYquery 方式同样可用,但 key 会进 URL 日志,header 方式更安全。
流式#
curl "https://qd.zsopc.com/v1beta/models/gemini-2.5-pro:streamGenerateContent" \
-H "x-goog-api-key: $PLATFORM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{"parts": [{"text": "Stream a haiku"}]}
]
}' \
--no-buffer
跨厂商 (curl 调 GLM)#
curl "https://qd.zsopc.com/v1beta/models/glm-5.1:generateContent" \
-H "x-goog-api-key: $PLATFORM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{"parts": [{"text": "Hello"}]}
]
}'
计费与余额#
- 所有
sk-gpushare-*API Key 共享同一个账户余额(单位是积分),按实际 token 用量结算。Key 本身没有独立预算池 —— Key 级只有模型白名单 (allowed_models)、过期时间、启用/停用等权限控制。 - 注册即送 120 积分体验额度,足够跑通本页全部示例。到 充值页 充值 (¥1 = 60 积分)。
- 余额耗尽时所有 Key 同时失效 (HTTP 402 +
status: "RESOURCE_EXHAUSTED"),新建 Key 不能解决额度问题;充值后立即恢复。
注意事项#
- URL 模型占位
{model}—— SDK 自动从model参数填,curl 直调时手动替换路径 :generateContentvs:streamGenerateContent—— SDK 根据generate_contentvsgenerate_content_stream自动切换- Key 鉴权 —— 网关按
x-api-key→x-goog-api-key→?key=→Authorization: Bearer四个位置回退识别;google-genai SDK 默认发x-goog-api-keyheader,无需任何改造 - 流式 wire 格式 —— SDK 的流式请求带
?alt=sse,网关把这个参数(只有它)转给上游,返回标准 SSE(data: {...}帧)。不带alt=sse的:streamGenerateContent照 Google 的约定返回 JSON 数组流 models.list()/models.get()—— 列出这把 Key 能调用的 Gemini 模型(GET /v1beta/models、GET /v1beta/models/{model}),余额为 0 时也能查count_tokens()—— 由网关按请求体估算(与扣费前的预估同一套算法),不是模型自己的分词结果;不收费,但和本路径的其他调用一样需要余额大于 0- 错误格式 统一返回 Gemini 风格:
{"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}}(code为数字 HTTP 状态码) - 模型范围:
- 只有下方「支持的模型」表内的模型可从 Gemini Native 端点到达
- 表外模型 —— 包括 GPT (
gpt-6-luna)、claude-opus-4-6系、hunyuan-*、doubao-*、grok-4.3等 —— 在本端点返回 503UNAVAILABLE(no_channel_available),请改用 OpenAI Chat 或 Anthropic Messages 端点 (见 API 参考)
- 配额/余额耗尽 返回 HTTP 402 + Gemini 风格错误对象:
{"error": {"code": 402, "message": "余额不足,请充值后重试。", "status": "RESOURCE_EXHAUSTED"}} - 超时 —— 网关没有 180 秒的总时长上限。非流式
generateContent一次上游调用最长 600 秒;超过 20 秒还没完成时,网关先回 HTTP 200,每 15 秒发一个空格保持连接,最后写入 JSON,所以这之后才出现的超时以 HTTP 200 + 错误对象返回。流式streamGenerateContent最长约 61 分钟,没有开流前的保活。如果客户端限制的是整个请求的总时长,非流式至少留 660 秒,详见流式响应
常见错误速查#
| HTTP | status | 含义 | 处置 |
|---|---|---|---|
| 400 | INVALID_ARGUMENT | 请求体非法,或模型不在该 Key 的 allowed_models 白名单 | 检查请求体 / Key 白名单 |
| 400 | NOT_FOUND | model id 不在平台目录 (message 形如 model `xxx` is not available) | 核对模型 id |
| 401 | UNAUTHENTICATED | Key 错误 / 已吊销 / 已过期 | 检查 Key (控制台 Key 详情页可随时重新查看) |
| 402 | RESOURCE_EXHAUSTED | 账户余额耗尽 | 充值 (见上方「计费与余额」) |
| 429 | RESOURCE_EXHAUSTED | 上游限流透传 (与 402 用 HTTP 状态码区分) | 退避重试 |
| 503 | UNAVAILABLE | 模型存在但 Gemini Native 协议下无可用通道 —— 调用表外模型时的真实表现 | 换模型,或改用 OpenAI Chat / Anthropic Messages 端点 |
| 504 | DEADLINE_EXCEEDED | 上游超时 | 改流式 / 重试。非流式请求 20 秒之后才出现的超时以 HTTP 200 + 同一个错误对象返回 |
完整错误对照 (三协议形状): 错误码参考
支持的模型 (Gemini Native 端点)#
下表是 Gemini Native 端点当前支持的全部模型 —— 不是平台全目录 (平台 124+ 模型大多走 OpenAI Chat / Anthropic Messages 端点)。表外模型在本端点一律返回 503 UNAVAILABLE:
| 厂商 | 模型 |
|---|---|
gemini-3-flash, gemini-3.1-pro-low, gemini-3.1-flash-lite, gemini-3-flash-agent, gemini-3.8-flash, gemini-4-argon, gemini-pro-agent | |
| Google(1020 线路) | gemini-3.1-pro-preview-1020 |
| Google(nx 线路) | gemini-3.8-flash-nx, gemini-4-argon-nx |
| 智谱 | glm-4.7, glm-5-turbo, glm-5.1 |
Claude 系列模型不支持本端点(无 Gemini→Anthropic 转换通道,返 503
UNAVAILABLE),调用 Claude 请改用 Anthropic Messages 端点。