# Chatbox

> Add a custom provider in Chatbox and connect through its OpenAI, Claude or Gemini compatible modes

Source: https://qd.zsopc.com/en/docs/integrations/chatbox

> [Chatbox](https://chatboxai.app) is an AI chat client for desktop, mobile and the web that lets you add your own model providers. These steps were checked against Chatbox v1.24.4 (released 2026-11-12).

## Get an API key

Create one at [qd.zsopc.com/dashboard/keys](https://qd.zsopc.com/dashboard/keys) (`sk-gpushare-` plus 64 hex characters; you can re-reveal it on its detail page at any time).

## Add the provider

1. **Settings** → **Model Provider** → **Add** → **Add Custom Provider**
2. In the dialog, enter a **Name** (anything, e.g. `xiaozhan`), set **API Mode** to **OpenAI API Compatible**, and click **Add**
3. On the provider's page, fill in:
   - **API Host**: `https://qd.zsopc.com/v1`
   - **API Path**: leave empty (the default is `/chat/completions`)
   - **API Key**: your `sk-gpushare-...`
4. Check that the **Preview** line reads `https://qd.zsopc.com/v1/chat/completions`
5. Under **Models**, click **New** and enter a model ID (such as `claude-sonnet-4-6`, `gpt-6.1-sol` or `deepseek-v4.1-flash`), or click **Fetch** to pull the list from `GET /v1/models` and pick from it
6. Click **Check** and pick one of the models you added to test the connection

> **Fetch** returns every model your key can call, including image and video models that don't work in a chat. Add only text models. Full list: [Models](../reference/models.md).

How Chatbox builds the URL: with an empty API Path and a host that doesn't end in `/v1`, it adds `/v1` itself; once you type an API Path, it joins host and path as written. Host `https://qd.zsopc.com/v1` with an empty path is the safest choice, and **Fetch** (which requests `host/models`) works with it too.

## Native Claude or Gemini protocol (optional)

Add another provider and pick the matching API mode:

| API mode | API Host | What Chatbox requests |
|---|---|---|
| Claude API Compatible | `https://qd.zsopc.com/v1` | `/v1/messages` |
| Google Gemini API Compatible | `https://qd.zsopc.com` | `/v1beta/models/...` |

The API Path field has no effect in these two modes. Use Claude models in Claude mode (e.g. `claude-sonnet-4-6`) and Gemini models in Gemini mode (e.g. `gemini-3.1-pro-low`). The OpenAI API Compatible mode reaches these models as well — the gateway translates the protocol for you, see the [compatibility matrix](../reference/compatibility-matrix.md).

## The web version

- **Desktop and mobile**: the app sends the requests itself, so the setup above is all you need.
- **Web**: requests go from your browser straight to the API, and this platform's API does not allow cross-origin calls from third-party web pages, so they fail. Turning on **Improve Network Compatibility** sends them through Chatbox's server instead — which means your API key passes through Chatbox's server. If that matters to you, use the desktop app.

## Troubleshooting

| Symptom | What to check |
|---|---|
| 401 `invalid_api_key` | Whether the key was copied in full (76 characters); re-reveal it on the [key detail page](https://qd.zsopc.com/dashboard/keys) |
| 404 / models won't load | Look at **Preview**: it should be `https://qd.zsopc.com/v1/chat/completions`. A path that repeats `/v1`, or a path typed in while the host lacks `/v1`, gives a 404 |
| 400 `model_not_found` | Model ID spelling — it must match [Models](../reference/models.md) exactly |
| 400 `model_not_allowed` | This key has a model allowlist that excludes the model |
| 402 `quota_exceeded` | Balance exhausted. Every key shares one account balance — top up on the [Top up page](https://qd.zsopc.com/dashboard/billing) |
| Network errors in the web version | See "The web version" above |

Full error reference: [Error codes](../reference/errors.md).

## Other clients

- [Cherry Studio](./cherry-studio.md) — desktop client
- [LobeChat](./lobechat.md) — self-hostable chat UI
- [NextChat](./nextchat.md) — lightweight web chat
- [Open WebUI](./open-webui.md) — self-hosted ChatGPT-style UI
