Documentation

Quickstart

1. 1. Sign up
2. 2. Top up your balance and create an API key in the dashboard.
3. 3. Paste your key into the snippet below and run the request.

curl https://apimira.com/v1/chat/completions \
  -H "Authorization: Bearer am-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "messages": [
      {
        "role": "user",
        "content": "Hello!"
      }
    ]
  }'

The base_url is the address above with a /v1 suffix. The model is set via the model parameter.

Copy the Model ID from the catalog in full, including the part before «/»: for example google/gemini-3.7-flash or anthropic/claude-sonnet-4.6.

Connect your apps

Any app with an OpenAI-compatible API connects with three values (Claude Code and the Anthropic SDK are the exception — they speak a different protocol; see the card below):

If the field is just «Base URL», the app appends /chat/completions itself — do not add it. And make sure the address does not end up as /v1/v1.

To test the key without an app, run the request from the Quickstart block above.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ApiMira": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "ApiMira",
      "options": {
        "baseURL": "https://apimira.com/v1",
        "apiKey": "am-YOUR_KEY"
      },
      "models": {
        "openai/gpt-5.4-mini": { "name": "GPT-5.4 Mini" },
        "anthropic/claude-sonnet-4.6": { "name": "Claude Sonnet 4.6" }
      }
    }
  }
}

Chat — generate a response

POST /v1/chat/completions

Generates a model response. Supports stream=true (SSE). Request and response formats match OpenAI.

Streaming: pass "stream": true. Chunks arrive as data: {...} and end with data: [DONE].

Supported: text chat (including tool calls via tools and tool_choice), image input on models that have the capability, image generation and editing, video generation. In chat, response_format, functions, audio and modalities still answer 400 — a parameter is never dropped silently.

Request parameters

Body of POST /v1/chat/completions. Only model and messages are required — everything else has a sensible default.

What comes back

The shape matches OpenAI, so the official SDKs parse it with no changes.

Image input

A model that can look at pictures accepts them right in the conversation: a screenshot of an error, a photo of a receipt, a mockup. No separate endpoint is needed — the image travels as a part of the message next to the text, through the same POST /v1/chat/completions. The same works on /v1/messages and /v1/responses.

How to send an image

In a user message, content becomes an array of parts: text is a part of type text, an image is a part of type image_url whose url is a string shaped like data:image/png;base64,… — the image type and its bytes in base64. The order of parts is preserved: the model sees them in the order you sent them. The detail field (auto, low, high) is passed to the model as is. A message may consist of images only, with no text.

{
  "role": "user",
  "content": [
    { "type": "text", "text": "What does this screenshot say?" },
    {
      "type": "image_url",
      "image_url": { "url": "data:image/png;base64,iVBORw0KGgo…", "detail": "auto" }
    }
  ]
}

The gateway never fetches remote links: an image behind http or https returns 400 invalid_request with a hint. Encode the file to base64 yourself — that is one line in any language.

curl https://apimira.com/v1/chat/completions \
  -H "Authorization: Bearer am-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "messages": [{ "role": "user", "content": [
      { "type": "text", "text": "What does this screenshot say?" },
      { "type": "image_url", "image_url": { "url": "data:image/png;base64,'"$(base64 -w0 shot.png)"'" } }
    ]}]
  }'

Limits

• — Formats: PNG, JPEG, WebP. The type is checked against the first bytes of the file, not against its name: a "png" with something else inside returns 400 here, before the model.
• — One image — up to 5 MB of binary data; in base64 the same file takes about a third more.
• — Up to 50 images per request — every image in the conversation counts, not just the ones in the last message.
• — A request body with images — up to 24 MB. This limit outranks the number of images: 50 of them only fit when they are small.
• — A body over 2 MB is read only for a working key with a positive balance, and the upload has 30 s to finish — after that 408 request_timeout with a Retry-After header. The number of large uploads in flight is capped: the next one gets 429 with Retry-After, so retry it after the stated delay.
• — More than 20 images in one request: some models then accept only small ones — up to 2000 px on the long side.

Which models see images

The capability is confirmed by a live probe rather than by a promise: today 38 models of the catalogue accept images. The same ones carry the "Sees images" mark on the Models page, and GET /v1/account/pricing returns them in the capabilities field. A model without the capability answers 400 unsupported_capability and is never charged.

