# 快速开始

> 一个 API Key, 三种 SDK, 接入 205+ 模型

来源：https://model.dflop.top/docs/quickstart

> **用任何 SDK 调任何模型, 无需修改代码**

本平台是多协议 AI 网关。你已经用熟的 OpenAI / Anthropic / Google Gemini SDK,
可以直接调用 205+ 个模型 —— 103 个文本模型覆盖 Claude / GPT / Gemini / Grok / DeepSeek /
Kimi / 千问 / MiniMax / GLM 等 12 家厂商,另有图像 / 视频 / embedding 模型
(见 [图像 / 视频 / 音乐 API](./reference/media-apis.md))。

## 1. 获取 API Key

访问 [model.dflop.top](https://model.dflop.top) 注册并创建 API Key:

- 控制台路径: **Dashboard → API Keys → Create Key**
- 格式: `sk-gpushare-` + **64 位十六进制**(总长 76 字符)
- **注册即送 $0.30 体验额度**,足够跑通本页全部示例
- 充值: 主站 dflop.top/dashboard/billing(Stripe,最低 $1;与 model.dflop.top 同账号 SSO,余额共享)
- 所有 Key 共享同一账户余额;Key 级可设模型白名单(`allowed_models`)、有效期、启停 —— 用于权限隔离与审计,**不是预算隔离**
- 原始 Key 可在控制台 Key 详情页**随时重新查看**(服务端加密存储)

```bash
export PLATFORM_API_KEY=sk-gpushare-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

## 2. 选择你已经在用的 SDK

### 2.1 OpenAI SDK

```python
from openai import OpenAI

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

# 调用任意模型 —— 包括非 OpenAI 家
response = client.chat.completions.create(
    model="claude-sonnet-4-6",  # 用 OpenAI SDK 调 Claude
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)
```

完整 Python / TypeScript / curl 示例见 [OpenAI SDK 指南](./sdks/openai-sdk.md)。

### 2.2 Anthropic SDK

```python
from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.dflop.top",  # ⚠️ 不带 /v1
    api_key="sk-gpushare-xxx",
)

