# New API / 中转平台接入

> 把本平台作为上游渠道接进 New API / One API,以及第三方客户端「查看余额」为什么开箱即用

来源：https://zhonkemodel.dflop.top/docs/integrations/new-api

> [New API](https://github.com/Calcium-Ion/new-api) / [One API](https://github.com/songquanpeng/one-api) 是常见的 OpenAI 兼容中转 / 分发平台。本平台可以直接作为它们的**上游渠道**接入,渠道列表里的「余额」列也能正常显示。

## 添加渠道

New API 后台 → **渠道** → **添加新的渠道**:

| 配置项 | 值 |
|---|---|
| 类型 | `OpenAI` |
| 名称 | 随意,例如 `GPUShare` |
| 代理 / Base URL | `https://zhonkezhonkeapi.dflop.top` |
| 密钥 | 你的 `sk-gpushare-*` Key(`sk-gpushare-` + 64 位十六进制,共 76 字符;在 [控制台 Key 页](https://zhonkezhonkemodel.dflop.top/dashboard/keys) 创建,详情页可随时重新查看) |
| 模型 | 点「获取模型列表」自动拉取,或手填 |

> **Base URL 不要带 `/v1`**。New API 会自己在后面拼 `/v1/chat/completions`;填成 `https://zhonkezhonkeapi.dflop.top/v1` 会变成 `/v1/v1/chat/completions` 而 404。

保存后点「测试」,再点「**更新余额**」——余额列即显示当前可用额度。

## 余额是怎么来的

New API 这类平台查上游余额,用的是 **OpenAI 官方的计费端点**,本平台原样实现了它们:

```text
GET /v1/dashboard/billing/subscription    → hard_limit_usd(总额度)
GET /v1/dashboard/billing/usage           → total_usage(已用,单位是美分)
余额 = hard_limit_usd − total_usage / 100
```

所以**不需要任何额外配置**,填好 Key 就能显示。这两条也同时挂在不带 `/v1` 前缀的位置(有些客户端会把 `/v1` 剥掉再拼)。

> **自托管企业版**(私有部署的盒子)请用**带 `/v1`** 的那条 —— 盒上的 Nginx 只把 `/api/`、`/v1/`、`/v1beta/` 分流给后端,不带前缀的 `/dashboard/billing/*` 会落到前端而拿不到 JSON。公有云 `zhonkeapi.dflop.top` 两条都可用。

你也可以自己 curl 核对:

```bash
curl https://zhonkezhonkeapi.dflop.top/v1/key/balance \
  -H "Authorization: Bearer $PLATFORM_API_KEY"
```

```json
{
  "object": "key.balance",
  "remaining_usd": "12.3456",
  "used_usd": "7.6544",
  "total_usd": "20.0000",
  "expires_at": null
}
```

`remaining_usd` 与 New API 算出来的余额恒等。字段口径与两条计费端点的完整 schema 见 [API 参考](../reference/api-reference.md#get-v1-dashboard-billing)。

**几个值得知道的点**:

- **余额为 0 时这三条端点照常返回 200**(其它端点会 402),所以中转平台看到的是 `$0` 而不是一个报错的渠道。
- 查余额**不计费、不占速率额度、不更新 Key 的「最近使用时间」**,定时轮询是安全的。
- `used_usd` 只统计**这一把 Key**。同账户下的其它 Key、或企业老板池的消费都不会算进来,所以给每个中转平台单发一把 Key,各自的用量就是干净分开的。
- 余额本身由账户下**所有 Key 共享**(统一钱包,Key 没有独立预算池)。**没设消费上限**的 Key 见底 = 整个账户见底,新建 Key 不会带来新额度 —— 到主站 dflop.top/dashboard/billing 充值。
- 想给某把 Key 设**消费上限**,在 [Key 详情页](https://zhonkezhonkemodel.dflop.top/dashboard/keys) 配置。设了上限之后有两个变化:中转平台看到的余额变成这把 Key 的**剩余额度**(而不是整个账户余额);而且上限用尽时这把 Key 会 402 —— **哪怕账户里还有钱**,这时充值没用,要去调高上限或换一把 Key。
- 反过来说:**不给 Key 设上限,持有方就能通过余额端点看到整个账户(企业 Key 则是老板池)的余额**。把 Key 发给外部中转方时,建议顺手设一个上限。

## 模型列表

「获取模型列表」走 `GET /v1/models`,返回本平台目录的全部模型。**建议裁剪一下**:目录里包含图像 / 视频 / 音乐 / 语音等 SKU,它们走[独立端点](../reference/media-apis.md),在 chat 渠道上调用只会报错(400 或 503)。只保留对话模型即可。

如果这把 Key 配了 `allowed_models` 白名单,`/v1/models` 只返回白名单内的条目 —— 可以用它直接约束中转平台能转发哪些模型。

## 其他客户端

许多桌面客户端(Cherry Studio、ChatBox、NextChat、LobeChat 等)的「查看余额」也调同一对计费端点,配置方式同理:Base URL 填 `https://zhonkezhonkeapi.dflop.top`(若该客户端要求带版本前缀则填 `https://zhonkezhonkeapi.dflop.top/v1`,两种拼法我们都受理),Key 填 `sk-gpushare-*`。具体以你使用的客户端版本为准;客户端没有这个功能时,用上面的 curl 自查即可。

## 常见问题

| 现象 | 排查 |
|---|---|
| 余额显示 0 或不更新 | 先用上面的 curl 直接打一次:能返回数字 = 端点正常,问题在中转平台侧(多为 Base URL 带了 `/v1`)。真是 0 有**两种**可能:账户余额耗尽(充值)、或**这把 Key 的消费上限已用尽**(账户里可能还有钱,充值无效 —— 去 Key 详情页调高上限) |
| 401 `invalid_api_key` | Key 是否复制全(共 76 字符);或这把 Key 已被停用 / 过期 |
| 渠道测试通过但对话 402 | `/v1/models` 不校验余额,所以测试会过。402 = 账户余额耗尽(所有 Key 同时失效,新建 Key 无效),**或**这把 Key 的消费上限用尽(只影响这一把)|
| 404 且路径里有两个 `/v1` | Base URL 填成了 `https://zhonkezhonkeapi.dflop.top/v1`,去掉 `/v1` |
| 余额对但少了一点 | `used_usd` 有最多 60 秒缓存;`remaining_usd` 永远是实时值 |
| 智能体专用 Key 查余额被拒 | 智能体 Key 只能调 `/v1/chat/completions` 与 `/v1/agent/*`,不能查余额。用普通 Key |

## 其他集成

- [Open WebUI](./open-webui.md) — 自托管 ChatGPT-like 界面
- [Claude Code](./claude-code.md) — 命令行 AI 编程
- [Cursor](./cursor.md) — IDE 内置 AI
- [Cline (VS Code)](./cline.md) — agentic AI Coding
- [Continue.dev](./continue.md) — VS Code / JetBrains
- [FlopCode](./flopcode.md) — 本平台官方 fork