openai/gpt-6-astra · openai/gpt-5.6-sol · openai/gpt-5.6-terra · openai/gpt-5.6-luna · openai/gpt-5.5 · openai/gpt-5.4-mini · openai/gpt-5.3-codex · anthropic/claude-fable-5.1 · anthropic/claude-fable-5 · anthropic/claude-fable-5-compressed-context · anthropic/claude-opus-5 · anthropic/claude-opus-4.8 · anthropic/claude-opus-4.7 · anthropic/claude-opus-4.6 · anthropic/claude-opus-4.5 · anthropic/claude-sonnet-4.6 · anthropic/claude-sonnet-4.5 · anthropic/claude-haiku-4.5 · google/gemini-3.7-flash · google/gemini-3.6-flash · google/gemini-3.1-pro-preview · google/gemini-3.1-flash-lite · google/gemini-3-flash-preview · google/gemini-2.5-pro · x-ai/grok-4.6 · x-ai/grok-4.5 · x-ai/grok-4.3 · x-ai/grok-build-0.1 · z-ai/glm-5.3 · z-ai/glm-5.3-flash · z-ai/glm-5.1 · moonshotai/kimi-k3 · moonshotai/kimi-k2.7-code · moonshotai/kimi-k2.5 · qwen/qwen3.8-max · xiaomi/mimo-v2.5-pro · xiaomi/mimo-v2.5 · minimax/minimax-m3

What an image costs

An image is billed as input tokens of the model. How many is up to the model: usually around 1 089 tokens for a 1024×1024 frame, and several times more on some models. You are charged exactly what the model returned in usage.prompt_tokens — the same formula as for text. A hold with a margin is placed for the request and the remainder returns to the balance (see Pricing and charges). An estimate of the same order comes back from POST /v1/messages/count_tokens.

Images from agents

An image produced by a tool result — the agent read an image file or took a screenshot — reaches the model as well. In the OpenAI protocol a tool result carries text only, so the gateway forwards such images as a separate user turn right after the series of results; the order of the conversation is preserved. Nothing to configure.

On /v1/responses an image is an input_image part; detail: original is treated as high. On /v1/messages it is an image block with a base64 source; a url source is not fetched, exactly as in chat. document and file blocks still answer 400: file input is not accepted yet.

Rejections

400 invalid_request — wrong format, bytes that do not match the declared type, an image over the size or count limit, an image in a system, developer or assistant message. 400 unsupported_capability — the model does not accept images. 400 context_length_exceeded — the images plus the text do not fit the model context. 408 request_timeout — the body did not arrive in full in time. 413 payload_too_large — the body is over the limit. None of these rejections is billed.

Image generation

POST /v1/images/generations

POST /v1/images/generations — synchronous, request and response are OpenAI Images-compatible. A fixed price per image is charged, multiplied by the count (n).

curl https://apimira.com/v1/images/generations \
  -H "Authorization: Bearer am-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "a red cat wearing glasses",
    "n": 1
  }'

The model must be an image model (see GET /v1/models). The response is a data array, each item carrying b64_json: the frame as base64. We never hand out a link, even when the model returns one — the frame arrives as bytes. Token-priced models also return usage: exactly the numbers you were charged for. The x-request-id response header is the id of the charge record, so the request can be found in GET /v1/account/usage.

Image editing

POST /v1/images/edits

POST /v1/images/edits changes an existing image from a text prompt: replace the background, add a detail, follow a style. The body is multipart/form-data, as in the OpenAI Images API: a file (or several) plus a prompt. The response is a base64 frame.

curl https://apimira.com/v1/images/edits \
  -H "Authorization: Bearer am-YOUR_KEY" \
  -F model=openai/gpt-image-2 \
  -F prompt="Replace the background with a light gradient" \
  -F image=@cat.png

Response:

{
  "created": 1757700000,
  "data": [{ "b64_json": "iVBORw0KGgo…" }],
  "usage": { "input_tokens": 116, "output_tokens": 1650, "total_tokens": 1766 }
}

The model picks the format of the frame: one returns PNG, another JPEG. We neither promise nor convert it — read data[0].b64_json as image bytes and, if the type matters, detect it from the first bytes.