# 调用绝大多数模型 (例外见兼容矩阵) —— 包括非 Anthropic 家
message = client.messages.create(
    model="gpt-5.5",                    # 用 Anthropic SDK 调 GPT
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
print(message.content[0].text)
```

完整示例见 [Anthropic SDK 指南](./sdks/anthropic-sdk.md)。

### 2.3 Google Gemini SDK

```python
from google import genai

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

# 调用绝大多数模型 (例外见兼容矩阵) —— 包括非 Gemini 家
response = client.models.generate_content(
    model="glm-5.1",                    # 用 Gemini SDK 调 GLM
    contents="Hello",
)
print(response.text)
```

SDK 默认发送的 `x-goog-api-key` header 直接被网关识别,无需任何鉴权改造。
完整示例见 [Gemini SDK 指南](./sdks/gemini-sdk.md)。

## 3. 它是怎么工作的?

本平台内部有一套协议自适配引擎:

```
你的 SDK (OpenAI / Anthropic / Gemini)
        ↓
本网关: 自动翻译协议
        ├─ T1: OpenAI Chat   → Anthropic Messages
        ├─ T2: OpenAI Chat   → Gemini Native
        ├─ T3: Anthropic     → OpenAI Chat
        ├─ T4: Gemini Native → OpenAI Chat
        └─ T6: Gemini Native → Anthropic Messages
        ↓
上游 model (Claude / GPT / Gemini / GLM / DeepSeek / Grok / ...)
        ↓
响应翻译回你 SDK 期望的 shape
        ↓
你的代码无感知
```

绝大多数「SDK 协议 × 模型」组合要么原生直通(byte-faithful),要么自动走协议翻译,
仅少数组合暂未支持。你**不需要**了解走哪条 —— 网关自动选最优路径,
翻译路径会在响应的 `X-Protocol-Translation` header 中标注。
完整矩阵: [兼容矩阵](./reference/compatibility-matrix.md)。

## 4. 客户端集成

本平台在主流 AI Coding 客户端里可作为 Custom API Provider 接入:

- [Claude Code](./integrations/claude-code.md) —— 把 `ANTHROPIC_BASE_URL` 指向本网关
- [Cursor](./integrations/cursor.md) / [Cline](./integrations/cline.md) —— Custom OpenAI 接口
- [Continue](./integrations/continue.md) / [Open WebUI](./integrations/open-webui.md)

## 5. 模型推荐

### 按厂商

| 厂商 | 模型 ID | 推荐 SDK |
|---|---|---|
| Anthropic | `claude-opus-4-8`, `claude-opus-4-7`, `claude-opus-4-6`, `claude-sonnet-4-6`, `claude-haiku-4-5-20251001` | Anthropic SDK |
| OpenAI | `gpt-5.5` | OpenAI SDK |
| Google | `gemini-2.5-flash`, `gemini-2.5-pro`, `gemini-3-flash-preview`, `gemini-3-pro-preview` | Gemini SDK |
| xAI | `grok-4`, `grok-4.1`, `grok-4.2`, `grok-4-fast-reasoning`, `grok-4-fast-non-reasoning` | 任意 |
| 智谱 | `glm-4.7`, `glm-5`, `glm-5-turbo`, `glm-5.1` | 任意 |
| DeepSeek | `deepseek-v3.2`, `deepseek-v4-flash`, `deepseek-v4-pro` | 任意 |
| Moonshot | `kimi-k2.5`, `kimi-k2.6` | 任意 |
| MiniMax | `MiniMax-M2.5`, `MiniMax-M2.7` | 任意 |

完整模型列表(含定价与上下文)见 [模型列表](./reference/models.md);
图像 / 视频模型见 [图像 / 视频 API](./reference/media-apis.md)。

### 按用途

| 用途 | 推荐 model | 理由 |
|---|---|---|
| 复杂推理 / agent | `claude-opus-4-8`, `claude-opus-4-7` | 最强推理,1M 上下文 + vision + thinking |
| 日常 coding | `claude-sonnet-4-6`, `gpt-5.5` | 平衡价格性能 |
| 秒级响应 | `gemini-2.5-flash`, `grok-4-fast-non-reasoning` | 低延迟 |
| 国内合规 (中文场景) | `glm-5.1`, `deepseek-v3.2`, `hunyuan-2.0-instruct-20251111` | 国内厂家 |
| 长上下文 | `gemini-2.5-pro` (2M), `grok-4-fast-*` (2M), `kimi-k2.6` (256K) | 上下文窗口 |
| 极便宜批量 | `grok-4-fast-*` ($0.2/M), `deepseek-v3.2` ($0.27/M) | $0.2–$0.30/M 量级 |
| 多模态视觉 | `claude-*`, `gpt-5.x`, `gemini-*`, `grok-4`, `grok-4.x` | 支持 vision input |

> **限制**: Gemini 系列暂不支持 Anthropic Messages 端点 (Anthropic→Gemini 翻译在路线图中);
> GPT-5.x 暂不支持 Gemini Native 端点。调用未支持的组合会返回 503 `no_channel_available`。
> 其余组合全部可用,详见 [兼容矩阵](./reference/compatibility-matrix.md)。

## 6. 计费

- **预付费钱包**: 充值进**账户余额**(USD),所有 API Key 共享同一余额,按实际用量扣减。Key 本身不带独立预算池 —— 想做预算隔离请在业务侧分账(用量日志按 Key 区分,便于审计)
- **计费单位**: chat / embeddings 按 token;图像按张;视频按秒(按实际生成时长结算,失败全额退回)。详见 [图像 / 视频 / 音乐 API](./reference/media-apis.md)
- **cached 价格**: 上游返回 `cached_tokens` 时自动按该模型的「缓存输入」价计费,无需(也无法)显式开启。各模型缓存费率见 [模型广场](https://model.dflop.top/models),未标注缓存价的模型与普通 input 同价。`/v1/responses` 多轮会话建议带稳定的 `session_id` 请求头(网关会透传给上游做会话粘连),可显著提高缓存命中率
- **错误统一返回**: HTTP 4xx/5xx + 协议本家 JSON shape (OpenAI / Anthropic / Gemini 三种返回格式)
- **余额耗尽**: HTTP **402** + code `quota_exceeded`(OpenAI 格式;Anthropic 格式为 type `billing_error`,Gemini 格式为 status `RESOURCE_EXHAUSTED`)。余额耗尽时**所有 Key 同时失效,新建 Key 不能解决**,请到 dflop.top/dashboard/billing 充值

最常见的四个错误码:

| HTTP | code | 含义 |
|---|---|---|
| 402 | `quota_exceeded` | 账户余额耗尽,充值后恢复 |
| 429 | `rate_limit_exceeded` | 超出账户的每分钟请求数 / 并发上限(读 `Retry-After`),或上游限流透传 |
| 503 | `no_channel_available` | 该模型在当前协议下无可用通道 |
| 504 | `upstream_timeout` | 上游 180s 超时,建议 SDK timeout 设 ≥200s |

完整错误码、三协议错误体对照与重试建议见 [错误码](./reference/errors.md)。

### 随时查余额

```bash
curl https://api.dflop.top/v1/key/balance \
  -H "Authorization: Bearer $PLATFORM_API_KEY"
# {"object":"key.balance","remaining_usd":"12.3456","used_usd":"7.6544","total_usd":"20.0000","expires_at":null}
```

余额为 0 时它照样返回 200(其它计费端点会 402),不计费也不占速率额度 —— 拿它做监控,别等 402 才发现。

如果你用的是 New API / One API 中转平台,**渠道列表的「余额」列开箱即用**:平台已原样实现 OpenAI 官方计费端点 `GET /v1/dashboard/billing/subscription` 与 `/usage`。Cherry Studio、ChatBox 这类桌面客户端的「查看余额」多数也走同一对端点(以你的客户端版本为准)。配置步骤见 [New API / 中转平台接入](./integrations/new-api.md)。

## 7. 下一步

- 完整 API 参考: [API 参考](./reference/api-reference.md)
- 鉴权细节: [鉴权](./reference/authentication.md)
- 流式响应: [流式指南](./guides/streaming.md)
- 工具调用: [工具调用](./guides/tool-calling.md)
- 图像 / 视频 / Embedding: [媒体 API](./reference/media-apis.md)
- 知识库检索 (REST + MCP): [知识库 API & MCP](./reference/wiki-api.md)
- 反馈渠道: support@dflop.top