# OpenAI SDK — 本平台

> 用 OpenAI SDK 调用本网关的 103 个文本模型 (Python / TypeScript / curl)

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

> 通用最广 —— OpenAI SDK 可调网关全部 103 个文本模型 (含 Claude / Gemini / GLM / Grok / ...)。图像 / 视频 / Embedding 模型走独立端点，见 [图像 / 视频 / 音乐 API](../reference/media-apis.md)。

## 端点

| 项 | 值 |
|---|---|
| Base URL | `https://zhonkezhonkeapi.dflop.top/v1` |
| 端点 | `/chat/completions` (兼容 OpenAI Chat Completions) |
| 鉴权 | `Authorization: Bearer sk-gpushare-xxx` (也接受 `x-api-key` header，详见 [鉴权](../reference/authentication.md)) |
| 协议 | OpenAI Chat Completions (HTTP / SSE 流式) |

## 获取 API Key 与计费

- **创建**: 在 zhonkemodel.dflop.top 控制台创建 API Key（控制台中显示为「子密钥」），格式 `sk-gpushare-` + 64 位十六进制。Key 创建后可随时回到 Key 详情页重新查看。
- **计费**: 按 token 从**账户余额**（美元钱包）扣费，所有 Key 共享同一余额；Key 本身没有独立预算池。注册即送 **$0.30 体验额度**，足够跑通本页全部示例。
- **充值**: 主站 dflop.top/dashboard/billing（Stripe，最低 $1，与 zhonkemodel.dflop.top 同账号 SSO 共享余额）。
- **用量**: 控制台可查每个 Key 的调用与花费明细。

## 安装

```bash
pip install openai          # Python
npm install openai          # TypeScript
```

## Python

### 基础调用

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://zhonkezhonkeapi.dflop.top/v1",
    api_key="sk-gpushare-xxx",
)

resp = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Say hello in one word."}],
)
print(resp.choices[0].message.content)
```

### 流式输出

```python
stream = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Stream a haiku about latency"}],
    stream=True,
)
for chunk in stream:
    if not chunk.choices:  # 流末尾必带一个 choices 为空、携带 usage 的 chunk，跳过
        continue
    print(chunk.choices[0].delta.content or "", end="", flush=True)
```

> 网关会强制注入 `stream_options.include_usage`，每条流以一个 `choices: []` + `usage` 的 chunk 收尾（计费依据）。Python 示例必须判空 `choices`，否则 `chunk.choices[0]` 在该 chunk 上会抛 `IndexError`（TypeScript 用 `?.` 链则天然安全）。

### 跨厂商调用 (重点)

OpenAI SDK 可以调用任意支持 OpenAI Chat 协议的模型 —— 不只是 GPT:

```python
# 调 Claude
resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Hello"}],
)

# 调 Gemini
resp = client.chat.completions.create(
    model="gemini-2.5-pro",
    messages=[{"role": "user", "content": "Hello"}],
)

# 调 GLM
resp = client.chat.completions.create(
    model="glm-5.1",
    messages=[{"role": "user", "content": "Hello"}],
)
```

### 图像生成 (WebSocket 流式通道)

`image_generation` 内置工具**仅 `gpt-5.5` 支持**（其他模型带该工具返回 400 `tool_not_supported`），且必须配合 `stream=True`:

```python
stream = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Draw an orange cat in pixel art"}],
    tools=[{"type": "image_generation"}],
    stream=True,
)

# 图像以 markdown 内联在 delta.content:
#   正常: ![](https://r2.dflop.top/...)    <- 图床 URL，长期可访问
#   降级: ![](data:image/png;base64,...)   <- 图床上传失败时的回退形态
for chunk in stream:
    if not chunk.choices:
        continue
    print(chunk.choices[0].delta.content or "", end="", flush=True)
```

> 客户端应同时处理 URL 与 base64 两种形态；多轮对话时**不要**把 base64 形态原样写回 `messages[]`（整张图会被当文本重新计 token，成本爆炸）。按张计费的独立图像端点 `/v1/images/generations`（Seedream / Grok Imagine 等）见 [图像 / 视频 / 音乐 API](../reference/media-apis.md)。

### 联网搜索

`web_search` 覆盖大部分文本模型（个别模型 / 通道不支持时返回 400 `tool_not_supported`，逐模型支持见 [兼容矩阵](../reference/compatibility-matrix.md)），同样必须 `stream=True`:

```python
stream = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "What did Anthropic ship this week?"}],
    tools=[{"type": "web_search"}],
    stream=True,
)
for chunk in stream:
    if not chunk.choices:
        continue
    print(chunk.choices[0].delta.content or "", end="", flush=True)