The usage field is not always there: a per-frame model returns none at all — you pay for the frame, not for tokens. The input_tokens_details and output_tokens_details breakdown appears only when the model provided it: check for the field instead of relying on it.

Request fields

Accepted and not forwarded to the model

quality, user, background set to opaque or auto, input_fidelity set to low. A request carrying them works, but the result and the price stay as they would be without them.

Pricing and charges

Pricing matches generation on the same model; there is no separate tariff for editing. On a token-priced model input and output are counted at its rates, and usage in the response shows exactly the numbers you were charged for. On a per-frame model the price of a frame is multiplied by the number of frames. A hold with a margin is placed for the request and the remainder returns; a model failure costs nothing.

The Content-Length header is required: an upload without it (chunked) returns 400 invalid_request. If your client streams the file, read it into memory or set the size yourself.

The response carries an x-request-id header — the id of the charge record. It finds the request in GET /v1/account/usage (the id field) and in the dashboard; the OpenAI SDK exposes it as request_id.

Which models edit images

Editing is enabled on 2 models of the catalogue today. They carry the "Editing" mark on the Models page, and GET /v1/account/pricing returns the image_edit capability in the capabilities field.

openai/gpt-image-2 · google/gemini-3.1-flash-image-preview

Video generation

POST /v1/videos/generations

Video is generated asynchronously: the request creates a job and returns its id right away. The seconds parameter is required — it sets the clip length and drives the price.

curl https://apimira.com/v1/videos/generations \
  -H "Authorization: Bearer am-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "alibaba/wan-2.6",
    "prompt": "a paper boat drifting on a calm pond",
    "seconds": 5
  }'

# {"id": "9b2f…", "status": "processing", "created": 1755648000}

GET /v1/jobs/{id}

Poll for readiness every 5–10 seconds. status: processing — still running, succeeded — done (the response carries the clip url), failed — did not work out (see error). Generation takes 30 seconds to 3 minutes. The url points to the provider’s storage — download the file right away.

curl https://apimira.com/v1/jobs/JOB_ID \
  -H "Authorization: Bearer am-YOUR_KEY"

# {"id": "9b2f…", "status": "succeeded", "url": "https://…/clip.mp4"}

The charge is price per second × seconds. Money is reserved when the job is created and debited only once the clip is ready; if generation fails, the reserve is returned in full.

Models and durations

The model must be of type “video” (see GET /v1/models). Per-second prices are on the models page.

Endpoints

Pricing and charges

How it works

• — You top the balance up in advance — no month-end invoices and no subscriptions.
• — Every request is charged its own cost, which depends on the model and on the number of tokens.
• — The balance drops right after the answer. When it runs out, requests answer with 402 — the account never goes negative.

How the cost is calculated

