# 从 Anthropic 直连迁移

> 用 Anthropic SDK 切到本平台 —— base URL 不带 /v1 一定要注意

来源：https://zhonkemodel.dflop.top/docs/guides/migrating-from-anthropic

> 已经在用 Anthropic SDK?切到本平台只需改 2 行代码,然后可以一并调 GPT / GLM / Grok / DeepSeek 等数十个非 Claude 模型(完整列表见 [模型列表](../reference/models.md))。

## ⚠️ 注意: base URL 不带 `/v1`

Anthropic SDK 默认会**自动在 base URL 后追加 `/v1/messages`**。所以:

```python
# ❌ 错: 会拼出 /v1/v1/messages
client = Anthropic(base_url="https://zhonkezhonkeapi.dflop.top/v1", ...)

# ✅ 对: SDK 会拼出 /v1/messages
client = Anthropic(base_url="https://zhonkezhonkeapi.dflop.top", ...)
```

记住一句话: **OpenAI SDK 带 `/v1`,Anthropic SDK 不带**。

## 改动点 (Python)

> 还没有 API Key?到 [zhonkemodel.dflop.top/dashboard/keys/new](https://zhonkezhonkemodel.dflop.top/dashboard/keys/new) 创建(详见[认证](../reference/authentication.md))。注册即送 $0.30 体验额度,足够跑通本页全部示例。

```python
from anthropic import Anthropic

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

就这两处。`client.messages.create(...)` 之后的代码**不变**。

## 改动点 (TypeScript)

```typescript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
-  apiKey: process.env.ANTHROPIC_API_KEY,
+  apiKey: process.env.PLATFORM_API_KEY,
+  baseURL: "https://zhonkezhonkeapi.dflop.top",
});
```

## 改动点 (curl)

```bash
- curl https://api.anthropic.com/v1/messages \
+ curl https://zhonkezhonkeapi.dflop.top/v1/messages \
-   -H "x-api-key: sk-ant-..." \
+   -H "x-api-key: sk-gpushare-xxx" \
    -H "anthropic-version: 2023-06-01" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "claude-sonnet-4-6",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Hello"}]
    }'
```

## 拿到的新能力

```python
# 用 Anthropic SDK 调 GPT
client.messages.create(model="gpt-5.5", max_tokens=1024, messages=[...])

# 调 GLM
client.messages.create(model="glm-5.1", max_tokens=1024, messages=[...])

# 调 Grok
client.messages.create(model="grok-4-fast-reasoning", max_tokens=1024, messages=[...])

# 调 DeepSeek
client.messages.create(model="deepseek-v3.2", max_tokens=1024, messages=[...])
```

> **Gemini 支持范围**: `gemini-3-flash` / `gemini-3.1-pro-low` 这 2 个 SKU(以及 `gemini-3-flash` 的历史别名 `gemini-2.5-flash-lite`)可以直接用 Anthropic SDK 调(上游原生支持 Anthropic 协议,无需翻译)。其余 `gemini-*` 暂不支持 Anthropic Messages 端点 (Anthropic → Gemini 翻译在路线图中),改用 OpenAI Chat 或 Gemini Native 端点。逐模型支持情况见[兼容矩阵](../reference/compatibility-matrix.md)。

## 价格

Anthropic 直连 vs 本平台:

| Model | Anthropic 直连 ($/1M in/out) | 本平台 ($/1M in/out) |
|---|---|---|
| claude-opus-4-6 | $15.00 / $75.00 | $15.00 / $75.00 |
| claude-sonnet-4-6 | $3.00 / $15.00 | $3.00 / $15.00 |

每次调用账单完整记在 [zhonkemodel.dflop.top/dashboard/usage](https://zhonkezhonkemodel.dflop.top/dashboard/usage),Key 管理在 [zhonkemodel.dflop.top/dashboard/keys](https://zhonkezhonkemodel.dflop.top/dashboard/keys)。

### 计费口径

- **统一钱包**: 计费走账户余额(美元钱包),所有 API Key 共享同一余额 —— Key 本身没有独立预算池(Key 级只有 `allowed_models` 白名单 / 过期时间 / 启用停用,用于权限隔离与审计)。
- **预扣 + 结算**: 每个请求先按 `max_tokens` 上界预估扣减,turn 结束后按真实 token 用量结算回补,只有实际用量入账。
- **余额耗尽 = HTTP 402**: 在 `/v1/messages` 端点返回 Anthropic 形状的错误体(注意这是 Anthropic 官方没有的错误场景,客户端需自行识别):

  ```json
  {"type": "error", "error": {"type": "billing_error", "message": "余额不足，请充值后重试。"}}
  ```

  余额耗尽时**所有 Key 同时失效**,新建 Key 不能解决额度问题;充值入口在主站 dflop.top/dashboard/billing(Stripe,最低 $1,与 zhonkemodel.dflop.top 同账号共享余额)。
- **cached 价格**: 上游 usage 返回 `cached_tokens` 时自动按 cached 价计费,无需(也无法)显式开启。流式下的 cache 折扣 caveat 见下方 [`cache_control` Q&A](#q-cache-control-还能用吗)。

## 改完之后必看

### 1. `anthropic-version` header

在本平台该 header **可以省略** —— gateway 转发上游时会自动注入 `anthropic-version: 2023-06-01`,入站不校验这个 header。带上也无害(会被忽略),所以 Anthropic SDK 自动设置的值不需要动,curl 直调时加不加都行。

### 2. Tools / Tool Use 兼容

完全一致:`input_schema` / `tool_use` / `tool_result` 命名都保留。详见 [工具调用](./tool-calling.md)。

### 3. 流式响应跟原 Anthropic 一致

`event: content_block_delta` / `event: message_stop` 等事件格式不变。详见 [流式响应](./streaming.md)。

### 4. 错误格式

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

### 5. `max_tokens` 建议始终带上

Anthropic SDK 客户端强制 `max_tokens`;curl 直调 Claude 模型时**上游**也要求该字段。本网关本身不校验它(缺失时计费预估回退到模型默认值),但为了行为可预期、计费预扣可控,建议始终显式带上。

### 6. Anthropic 专属功能兼容一览

| 功能 | 状态 |
|---|---|
| Messages API (`POST /v1/messages`) | ✅ 完整支持 |
| Streaming | ✅ 支持 |
| Tool Use | ✅ 支持 |
| Vision (image input) | ⚠️ 按模型而定,见[模型列表](../reference/models.md)的 `supports_vision` 标记 (如 `claude-opus-4-6` / `gpt-5.5` 支持,`grok-4-fast-reasoning` / `glm-5.1` 不支持) |
| Prompt caching (`cache_control`) | ⚠️ 翻译路径会丢字段;原生 Claude 通道支持 |
| Computer Use beta | ❌ 不支持 |
| Files API | ❌ 不支持 |
| Batch API | ❌ 不支持 |

### 7. 超时、自动重试与限流

- **gateway 内置 failover**: 上游 5xx / 超时 / 连接失败时,gateway 会自动在可用通道间重试,**单个请求最多尝试 3 次**;全部失败后返回的是最后一次的上游错误。所以同一请求偶尔会比直连 Anthropic 慢 —— 内部可能已经重试过。客户端自己的重试建议用指数退避,并把这层内置重试考虑进去,避免叠加放大。
- **没有可用通道**: 返回 HTTP 503,Anthropic 形状 `{"type": "error", "error": {"type": "overloaded_error", ...}}`。通道健康探测每 6 小时一轮,持续 503 应换 model 或反馈,等几分钟无效。
- **超时**: chat 端点上游总时长上限 **180 秒**(流式同样受 180s 总上限约束,流式只是更早拿到首 token)。建议 SDK timeout 设 **≥ 200s**。
- **限流**: 平台无硬性 QPS 限制;遇到 429 是上游限流透传,按一般退避策略处理即可。

## 完整 diff 示例

### 原 Anthropic 直连

```python
import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

