# 从 OpenAI 直连迁移

> 用 OpenAI SDK 切到本平台 —— 你只需改 2 行代码,立刻可调 205+ 个模型

来源：https://model.dflop.top/docs/guides/migrating-from-openai

> 已经在用 OpenAI SDK?切到本平台只需改 2 行代码,然后立刻可以调 205+ 个模型 (不只是 GPT)。
>
> 还没有 `sk-gpushare-*` Key?在 [model.dflop.top/dashboard/keys](https://model.dflop.top/dashboard/keys) 创建,注册即送 $0.30 体验额度,足够跑通本页全部示例。

## 改动点 (Python)

```python
from openai import OpenAI

# 原 OpenAI 直连
client = OpenAI(
-    api_key="sk-...",
+    api_key="sk-gpushare-xxx",
+    base_url="https://api.dflop.top/v1",
)
```

就这两处。`client.chat.completions.create(...)` 之后的代码**一行都不动**。

## 改动点 (TypeScript)

```typescript
import OpenAI from "openai";

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

## 改动点 (curl)

```bash
- curl https://api.openai.com/v1/chat/completions \
+ curl https://api.dflop.top/v1/chat/completions \
-   -H "Authorization: Bearer sk-..." \
+   -H "Authorization: Bearer sk-gpushare-xxx" \
    -H "Content-Type: application/json" \
    -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"Hello"}]}'
```

## 拿到的新能力

切完 base URL,你的代码立刻能调用**不只是 GPT**:

```python
# 同一个 client, 同一份代码, 不同 model
client.chat.completions.create(model="gpt-5.5", ...)               # 还能调
client.chat.completions.create(model="claude-sonnet-4-6", ...)  # 新增!
client.chat.completions.create(model="gemini-2.5-pro", ...)        # 新增!
client.chat.completions.create(model="glm-5.1", ...)               # 新增!
client.chat.completions.create(model="grok-4-fast-reasoning", ...) # 新增!
```

模型 ID 完整列表见 [模型列表](../reference/models.md)。

## 价格透明

本平台公开**透明定价**(详见 [模型广场](https://model.dflop.top/models) 页面),GPT 系列与原厂同价 (截至 2026-06):

| Model | OpenAI 直连 ($/1M in/out) | 本平台 ($/1M in/out) |
|---|---|---|
| `gpt-5.5` | $5.00 / $30.00 | $5.00 / $30.00 |

每次调用账单完整记在 [model.dflop.top/dashboard/usage](https://model.dflop.top/dashboard/usage),跟原厂账单一致;Key 管理在 [model.dflop.top/dashboard/keys](https://model.dflop.top/dashboard/keys)。

计费是**预付费账户钱包**:所有 Key 共享同一账户余额,余额耗尽时所有 Key 同时失效 (HTTP 402)。充值入口在主站 dflop.top/dashboard/billing (Stripe,最低 $1,与 model.dflop.top 同账号共享余额)。

## 改完之后必看

### 1. tools 行为略有不同

- `function` 工具完全兼容,行为跟 OpenAI 直连一致
- `web_search` 工具支持 `gpt-5.5` 及部分 Claude / Gemini 型号 (完整清单见 [兼容矩阵](../reference/compatibility-matrix.md) 与 [模型列表](../reference/models.md) 的能力列),必须配合 `stream=true`
- `image_generation` 工具同上,必须 `stream=true`
- **混用注意**: 一旦 `tools` 里混入 `web_search` 或 `image_generation`,请求会走另一条翻译路径,此时多轮历史里 assistant 消息的 `tool_calls` 字段**不回放** (gateway 只保留 assistant 文本;`tool` 角色消息的 `tool_call_id` 仍透传)。纯 `function` 工具不受影响;重度多轮 function-call 场景建议不要混用内置工具
- 详见 [工具调用](./tool-calling.md)

### 2. 流式响应跟原 OpenAI 一致

`stream=true` + 同样的 SSE 协议。客户端解析代码不用改。详见 [流式响应](./streaming.md)。

### 3. 错误格式一致

本网关在 `/v1/chat/completions` 端点返回的错误**保持 OpenAI 协议格式**:
```json
{"error": {"message": "...", "type": "...", "code": "..."}}
```

### 4. OpenAI endpoint 支持情况

| 端点 | 状态 |
|---|---|
| `POST /v1/chat/completions` | ✅ 完整支持 |
| `POST /v1/completions` (legacy 补全) | ❌ 不支持 |
| `POST /v1/embeddings` | ❌ 平台已于 2026-07 下架 embedding SKU,当前无可用模型(调用返回 404 `model_not_found`) |
| `POST /v1/audio/transcriptions` (Whisper) | ❌ 不支持 |
| `POST /v1/audio/speech` (TTS) | ✅ 支持,模型 `voice-tts-pro`(按字符计费,返回永久 URL 而非音频字节流 —— 与 OpenAI 的响应形状不同);另支持声音克隆 `POST /v1/audio/voices`。详见 [图像 / 视频 / 音乐 API](../reference/media-apis.md#post-v1audiospeech) |
| `POST /v1/images/generations` | ✅ 支持,模型用平台自己的 id:`gpt-image-2` / `doubao-seedream-*` / `nano-banana*` / `grok-imagine-*`(按张计费,返回 URL 24h 过期)。OpenAI 原厂 id(`dall-e-3` / `gpt-image-1`)不可用,请改用上面的 id。详见 [图像 / 视频 / 音乐 API](../reference/media-apis.md) |
| `POST /v1/images/edits` | ✅ 支持(JSON 与 multipart 双收,SDK 的 `client.images.edit(image=...)` 可直接用);计费与 `/generations` 同价。`mask`(局部重绘)会被原样转发给上游但**未验证生效**,不要依赖;当前语义是整图按 prompt 编辑。详见 [图改图 (Image-to-Image)](./image-editing.md) |
| `POST /v1/responses` | ✅ GPT-5.x / Claude / 多数第三方模型 —— 内置 web_search / image_generation;无 `previous_response_id` (gateway 无服务端会话状态),多轮请重发完整 `input`,gateway 会自动剥离历史里的 reasoning item |
| `GET /v1/models` | ✅ —— 返回平台目录 (注意: 该端点仅支持 `Authorization: Bearer` / `x-api-key` 两种 header 鉴权,不支持 `?key=`) |

如果你的应用强依赖 TTS / 语音转录,这部分需要继续走原厂。

另外本平台还提供 OpenAI 没有的端点: 异步视频生成 (按秒计费,见 [图像 / 视频 / 音乐 API](../reference/media-apis.md)) 与知识库检索 REST + MCP (见 [知识库 API & MCP](../reference/wiki-api.md))。

## 完整 diff 示例

### 原 OpenAI 直连

```python
import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