Each model has its own price, quoted per 1 million tokens — separately for input (your request) and output (the model's answer). Output is almost always the dearer half. Current prices for every model live in the Models and pricing catalogue.

input   =  input_tokens   / 1 000 000 × input_price
output  =  output_tokens  / 1 000 000 × output_price
────────────────────────────────────────────────────
total   =  input + output

Each half is rounded up to one millionth of a dollar. The token counts come from the model's own answer — the very usage field you see in your code.

Worked example

model:         openai/gpt-5.4-mini
input price:   $0.12 per 1M tokens
output price:  $0.64 per 1M tokens
request:       1 200 input tokens, 800 output tokens

input     1 200 / 1 000 000 × $0.12  = $0.000144
output    800 / 1 000 000 × $0.64    = $0.000512
────────────────────────────────────────────────
charged:                             = $0.000656

The prices above are not made up — they are pulled from the live catalogue, the same one the bill uses.

Cache discount

When a request starts with the same text as the previous one — a system prompt, instructions, a long context — the model serves that part from its cache, and we bill those tokens at a discounted rate. There is nothing to switch on: the cache kicks in by itself when an identical prefix arrives back to back and is long enough (roughly a thousand tokens or more). The first request, the one that writes the cache, does not cost extra: it is billed exactly as it would be without a cache.

input  =  (input_tokens − cached_tokens) / 1 000 000 × input_price
       +  cached_tokens / 1 000 000 × cached_input_price

The number of tokens served from cache is in the response: usage.prompt_tokens_details.cached_tokens, or usage.cache_read_input_tokens on the /v1/messages endpoint. The same figures appear in the dashboard, in GET /v1/account/usage and in the CSV export. The cached-input rate is listed on the Models page and in GET /v1/account/pricing. Not every model gets the discount: where no rate is listed, the cache is billed at the regular input price.

The hold while a request runs

While the model is answering, nobody knows how long the answer will be. So before we call the model, the worst case is held on your balance:

hold  =  input_tokens / 1 000 000 × input_price
      +  max_tokens / 1 000 000 × output_price

If the hold does not fit, the request is refused straight away, before the model is called. Once the answer arrives, the real cost is charged and the rest of the hold returns to the balance the same moment.

same request,  max_tokens: 4 000

held:              $0.002704
actually charged:  $0.000656
returned:          $0.002048

Set max_tokens close to the answer length you expect: the bigger it is, the bigger the hold and the less balance is left for parallel requests. With no max_tokens the hold is computed against the 32,000-token ceiling.

When you are not charged

An error on the model's side (502, 504) costs nothing and the hold returns in full. A refused request — wrong key, empty balance, unsupported parameter, oversized body — is free too: it never reached the model. Token estimation via /v1/messages/count_tokens is always free.

Where to watch your spend

In the dashboard. The key page shows a log of requests with model, tokens and cost for each, a CSV export and a daily chart. The Usage section shows a summary for the period and a breakdown by model. We never store the text of requests or answers — the statistics hold only these counters.

Account API — balance, prices, and key statistics

A read-only API for your account: balance, retail prices, and key usage from your own backend — no dashboard needed. The dashboard section "Account management" collects the base URL and ready-made snippets.

Authorize with the same key you use for model requests: the Authorization: Bearer header. GET only; the key must be active (paused and revoked keys get 401). Never put the key in a URL or browser code. Statistics are scoped to the key making the request; balance and prices are account-wide.

Query parameters

All parameters are optional. Out-of-range values return 400 invalid_request with the parameter name in param.

Examples

curl https://apimira.com/v1/account/balance \
  -H "Authorization: Bearer am-YOUR_KEY"

# {"object": "account.balance", "balance_usd": 4.981234, "currency": "USD"}

curl "https://apimira.com/v1/account/usage?days=7&limit=25" \
  -H "Authorization: Bearer am-YOUR_KEY"

Response:

{
  "object": "list",
  "days": 7,
  "limit": 25,
  "page": 0,
  "has_more": false,
  "data": [
    {
      "id": "9b2f…",
      "created_at": "2026-08-21T09:58:12.000Z",
      "model": "openai/gpt-5.4-mini",
      "operation": "chat",
      "status": "success",
      "tokens_in": 1200,
      "cached_tokens_in": 0,
      "images_in": 0,
      "tokens_out": 800,
      "cost_usd": 0.000656,
      "price_input_usd_per_1m_tokens": 0.12,
      "price_cached_input_usd_per_1m_tokens": 0.0168,
      "price_output_usd_per_1m_tokens": 0.64,
      "price_generation_usd": null,
      "latency_ms": 812
    }
  ]
}

The /v1/account/analytics response is a single object with:

totals · models[] · daily[] · errors.by_code[]

Errors

The error envelope is shared across the gateway (see the Errors section). You may encounter:

401 invalid_api_key · 400 invalid_request · 429 rate_limited

Limits and restrictions

The limits protect you as much as the gateway: a stray loop in your code should not burn the balance in a minute.

Going over the rate gives 429 rate_limited: wait and retry, the key is neither blocked nor penalised. A body over 2 MB is read only for a working key with a positive balance: the upload has 30 s, and the number of large uploads in flight is capped — an extra one gets 429 with a Retry-After header. Spend limits and the schedule are yours to set in the dashboard on the key page. Guessing at wrong keys from one address is slowed down on top of that.

Error codes

Every error arrives in the same shape as OpenAI's, so the SDKs parse it for you:

{
  "error": {
    "message": "The model `openai/gpt-9` does not exist or is disabled.",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "param": "model"
  }
}

Branch on code: it is machine-readable and stable. The message text is written for a human and may change. The param field points at the specific request field when the error is in one.

Nothing in this table is billed. If the request never reached the model, or the model answered with an error, no money is taken and the hold returns to the balance in full.

Common questions