# Google Gemini SDK

> Use the Google Gemini SDK against this gateway (Python / TypeScript / curl), including cross-vendor calls to GLM, Grok, DeepSeek and more

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

> When to use this: a project already on Google's `genai` SDK can switch base URL and keep its code unchanged.
> You can also use the Gemini SDK to call some non-Gemini models (GLM, Grok, DeepSeek, Kimi and others — full scope in "Supported models" below).

## Endpoint

| | Value |
|---|---|
| Base URL | `https://zhonkezhonkeapi.dflop.top` |
| Endpoint | `/v1beta/models/{model}:generateContent` (compatible with the Gemini Native API) |
| Streaming endpoint | `/v1beta/models/{model}:streamGenerateContent` |
| Auth | four positions tried in order: `x-api-key` → `x-goog-api-key` → `?key=` → `Authorization: Bearer`. The google-genai SDK sends `x-goog-api-key` by default, so it **works with no changes at all** |
| Protocol | Google Generative AI Native (HTTP / SSE streaming) |

> Prefer a header (`x-goog-api-key` or `x-api-key`) over the `?key=` query so your API key never lands in URL access logs.

## Install

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

> Google moved from `google-generativeai` to the newer `google-genai` across 2024–2025. This page uses the new SDK.

## Python

### Basic call

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

### Streaming

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

### Calling other vendors (the interesting part)

The Gemini SDK can reach the cross-vendor models that the Gemini Native endpoint supports — not just 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",
)
```

> Only the models listed in "Supported models" are reachable from this endpoint; anything else returns 503 `UNAVAILABLE`.
> Claude models are declared on the channel, but the Gemini → Anthropic conversion has a known upstream defect and may return 500 — call Claude through the [Anthropic SDK / Messages endpoint](./anthropic-sdk.md) instead.

### Multimodal (image input)

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

### Basic call

```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);
```

### Streaming

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

### Calling other vendors

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

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

## curl

### Non-streaming

```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` also works, but the key ends up in URL logs — a header is safer.

### Streaming

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

### Cross-vendor (calling GLM with curl)

```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"}]}
    ]
  }'
```

## Billing and balance

- Every `sk-gpushare-*` API key draws on the same **account balance** (a USD wallet), settled on actual token usage. A key has no budget pool of its own — per key you only get access controls: the `allowed_models` allowlist, an expiry, and enable/disable.
- Sign-up includes **$0.30 of trial credit**, enough for every example on this page. Top up at dflop.top/dashboard/billing (Stripe, $1 minimum, same SSO account and shared balance as zhonkemodel.dflop.top).
- When the balance runs out **every key fails at once** (HTTP 402 with `status: "RESOURCE_EXHAUSTED"`); creating a new key doesn't help, and topping up restores service immediately.

## Things to know

- **The `{model}` placeholder in the URL** is filled from the `model` argument by the SDK; replace it by hand when using raw curl
- **`:generateContent` vs `:streamGenerateContent`** — the SDK switches automatically based on `generate_content` vs `generate_content_stream`
- **Key auth** — the gateway falls back through `x-api-key` → `x-goog-api-key` → `?key=` → `Authorization: Bearer`. The google-genai SDK sends `x-goog-api-key` by default, so nothing needs changing
- **Streaming wire format** — the `?alt=sse` parameter the SDK puts on streaming URLs is **not forwarded upstream**. The gateway labels streaming responses `content-type: text/event-stream`, but the body is forwarded in whatever wire format the serving upstream channel uses by default (SSE frames or a JSON array). If SDK stream parsing fails while curl works, inspect the body with `curl --no-buffer` to see which format you're getting. Non-streaming calls are unaffected
- **Errors always come back Gemini-style**: `{"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}}` (where `code` is the numeric HTTP status)
- **Model scope**:
  - Only the models in "Supported models" below are reachable from the Gemini Native endpoint
  - Everything else — including GPT-5.x (`gpt-5.5`), the `claude-opus-4-6` line, `hunyuan-*`, `doubao-*`, `grok-4.3` and so on — returns 503 `UNAVAILABLE` (`no_channel_available`) here. Use the OpenAI Chat or Anthropic Messages endpoint instead (see the [API reference](../reference/api-reference.md))
- **Out of balance** returns HTTP **402** with a Gemini-style error object: `{"error": {"code": 402, "message": "Insufficient balance. Please top up and try again.", "status": "RESOURCE_EXHAUSTED"}}`
- **Timeouts** — the upstream total ceiling is 180 seconds (streaming is bound by it too, you just get the first token sooner); set your SDK timeout to ≥ 200 seconds

## Common errors at a glance

| HTTP | `status` | Meaning | What to do |
|---|---|---|---|
| 400 | `INVALID_ARGUMENT` | Malformed body, or the model isn't in this key's `allowed_models` allowlist | Check the body / the key's allowlist |
| 400 | `NOT_FOUND` | The model id isn't in the platform catalog (message like ``model `xxx` is not available``) | Verify the model id |
| 401 | `UNAUTHENTICATED` | Key wrong, revoked or expired | Check the key (re-revealable on its console detail page) |
| 402 | `RESOURCE_EXHAUSTED` | Account balance exhausted | Top up (see "Billing and balance" above) |
| 429 | `RESOURCE_EXHAUSTED` | Upstream rate limit passed through (distinguish from 402 by the HTTP status) | Back off and retry |
| 503 | `UNAVAILABLE` | The model exists but has no channel on the Gemini Native protocol — this is what calling an unlisted model actually looks like | Switch model, or use the OpenAI Chat / Anthropic Messages endpoint |
| 504 | `DEADLINE_EXCEEDED` | Upstream hit the 180-second ceiling | Shorten the input / switch to streaming / retry |

Full cross-protocol error comparison: [Error codes](../reference/errors.md)

## Supported models (Gemini Native endpoint)

This is the **complete set** reachable from the Gemini Native endpoint — not the whole catalog (most of the platform's 205+ models use the OpenAI Chat or Anthropic Messages endpoints). Anything not listed returns 503 `UNAVAILABLE` here:

| Vendor | Models |
|---|---|
| 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` |
| Zhipu | `glm-4.7`, `glm-5-turbo`, `glm-5.1` |

> Claude models aren't supported on this endpoint (there's no Gemini→Anthropic conversion channel, so you get 503 `UNAVAILABLE`) — call Claude through the [Anthropic Messages endpoint](./anthropic-sdk.md).

Full matrix: [compatibility matrix](../reference/compatibility-matrix.md) · standalone image/video endpoints: [Media APIs](../reference/media-apis.md)