resp = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Write a haiku"}],
)
print(resp.choices[0].message.content)
```

### 本平台

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PLATFORM_API_KEY"],
    base_url="https://api.dflop.top/v1",
)

# 同样调 GPT
resp = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Write a haiku"}],
)

# 也能调 Claude
resp_claude = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Write a haiku"}],
)
```

## 常见问题

### Q: 我应该删 `OPENAI_API_KEY` 环境变量吗?

不必。建议平行保留:

```bash
export OPENAI_API_KEY=sk-...           # 原 OpenAI 直连
export PLATFORM_API_KEY=sk-gpushare-...
```

代码里显式指定用哪把:

```python
# 关键时刻 fallback 回原厂
client = OpenAI(
    api_key=os.environ.get("PLATFORM_API_KEY") or os.environ["OPENAI_API_KEY"],
    base_url=os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1"),
)
```

### Q: 速率限制跟原 OpenAI 一样吗?

不一样。本平台不强制 QPS 上限 (偶发 429 为上游限流透传),计费是**预付费账户钱包**: 所有 Key 共享同一账户余额,余额耗尽时所有 Key 同时返回 HTTP 402 (type `insufficient_quota`,code `quota_exceeded`)——新建 Key 不会带来新额度,充值才会 (dflop.top/dashboard/billing)。详见 [鉴权](../reference/authentication.md) 与 [错误码](../reference/errors.md)。

### Q: 重试逻辑要改吗?

不用。OpenAI SDK 内置的指数退避对本平台同样有效。状态码语义跨服务保持一致 ([错误码](../reference/errors.md))。

### Q: Function tools 的 tool_call_id 跨次会变吗?

纯 `function` 工具路径下,本网关透传上游 ID,不重写,你的多轮工具回填代码不需改。但若同一请求混入了 `web_search` / `image_generation` 内置工具,历史中的 assistant `tool_calls` 不回放,见上文 [tools 行为略有不同](#1-tools-行为略有不同)。

## 下一步

- 选用什么模型最划算? 见 [模型列表 §按用途速选](../reference/models.md#按用途速选)
- 用 Anthropic SDK 还是 OpenAI SDK 调 Claude? 个人偏好。两个都跑通,选你熟的
- 客户端集成见 [Cursor](../integrations/cursor.md) / [Cline](../integrations/cline.md) / [Continue](../integrations/continue.md)