```

### Function Tools

兼容 OpenAI function calling 语义 —— GPT / GLM 等模型直接透传；Claude / Gemini 模型经协议转换层转换，标准 `tools` / `tool_choice` / `tool_calls` / `role: "tool"` 字段均有映射。走 HTTP 通道,**不**经过 WS V2,`stream:false` 也支持:

```python
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get the current weather in a city",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"},
            },
            "required": ["city"],
        },
    },
}]

resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Weather in Tokyo?"}],
    tools=tools,
)
print(resp.choices[0].message.tool_calls)
```

## TypeScript

### 基础调用

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.PLATFORM_API_KEY,
  baseURL: "https://zhonkezhonkeapi.dflop.top/v1",
});

const resp = await client.chat.completions.create({
  model: "gpt-5.5",
  messages: [{ role: "user", content: "Say hello in one word." }],
});

console.log(resp.choices[0].message.content);
```

### 流式输出

```typescript
const stream = await client.chat.completions.create({
  model: "claude-sonnet-4-6",
  messages: [{ role: "user", content: "Stream a haiku" }],
  stream: true,
});

for await (const chunk of stream) {
  // 流末尾的 usage chunk choices 为空，?. 链可安全跳过
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
```

### 跨厂商调用

```typescript
// 调 Claude
await client.chat.completions.create({
  model: "claude-opus-4-6",
  messages: [{ role: "user", content: "Hello" }],
});

// 调 Grok
await client.chat.completions.create({
  model: "grok-4-fast-reasoning",
  messages: [{ role: "user", content: "Hello" }],
});
```

## curl

### 非流式

```bash
curl https://zhonkezhonkeapi.dflop.top/v1/chat/completions \
  -H "Authorization: Bearer $PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {"role": "user", "content": "Say hello in one word."}
    ]
  }'
```

### 流式

```bash
curl https://zhonkezhonkeapi.dflop.top/v1/chat/completions \
  -H "Authorization: Bearer $PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Stream a haiku"}
    ]
  }' \
  --no-buffer
```

## 注意事项

- **`stream: false`** 仅支持纯文本 + function 工具。`web_search` / `image_generation` 必须 `stream: true`
- **流式结尾 usage chunk**: 网关强制注入 `stream_options.include_usage`，每条流以一个 `choices: []` + `usage` 的 chunk 收尾（计费依据）。遍历 `choices[0]` 前先判空
- **内置工具支持范围**: `image_generation` 仅 `gpt-5.5`；`web_search` 覆盖大部分文本模型但非全量。不支持的组合返回 400 `tool_not_supported`，逐模型支持见 [兼容矩阵](../reference/compatibility-matrix.md)
- **模型范围**: `/chat/completions` 只服务文本 (chat) 类模型；图像 / 视频 / Embedding SKU 走各自独立端点（见 [图像 / 视频 / 音乐 API](../reference/media-apis.md)），在 chat 端点上调用会返回 503 `no_channel_available`。不存在的 model id 返回 400 `model_not_found`（不是 404）。Key 若创建时限定了模型白名单 (`allowed_models`)，越界调用返回 400 `model_not_allowed`
- **错误格式** 统一返回 OpenAI 风格: `{"error": {"message": "...", "type": "...", "code": "..."}}`，完整错误码表见 [错误参考](../reference/errors.md)
- **余额耗尽** 返回 HTTP 402 + code `quota_exceeded`（type `insufficient_quota`）。余额是账户级的，所有 Key 共享 —— 402 时新建 Key 无效，去主站 dflop.top/dashboard/billing 充值
- **超时**: 单请求上游超时 180 秒，超时返回 504 `upstream_timeout`（流式同样受 180s 总上限约束）。建议把 SDK `timeout` 设为 ≥ 200s；长输出任务用 `stream: true` 边收边处理

## 完整模型列表

[模型列表](../reference/models.md) 或 [兼容矩阵](../reference/compatibility-matrix.md)。也可以直接用 SDK 的 `client.models.list()`（即 `GET /v1/models`，仅支持 `Authorization: Bearer` / `x-api-key` header 鉴权）。