Configuration

Everything you configure for a request lives in two places: the base URL decides which protocol you call, and the request body decides which model and parameters you use. This page covers both, along with the parameters, error handling, and retry behavior that apply to every request.

Base URLs

Protocol	Base URL	Auth
OpenAI-compatible	`https://api.mirapi.ai/v1`	`Authorization: Bearer`
Anthropic	`https://api.mirapi.ai` (bare, 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=`

Use the same key everywhere; the protocol is determined by the URL you call.

Rule of thumb: if your tool appends its own path (for example /chat/completions), point it at https://api.mirapi.ai/v1. Anthropic clients point at the bare https://api.mirapi.ai instead.

Authentication

Send the key as Authorization: Bearer <key>. The scheme is case-insensitive, and a bare key with no scheme is also accepted. Anthropic endpoints additionally accept x-api-key; Gemini endpoints accept x-goog-api-key or ?key=. The OpenAI-Organization header, if your client sends it, is ignored.

A key can carry four constraints: a model whitelist (models outside it get 403), a validity period, a quota cap, and an IP allowlist. A 401 means the key is missing, invalid, or unknown; a 403 means the key is valid but the request was rejected (balance, whitelist, quota, or IP).

See Authentication for the full details.

Chat parameters

The chat endpoint accepts the standard OpenAI-style parameters:

Parameter	Purpose
`model`	Model name exactly as returned by `GET /v1/models`
`messages`	Conversation history with `system`, `user`, `assistant`, and `tool` roles
`temperature`	Sampling randomness, 0–2 (default 1)
`top_p`	Nucleus sampling, 0–1 (default 1)
`max_tokens` / `max_completion_tokens`	Upper bound on output tokens
`presence_penalty` / `frequency_penalty`	Discourage repeated tokens; negative values encourage reuse
`stop`	Up to 4 strings that stop generation
`seed`	Best-effort reproducibility where the model supports it
`stream`	`true` for SSE streaming
`tools` / `tool_choice`	Function calling (see Tool calling)
`response_format`	JSON output (see Structured outputs)
`reasoning_effort`	OpenAI-style reasoning control (see Reasoning models)

Not every model accepts every parameter. Check the model’s supported_parameters in the catalog (or its card in the Platform) to see which ones it accepts.

Protocol variants

All three protocols share the same key and the same models. Choose the one your client already speaks.

OpenAI-compatible

Use https://api.mirapi.ai/v1 as the base URL. Chat runs through POST /v1/chat/completions (or POST /v1/responses for Responses-API clients). Authenticate with Authorization: Bearer. Errors come back in the OpenAI envelope {"error":{"message","type","param","code"}}, where type is new_api_error (gateway-side) or upstream_error (upstream failure, message sanitized).

Anthropic

Use the bare https://api.mirapi.ai (no /v1) with the Anthropic SDK. The endpoint is POST /v1/messages, authenticated with x-api-key or Authorization: Bearer. Enable prompt caching with cache_control: {"type":"ephemeral"}. You can set up to four explicit breakpoints, and the cache can be extended to one hour with "ttl":"1h" at a higher write price. Errors use the Anthropic envelope {"type":"error","error":{"type":"permission_error","message"}}.

Gemini

Use https://api.mirapi.ai or https://api.mirapi.ai/v1beta and authenticate with x-goog-api-key or ?key=. Generation runs through POST /v1beta/models/{model}:generateContent; embeddings are also available in Gemini style at POST /v1/engines/{model}/embeddings.

Streaming

Set stream: true and the endpoint answers with standard SSE. Each chunk is one data: line, and the stream ends with data: [DONE]:

curl -N https://api.mirapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $MIRAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "Count to three"}],
    "stream": true
  }'

Each chunk carries a delta; the final chunk carries the usage object. With reasoning models, the reasoning content arrives before the answer. Any OpenAI-compatible SDK parses the stream for you.

Usage in responses

Non-streaming responses include a usage object with prompt_tokens, completion_tokens, and total_tokens. It reports token counts only. The monetary amount is in the Platform billing log and GET /api/log/token, never in the API response. To confirm a prompt-cache hit, look at usage.prompt_tokens_details.cached_tokens (and cache_write_tokens for writes).

Billing

MirAPI is prepaid: you top up USD at https://platform.mirapi.ai; there is no subscription or minimum, and your balance never expires.
Text and multimodal chat are billed per 1M tokens in three tiers (input, output, cache read); image generation is billed per image; video generation is billed per second of output.
Reasoning/thinking tokens are billed as output; cache reads are cheaper than fresh input.
An exhausted balance returns 403, and topping up restores the same key immediately.
Reconcile through the Platform billing log, GET /api/usage/token (account-level summary), or GET /api/log/token (per-request detail).

See Billing & top-ups for the full picture.

Errors

The API uses standard HTTP status codes:

Status	Meaning
401	Missing, invalid, or unknown key. Fix the credential.
403	Valid key but request rejected (balance, whitelist, quota, IP). Resolve the cause and retry.
413	Request body too large. Reduce it.
429	Rate limited. Back off and retry.
500	Gateway or upstream failure. Idempotent requests are safe to retry.

Insufficient balance is rejected with 403. Every error message ends with a request ID; include it in support tickets. See Errors for the response envelopes and sanitization behavior.

Timeouts and retries

MirAPI does not retry requests on your behalf. Retry logic belongs in your client.
On 429, back off with exponential delay and jitter (1s → 2s → 4s, capped at ~30s) and stop after a few attempts. The 429 response has no Retry-After header.
Retrying idempotent requests that fail with 429 or 5xx is safe. For non-idempotent requests (image/video generation, tool side effects), do not blindly replay the request.
Set generous timeouts for non-streaming calls (30–60s) and no timeout for SSE streams.

Troubleshooting

Wrong model or unsupported parameter: copy the exact id from GET /v1/models and check its supported_parameters. The vendor/ prefix is Platform-only and never part of an API request.
403 on a key that used to work: usually an exhausted balance (top up to restore it instantly), or a whitelist / quota / IP restriction on the key.
429 rate limits: back off with jitter and retry; no Retry-After header is sent.
404 on an endpoint: /v1/files, /v1/fine-tunes, and /v1/messages/count_tokens are not implemented and return 404.
Unexpected cost: reasoning tokens are billed as output, and cache reads are cheaper than fresh input. Reconcile in GET /api/log/token.