# New API and relay platforms

> Adding this platform as an upstream channel in New API / One API, and why third-party clients show a balance out of the box

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

> [New API](https://github.com/Calcium-Ion/new-api) and [One API](https://github.com/songquanpeng/one-api) are widely used OpenAI-compatible relay/distribution platforms. This platform plugs straight in as an **upstream channel**, balance column included.

## Adding the channel

In the New API admin panel → **Channels** → **Add channel**:

| Setting | Value |
|---|---|
| Type | `OpenAI` |
| Name | Anything, e.g. `GPUShare` |
| Proxy / Base URL | `https://zhonkezhonkeapi.dflop.top` |
| Key | Your `sk-gpushare-*` key (`sk-gpushare-` plus 64 hex characters, 76 in total; create one on the [console key page](https://zhonkezhonkemodel.dflop.top/dashboard/keys), where you can re-read it any time) |
| Models | Hit "fetch model list" to pull them automatically, or type them in |

> **Leave `/v1` off the Base URL.** New API appends `/v1/chat/completions` itself, so `https://zhonkezhonkeapi.dflop.top/v1` becomes `/v1/v1/chat/completions` and 404s.

Save, hit "Test", then hit "**Update balance**" — the balance column fills in with the credit currently available.

## Where the balance comes from

Platforms like New API read an upstream's balance through **OpenAI's own billing endpoints**, which this platform implements verbatim:

```text
GET /v1/dashboard/billing/subscription    → hard_limit_usd (total credit)
GET /v1/dashboard/billing/usage           → total_usage (spend, in cents)
balance = hard_limit_usd − total_usage / 100
```

So there is **nothing extra to configure** — a valid key is enough. Both are also mounted without the `/v1` prefix, since some clients strip it before appending.

> **Self-hosted enterprise deployments** should use the **`/v1`** form: the box's Nginx only routes `/api/`, `/v1/` and `/v1beta/` to the backend, so a prefix-less `/dashboard/billing/*` lands on the frontend instead of returning JSON. On the public `zhonkeapi.dflop.top`, either form works.

You can verify the same figure yourself:

```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` is always identical to the balance New API derives. Full schemas for both billing endpoints are in the [API reference](../reference/api-reference.md#get-v1-dashboard-billing).

**Worth knowing:**

- **All three endpoints still return 200 at a zero balance** (every other endpoint would 402), so a drained key shows up in the relay as `$0` rather than as a broken channel.
- Checking the balance is **not billed, doesn't consume rate limit, and doesn't update the key's "last used" time** — polling on a schedule is safe.
- `used_usd` only ever counts **this one key**. Other keys on the same account, and an enterprise owner's pooled spend, are never folded in — so issuing one key per relay platform keeps their usage cleanly separated.
- The balance itself is **shared by every key** on the account (one wallet; keys have no separate budget pool). An **uncapped** key running dry means the account ran dry, and a new key brings no new credit — top up at dflop.top/dashboard/billing.
- To cap a single key's spend, configure it on the [key detail page](https://zhonkezhonkemodel.dflop.top/dashboard/keys). A cap changes two things: the relay then sees that key's **remaining allowance** rather than the whole account balance, and once the cap is used up that key 402s **even though the account still has funds** — at which point topping up does nothing and you need to raise the cap or switch keys.
- Conversely: **without a cap, the key's holder can read the whole account's balance** (the owner's pool, for an enterprise key) through the balance endpoint. Set a cap before handing a key to an outside relay operator.

## Model list

"Fetch model list" calls `GET /v1/models`, which returns the platform's whole catalogue. **Trim it**: the catalogue includes image, video, music and speech SKUs that live on [their own endpoints](../reference/media-apis.md) and can only error (400 or 503) on a chat channel. Keep the conversational models.

If the key carries an `allowed_models` allowlist, `/v1/models` returns only what's on it — a convenient way to constrain what a relay can forward.

## Other clients

Many desktop clients (Cherry Studio, ChatBox, NextChat, LobeChat and others) hit the same billing pair for their "check balance" button, and configure the same way: Base URL `https://zhonkezhonkeapi.dflop.top` (or `https://zhonkezhonkeapi.dflop.top/v1` if the client insists on a version prefix — both spellings are served), key `sk-gpushare-*`. Exact behaviour depends on your client's version; where a client has no such feature, the curl above answers the same question.

## Troubleshooting

| Symptom | What to check |
|---|---|
| Balance shows 0 or never updates | Run the curl above first: a number back means the endpoint is fine and the problem is on the relay side (usually a `/v1` left on the Base URL). An actual 0 has **two** causes: the account is out of credit (top up), or **this key's spend cap is used up** (the account may still have funds, so topping up won't help — raise the cap on the key detail page) |
| 401 `invalid_api_key` | Was the key copied in full (76 characters)? Is it disabled or expired? |
| Channel test passes but chat 402s | `/v1/models` doesn't check the balance, so the test passes. A 402 means either the account is out of credit (every key fails at once; a new key won't help) **or** this key's spend cap is used up (affects only that key) |
| 404 with two `/v1` in the path | Base URL was set to `https://zhonkezhonkeapi.dflop.top/v1` — drop the `/v1` |
| Balance is right but slightly stale | `used_usd` is cached for up to 60 seconds; `remaining_usd` is always live |
| An agent key is refused | Agent-scoped keys may only call `/v1/chat/completions` and `/v1/agent/*`, never the balance endpoints. Use a normal key |

## Other integrations

- [Open WebUI](./open-webui.md) — self-hosted ChatGPT-like interface
- [Claude Code](./claude-code.md) — AI coding in the terminal
- [Cursor](./cursor.md) — AI built into the IDE
- [Cline (VS Code)](./cline.md) — agentic AI coding
- [Continue.dev](./continue.md) — VS Code / JetBrains
- [FlopCode](./flopcode.md) — this platform's official fork