Google Gemini SDK — 本平台

用 Google Gemini SDK 调用本网关 (Python / TypeScript / curl),并可跨厂商调用 GLM / Grok / DeepSeek 等模型

适用场景: 已经在用 Google genai SDK 的项目可直接切换 base URL,代码零改动。 也可以用 Gemini SDK 调用部分非 Gemini 模型 (GLM / Grok / DeepSeek / Kimi 等,完整范围见下方「支持的模型」一节)。

端点#

Base URLhttps://api.dflop.top
端点/v1beta/models/{model}:generateContent (兼容 Gemini Native API)
流式端点/v1beta/models/{model}:streamGenerateContent
鉴权四种位置按序识别: x-api-keyx-goog-api-key?key=Authorization: Bearer。google-genai SDK 默认发 x-goog-api-key header,零改造直接可用
协议Google Generative AI Native (HTTP / SSE 流式)

推荐用 header 方式 (x-goog-api-keyx-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。

Python#

基础调用#

from google import genai

client = genai.Client(
    api_key="sk-gpushare-xxx",
    http_options={"base_url": "https://api.dflop.top"},
)

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://api.dflop.top" },
});

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-pro",
  contents: "Hello",
});

curl#

非流式#

curl "https://api.dflop.top/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_KEY query 方式同样可用,但 key 会进 URL 日志,header 方式更安全。

流式#

curl "https://api.dflop.top/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://api.dflop.top/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)、过期时间、启用/停用等权限控制。
  • 注册即送 $0.30 体验额度,足够跑通本页全部示例。充值入口在主站 dflop.top/dashboard/billing (Stripe,最低 $1,与 model.dflop.top 同账号 SSO 共享余额)。
  • 余额耗尽时所有 Key 同时失效 (HTTP 402 + status: "RESOURCE_EXHAUSTED"),新建 Key 不能解决额度问题;充值后立即恢复。

注意事项#

  • URL 模型占位 {model} —— SDK 自动从 model 参数填,curl 直调时手动替换路径
  • :generateContent vs :streamGenerateContent —— SDK 根据 generate_content vs generate_content_stream 自动切换
  • Key 鉴权 —— 网关按 x-api-keyx-goog-api-key?key=Authorization: Bearer 四个位置回退识别;google-genai SDK 默认发 x-goog-api-key header,无需任何改造
  • 流式 wire 格式 —— SDK 流式请求 URL 上的 ?alt=sse 参数不会透传到上游。网关流式响应统一标 content-type: text/event-stream,但实际 body 以承载通道上游的默认 wire 格式原样转发 (SSE 帧或 JSON-array)。若 SDK 流式解析失败而 curl 正常,先用 curl --no-buffer 直接观察 body 是哪种格式;非流式调用不受影响
  • 错误格式 统一返回 Gemini 风格: {"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}} (code 为数字 HTTP 状态码)
  • 模型范围:
    • 只有下方「支持的模型」表内的模型可从 Gemini Native 端点到达
    • 表外模型 —— 包括 GPT-5.x (gpt-5.4, gpt-5.5)、claude-opus-4-6 系、hunyuan-*doubao-*grok-4.3 等 —— 在本端点返回 503 UNAVAILABLE (no_channel_available),请改用 OpenAI Chat 或 Anthropic Messages 端点 (见 API 参考)
  • 配额/余额耗尽 返回 HTTP 402 + Gemini 风格错误对象: {"error": {"code": 402, "message": "quota exceeded: used X of Y USD", "status": "RESOURCE_EXHAUSTED"}}
  • 超时 —— 上游总时长上限 180 秒 (流式同样受限,只是更早拿到首 token);客户端 SDK 的 timeout 建议设为 ≥ 200 秒

常见错误速查#

HTTPstatus含义处置
400INVALID_ARGUMENT请求体非法,或模型不在该 Key 的 allowed_models 白名单检查请求体 / Key 白名单
400NOT_FOUNDmodel id 不在平台目录 (message 形如 model `xxx` is not available)核对模型 id
401UNAUTHENTICATEDKey 错误 / 已吊销 / 已过期检查 Key (控制台 Key 详情页可随时重新查看)
402RESOURCE_EXHAUSTED账户余额耗尽充值 (见上方「计费与余额」)
429RESOURCE_EXHAUSTED上游限流透传 (与 402 用 HTTP 状态码区分)退避重试
503UNAVAILABLE模型存在但 Gemini Native 协议下无可用通道 —— 调用表外模型时的真实表现换模型,或改用 OpenAI Chat / Anthropic Messages 端点
504DEADLINE_EXCEEDED上游 180 秒超时缩短输入 / 改流式 / 重试

完整错误对照 (三协议形状): 错误码参考

支持的模型 (Gemini Native 端点)#

下表是 Gemini Native 端点当前支持的全部模型 —— 不是平台全目录 (平台 80+ 模型大多走 OpenAI Chat / Anthropic Messages 端点)。表外模型在本端点一律返回 503 UNAVAILABLE:

厂商模型
Googlegemini-3-flash, gemini-3.1-pro-low, gemini-3.1-flash-lite, gemini-3-flash-agent, gemini-3.5-flash-low, gemini-pro-agent
智谱glm-4.7, glm-5-turbo, glm-5.1

Claude 系列模型不支持本端点(无 Gemini→Anthropic 转换通道,返 503 UNAVAILABLE),调用 Claude 请改用 Anthropic Messages 端点

完整矩阵: 兼容矩阵 · 图像 / 视频独立端点: 媒体 API