# Cherry Studio

> Add MirAPI to Cherry Studio as an OpenAI, Anthropic, or Gemini provider and chat with deepseek-chat.

Cherry Studio is a free, open-source desktop chat client for Windows, macOS, and Linux. It calls models through provider "types", and every type can point at MirAPI: an OpenAI-type provider is the primary path, while the Anthropic and Gemini types are there when you need those protocols' semantics.

## What you need

| Element | Value |
|---|---|
| Base URL (OpenAI) | `https://api.mirapi.ai/v1` |
| Base URL (Anthropic) | `https://api.mirapi.ai` |
| Base URL (Gemini) | `https://api.mirapi.ai/v1beta` |
| API key | Your MirAPI key (`sk-...`) |
| Model | `deepseek-chat` (from `GET /v1/models`) |

The same key works across all three provider types and every assistant in the app.

## Configure

1. Open **Settings → Model Services → Add**.
2. Choose the **OpenAI** provider type.
3. Fill in:

```text
Provider name: MirAPI
API base URL: https://api.mirapi.ai/v1
API key: sk-...
```

4. Add a model. In the provider's model list, click **Manage / Add model** and enter the exact id from the catalogue:

```text
deepseek-chat
```

5. Save and enable the provider.

The key is sent as `Authorization: Bearer`; the scheme is case-insensitive and a bare key without the scheme is also accepted. Cherry Studio appends `/chat/completions` to the base URL, which is why the address must include `/v1`.

## Verify with a message

Start a new assistant using the MirAPI provider and send:

```text
Reply with exactly: connected to MirAPI
```

Expect the exact phrase in the reply. If the call errors, keep the message Cherry Studio shows — it ends with the MirAPI request id, which support needs.

## Protocol variants

Cherry Studio also ships Anthropic and Gemini provider types. Both talk to MirAPI through the matching endpoints; pick one when you specifically want that protocol's semantics — for example Anthropic's `cache_control` prompt caching.

### Anthropic

| Element | Value |
|---|---|
| Base URL | `https://api.mirapi.ai` (no `/v1`) |
| API key | Your MirAPI key (`sk-...`), sent as `x-api-key` |

The Anthropic type calls `/v1/messages`. MirAPI accepts the key as either `x-api-key` or `Authorization: Bearer`. Enter the bare base URL — the client appends `/v1/messages` itself, so do not add `/v1`.

### Gemini

| Element | Value |
|---|---|
| Base URL | `https://api.mirapi.ai/v1beta` |
| API key | Your MirAPI key (`sk-...`), sent as `x-goog-api-key` |

The Gemini type calls `generateContent` on `/v1beta/models/{model}:generateContent`. MirAPI accepts `x-goog-api-key` or a `?key=` query parameter; the bare `https://api.mirapi.ai` is also accepted as a base URL.

## Billing

- Chat is billed per token: USD per 1M tokens, with separate input, output, and cache-read tiers. Reasoning tokens are billed as output, and cache reads cost less than plain input.
- MirAPI uses a prepaid USD balance — no subscription, no minimum, and the balance never expires.
- When the balance runs out, calls return 403. Top up and the same key works again immediately.
- Reconcile spend in the console billing log, with `GET /api/usage/token` for the account summary and `GET /api/log/token` for per-request detail.

## Troubleshooting

- **401** — the key is missing, malformed, or unknown. Check it and retry.
- **403** — the key is valid but the request was rejected: the model is not in the key's whitelist, the balance is exhausted, the quota is reached, or the caller's IP is not allowlisted. Fix the indicated condition and retry.
- **429** — rate limited. MirAPI sends no `Retry-After` header, so back off with jitter (1s → 2s → 4s, capped around 30s).
- **500** — an upstream failure; retry idempotent requests safely. MirAPI never silently swaps in another model, so the retry stays on the model you chose.
- Add models by their exact `GET /v1/models` id — a typo is an error, not a fallback.

## Related links

- [Quickstart](/docs/quickstart)
- [Models & pricing](/docs/models)
- [Authentication](/docs/api-reference/authentication)
- [Errors](/docs/api-reference/errors)
- [Billing & top-ups](/docs/billing)