# MirAPI Documentation

> MirAPI is an OpenAI-compatible API gateway that routes your existing SDK or agent to chat, image, video, audio, and embeddings models from major vendors on one prepaid balance.

MirAPI is a single, OpenAI-compatible API gateway in front of 200+ models from every major vendor. Point your existing SDK or agent at it, and routing, billing, and logging all happen in one place — no per-provider accounts or keys to manage.

## What is MirAPI?

MirAPI speaks the OpenAI wire format, so most of the code you already have keeps working unchanged. The integration is intentionally small: **change your `base_url` and go**. Your prompt shapes, streaming, and tool-calling logic stay the same — only the endpoint and the API key change.

On top of that, MirAPI also accepts Anthropic Messages and Gemini request formats, so Claude- and Gemini-native tooling works too. Every model and capability is billed against one prepaid USD balance.

## How it works

```text
Your app (OpenAI SDK / agent)
│ base_url = https://api.mirapi.ai/v1
▼
MirAPI gateway ──► Model vendor A
──► Model vendor B
──► Model vendor C …
```

1. Register at https://console.mirapi.ai and top up a prepaid USD balance.
2. Each request is routed to a healthy channel of the model you asked for and billed at that model's displayed rate. If every channel for a model is down, the request fails — MirAPI never silently switches models.
3. No subscription, no monthly minimum, no expiry — your balance stays until you use it.

## Quick start

Change `base_url` to `https://api.mirapi.ai/v1`, set your key, and send a chat request with `deepseek-chat`:

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.mirapi.ai/v1",
    api_key="sk-...",  # your MirAPI key
)

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "Hello, MirAPI!"}],
)
print(response.choices[0].message.content)
```

The same call over plain HTTP:

```bash
curl https://api.mirapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "Hello, MirAPI!"}]
  }'
```

:::tip
Any OpenAI SDK works by changing only `base_url`. Keep your API key on the server — never ship it in client-side code.
:::

## Supported protocols

| Protocol | Base URL | Authentication |
|---|---|---|
| OpenAI-compatible | `https://api.mirapi.ai/v1` | `Authorization: Bearer sk-...` |
| Anthropic Messages | `https://api.mirapi.ai` (no `/v1`) | `x-api-key` or `Authorization: Bearer` |
| Gemini | `https://api.mirapi.ai` or `https://api.mirapi.ai/v1beta` | `x-goog-api-key` or `?key=` |

Rule of thumb: if a tool appends its own path (for example `/chat/completions`) to the base URL, set it to `https://api.mirapi.ai/v1`. Anthropic SDKs point at `https://api.mirapi.ai` directly.

## Capabilities

- Chat: `/v1/chat/completions`, `/v1/responses`, and `/v1/responses/compact`
- Anthropic Messages and Gemini `generateContent`
- Embeddings, rerank, and moderations
- Image generation and edits
- Video generation (asynchronous task flow)
- Audio transcription, translation, and speech
- Realtime speech over WebSocket
- Prompt caching, tool calling, structured outputs, and reasoning

Inspect the full catalogue with `GET /v1/models`, which returns each model's `id`, `name`, `context_length`, per-token `pricing`, `supported_parameters`, and `output_modalities`.

## Errors and rate limits

### Common status codes

| Status | Meaning | What to do |
|---|---|---|
| 401 | Missing, invalid, or unknown key | Fix your credentials |
| 403 | Key is valid but rejected (balance, whitelist, quota, IP) | Resolve the cause and retry |
| 413 | Request too large | Reduce the size |
| 429 | Rate limited | Retry with jittered exponential backoff (no `Retry-After` header is sent) |
| 500 | Upstream failure | Retry idempotent requests safely |

The gateway does not retry for you. For `429`, back off with jitter — for example 1s → 2s → 4s, capped around 30s. Every error message ends with a request ID; include it in any support ticket.

:::note
A drained balance returns **403**, and the same key works again immediately after you top up.
:::

## Billing at a glance

Text and multimodal chat are billed per token (per 1M tokens, with separate input, output, and cache-read rates). Images are billed per image and video per output second. Reasoning tokens count as output; cache reads are cheaper than ordinary input.

Balances are prepaid in USD, never expire, and have no subscription or minimum. To reconcile usage, use the console billing log, `GET /api/usage/token` (account-level totals), or `GET /api/log/token` (per-request detail). See [Billing](/docs/billing) for details.

## Troubleshooting

- **401 on every request** — check the key is present and unchanged; the `Bearer` scheme is case-insensitive and a bare key is also accepted.
- **403 after a successful day** — most often the balance is drained; top up and retry with the same key. Whitelist, quota, and IP-allowlist restrictions also return 403.
- **429 under load** — add jittered backoff; the gateway does not throttle for you.
- **Streaming stops early** — streams are standard SSE: `data:` lines ending with `data: [DONE]`, with reasoning content arriving before the answer.

## Navigate the docs

| Section | What you'll find |
|---|---|
| [Quickstart](/docs/quickstart) | Register, top up, create a key, and make your first request |
| [Configuration](/docs/configuration) | Base URLs, auth headers, streaming, timeouts, and reconciliation |
| [Billing](/docs/billing) | Prepaid balances, the three pricing units, and usage logs |
| [Models & pricing](/docs/models) | The catalogue, model names, pricing, and discount badges |
| [OpenAI compatibility](/docs/openai-compat) | Endpoint support and known differences from OpenAI |
| [Capability guides](/docs/guides/images) | Images, video, audio, realtime, vision, embeddings, reasoning, structured outputs, prompt caching, web search |
| [Integrations](/docs/integrations) | Claude Code, Codex, Cursor, SDKs, and other tools |
| [API reference](/docs/api-reference) | Authentication, errors, and every endpoint |
| [Tutorials](/docs/tutorials) | Complete, runnable end-to-end examples |
| [FAQ](/docs/faq) | Billing, keys, rate limits, and privacy |

## Related links

- [Quickstart](/docs/quickstart)
- [Configuration](/docs/configuration)
- [Models & pricing](/docs/models)
- [API reference](/docs/api-reference)