# Models & pricing

> Query the MirAPI model catalogue via GET /v1/models, compare models by context, capabilities, and price, and understand pricing tiers, discount badges, and channel failover.

One API, many models. The catalogue at https://console.mirapi.ai lists 200+ models from multiple vendors, and you call any of them through the same endpoints — for chat, you only change the `model` field. The catalogue is also an API, so you can browse and filter it programmatically.

## Browsing the catalogue

`GET /v1/models` returns every entry, and a Gemini-compatible list is available at `/v1beta/models`:

```bash
# OpenAI-compatible
curl https://api.mirapi.ai/v1/models \
  -H "Authorization: Bearer $MIRAPI_API_KEY"

# Gemini-compatible
curl "https://api.mirapi.ai/v1beta/models" \
  -H "x-goog-api-key: $MIRAPI_API_KEY"
```

The list accepts `Authorization: Bearer` (the scheme is case-insensitive, and a bare key without the scheme also works). On `/v1/models` you can use `x-api-key` instead; the Gemini variant accepts `x-goog-api-key` or a `?key=` query parameter.

Each entry carries the fields you need to choose:

| Field | What it tells you |
|---|---|
| `id` / `name` | The exact name to send in requests |
| `context_length` | Maximum context window, in tokens |
| `pricing` | USD per 1M tokens — input / output / cache read |
| `supported_parameters` | Which request features the model supports (tools, vision, reasoning, …) |
| `output_modalities` | What the model can produce: text, image, video, audio, embeddings |

Entries fall into two classes:

- **Available** — MirAPI operates a channel today; the card shows real channel pricing and you can call it now.
- **Coming soon** — listed with the vendor's official pricing, but no channel yet. You can't call it until it flips to available.

## Choosing a model

Start from what the task needs:

1. **Capabilities first** — does it need tool calling, vision input, reasoning, or JSON output? Filter by those.
2. **Context window** — long documents or large codebases need a larger window.
3. **Price** — compare input/output per-1M-token prices; the model detail page shows the exact numbers.
4. **Send the exact `id`** the catalogue returns — model names are passed through verbatim.

The console supports filtering by context size, capabilities, vendor, series, and output type, so you can narrow hundreds of models to a shortlist in seconds.

## Model names

Call models by the name the catalogue returns — for example `deepseek-chat`. That string is passed through verbatim.

The catalogue also displays a browsing ID with a `vendor/` prefix (for example `deepseek/deepseek-chat`). The prefix is only used for browsing and filtering in the console — it is not part of an API request. When in doubt, copy the exact name from the model card.

## Capabilities

`supported_parameters` tells you which request features a model accepts. The common ones, and what they unlock:

| Capability | What it enables |
|---|---|
| Tool calling | Send `tools` / `tool_choice` so the model can call your functions |
| Vision input | Pass images via `image_url` (HTTP(S) URL or base64 data URI) |
| Reasoning | Control effort with `reasoning_effort`; reasoning tokens are billed as output |
| Structured output | Use `response_format` (json_schema or JSON mode) for guaranteed JSON |
| Prompt caching | OpenAI-compatible models cache automatically; Anthropic uses `cache_control` |
| Web search | The model must be marked as web-search capable in the catalogue |

`output_modalities` lists what the model returns — text, image, video, audio, or embeddings — so pick a model whose output matches your task.

## Pricing

For text and multimodal models, price is quoted per 1M tokens in three tiers:

| Tier | What it covers |
|---|---|
| Input | Tokens in the request |
| Cache read | Tokens served from prompt cache — cheaper than fresh input; enable it per [Prompt caching](/docs/guides/prompt-caching) |
| Output | Generated tokens, including reasoning/thinking tokens |

Image generation is billed per image and video generation per second of output. Catalogue prices are in USD and are the authoritative source; this page describes the mechanism rather than fixed numbers.

Billing runs on a prepaid USD balance that never expires — no subscription, no minimum spend. When the balance runs out, requests return 403 and the same key works again immediately after you top up. See [Billing](/docs/billing) for reconciling usage.

## Discount badges

A model card may carry a discount badge (for example "up to X% off"). It compares MirAPI's combined input+output price against the vendor's official list price for the same model. The badge is a price comparison, not a quality claim — the model and its output are identical.

## Channels and failover

Each available model can be served by several channels (different upstream routes). The displayed price is the model's real channel price.

MirAPI routes each request to a healthy channel and steers around degraded ones automatically — you don't configure failover. If every channel for a model is down, the request fails with a 5xx rather than silently substituting a different model — there is no model-level fallback.

## Key whitelists

A key can be restricted to a whitelist of models at creation time. A whitelisted key calling a model outside the list gets 403 even though the key itself is valid. Keys can also carry a validity period, a quota cap, and an IP allowlist — see [Authentication](/docs/api-reference/authentication).

## Troubleshooting

| Status | Meaning | What to do |
|---|---|---|
| 401 | Key missing, invalid, or unknown | Check the key; see [Authentication](/docs/api-reference/authentication) |
| 403 | Key valid but rejected — balance, whitelist, quota, or IP | Fix the cause; top up if the balance is empty |
| 413 | Payload too large | Reduce the request size |
| 429 | Rate limited (no `Retry-After` header) | Retry with jittered exponential backoff (1s → 2s → 4s, capped ~30s) |
| 5xx | Upstream or channel failure | Retry idempotent requests; attach the request ID from the error to any ticket |

Every error message ends with a request ID — include it when you open a support ticket. Full error shapes are in [Errors](/docs/api-reference/errors).

## Related links

- [Billing](/docs/billing)
- [OpenAI compatibility](/docs/openai-compat)
- [Prompt caching](/docs/guides/prompt-caching)
- [Authentication](/docs/api-reference/authentication)