# Google Gemini SDK — 本平台

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

来源：https://zhonkemodel.dflop.top/docs/sdks/gemini-sdk

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

## 端点

| 项 | 值 |
|---|---|
| Base URL | `https://zhonkezhonkeapi.dflop.top` |
| 端点 | `/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 访问日志。

## 安装

```bash
pip install google-genai     # Python
npm install @google/genai    # TypeScript
```

> Google 在 2024-2025 把 SDK 从 `google-generativeai` 切到了新的 `google-genai`。本文档用新 SDK。

## Python

### 基础调用

```python
from google import genai

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

response = client.models.generate_content(
    model="gemini-2.5-pro",
    contents="Say hello in one word.",
)
print(response.text)
```

### 流式输出

```python
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:

```python
# 调 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 端点](./anthropic-sdk.md)。

### 多模态 (图像输入)

```python
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

```python
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

### 基础调用

```typescript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
  apiKey: process.env.PLATFORM_API_KEY,
  httpOptions: { baseUrl: "https://zhonkezhonkeapi.dflop.top" },
});

const response = await client.models.generateContent({
  model: "gemini-2.5-pro",
  contents: "Say hello in one word.",
});

console.log(response.text);
```

### 流式输出

```typescript
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 ?? "");
}
```

### 跨厂商调用

```typescript
// 调 GLM
await client.models.generateContent({
  model: "glm-4.7",
  contents: "Hello",
});

// 调 DeepSeek
await client.models.generateContent({
  model: "deepseek-v4-pro",
  contents: "Hello",
});
```

## curl

### 非流式

```bash
curl "https://zhonkezhonkeapi.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 方式更安全。

### 流式

```bash
curl "https://zhonkezhonkeapi.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)

```bash
curl "https://zhonkezhonkeapi.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,与 zhonkemodel.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-key` → `x-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.5`)、`claude-opus-4-6` 系、`hunyuan-*`、`doubao-*`、`grok-4.3` 等 —— 在本端点返回 503 `UNAVAILABLE` (`no_channel_available`),请改用 OpenAI Chat 或 Anthropic Messages 端点 (见 [API 参考](../reference/api-reference.md))
- **配额/余额耗尽** 返回 HTTP **402** + Gemini 风格错误对象: `{"error": {"code": 402, "message": "余额不足，请充值后重试。", "status": "RESOURCE_EXHAUSTED"}}`
- **超时** —— 上游总时长上限 180 秒 (流式同样受限,只是更早拿到首 token);客户端 SDK 的 timeout 建议设为 ≥ 200 秒

## 常见错误速查

| 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` | 上游 180 秒超时 | 缩短输入 / 改流式 / 重试 |

完整错误对照 (三协议形状): [错误码参考](../reference/errors.md)

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

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

| 厂商 | 模型 |
|---|---|
| Google | `gemini-3-flash`, `gemini-3.1-pro-low`, `gemini-3.1-flash-lite`, `gemini-3-flash-agent`, `gemini-3.5-flash-low`, `gemini-3.6-flash`, `gemini-3.7-flash`, `gemini-pro-agent` |
| 智谱 | `glm-4.7`, `glm-5-turbo`, `glm-5.1` |

> Claude 系列模型不支持本端点(无 Gemini→Anthropic 转换通道,返 503 `UNAVAILABLE`),调用 Claude 请改用 [Anthropic Messages 端点](./anthropic-sdk.md)。

完整矩阵: [兼容矩阵](../reference/compatibility-matrix.md) · 图像 / 视频独立端点: [媒体 API](../reference/media-apis.md)