msg = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Write a haiku"}],
)
print(msg.content[0].text)
```

### 本平台

```python
import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["PLATFORM_API_KEY"],
    base_url="https://zhonkezhonkeapi.dflop.top",
)

# 同样调 Claude
msg = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Write a haiku"}],
)

# 也能调 GPT (用 Anthropic SDK!)
msg_gpt = client.messages.create(
    model="gpt-5.5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Write a haiku"}],
)
```

## 常见问题

### Q: `ANTHROPIC_API_KEY` 环境变量还要留吗?

建议平行保留:

```bash
export ANTHROPIC_API_KEY=sk-ant-...       # 原 Anthropic 直连
export PLATFORM_API_KEY=sk-gpushare-...
```

### Q: Claude Code 客户端怎么切?

```bash
export ANTHROPIC_BASE_URL=https://zhonkezhonkeapi.dflop.top
export ANTHROPIC_AUTH_TOKEN=sk-gpushare-xxx
claude
```

详见 [Claude Code 集成](../integrations/claude-code.md)。

### Q: `cache_control` 还能用吗?

- 原生 Claude 通道**支持** (Anthropic 直传 Claude 模型时)
- 翻译路径**会丢字段**,并通过 `X-Protocol-Warning` 响应 header 告知,例如:

  ```
  X-Protocol-Warning: content[].cache_control dropped
  X-Protocol-Warning: system.cache_control dropped (OpenAI has no equivalent)
  ```

  该 header 的值是人类可读的句子,**不要做精确匹配** —— 判断 header 存在 + 子串包含 `cache_control` 即可。

如果 prompt caching 对你的成本很关键,坚持用 Claude 模型走 `/v1/messages` 端点即可保留完整支持。

> **流式 cache 折扣 caveat**: Anthropic 上游的流式 `message_delta` 事件不携带 `cache_read_input_tokens`,所以 `stream: true` 时 gateway 只能按可见计数结算,cache 命中折扣可能**少算**(即比应得的折扣付更多)。对 cache 成本敏感的高频场景,建议用 `stream: false`(可拿到准确的 cache 折扣)或自行核账。

### Q: 怎么知道走的是原生还是翻译路径?

看响应 header:
- `X-Protocol-Translation: <tag>` —— 翻译路径
- 无该 header —— 原生直通

也可以在 [兼容矩阵](../reference/compatibility-matrix.md) 直接查每个模型每个端点的路径。

## 下一步

- 选什么模型最划算? 见 [模型列表 §按用途速选](../reference/models.md#按用途速选)
- 想用 Anthropic SDK 调 Gemini? `gemini-3-flash` / `gemini-3.1-pro-low`(及历史别名 `gemini-2.5-flash-lite`)可以直接调;其余 `gemini-*` 暂不支持 (路线图中),改用 [Gemini SDK](../sdks/gemini-sdk.md) 或 [OpenAI SDK](../sdks/openai-sdk.md)
- 图像 / 视频 / Embedding 等非 chat 端点见 [图像 / 视频 / 音乐 API](../reference/media-apis.md)