> ## Documentation Index
> Fetch the complete documentation index at: https://omnirelay.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage and billing

> How requests are metered, priced and recorded.

Real models are billed using validated token usage and the customer prices confirmed for the request. They reserve a maximum charge first; ambiguous failures after dispatch keep a hold pending reconciliation. See [Model access and request diagnostics](https://omnirelay.ai/docs/general/provider-integration.md).

Every successful chat completion is metered and debited atomically. The following partial example uses GPT 5.4 Mini at full price; other prices or discounts produce different charges:

```json theme={null}
{
  "usage": { "prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15 },
  "cost_microusd": 30
}
```

## Multi-model capabilities and prices

Live routes are enabled per workspace. Read your own `GET /v1/models` for IDs, input/output/cache rates, discounts and `price_version`; do not apply the GPT 5.4 Mini example prices or limits below to other models. Most integrated text models allow up to 128,000 output tokens and default to 32,000 (Gemini 3.1 Pro Preview and Gemini 3.6 Flash: at most 65,536); DeepSeek V4 Pro, GLM 5.3 and Kimi K3 default to and allow at most 4,096; check SSE and reasoning support in `capabilities`. Holds use a request-sized input bound capped by that model’s input ceiling, the requested output limit and current customer prices; validated usage determines the final charge. Public catalog visibility is not key permission. See [List models](https://omnirelay.ai/docs/llms/listing-models.md).

## GPT 5.4 Mini charge and reservation example

The `gpt-5.4-mini` endpoint is available only in explicitly enabled
workspaces. At full price, its frozen customer rates are:

| Token partition | USD / 1M tokens |
| - | - |
| Uncached input | \$0.75 |
| Cached input reads | \$0.075 |
| Cache writes | \$0; no separate write charge on this endpoint |
| Visible output | \$4.50 |
| Reasoning output, if reported within completion usage | \$4.50 |

This model has no fixed per-request fee. `prompt_tokens` includes cached
reads/writes; `completion_tokens` includes reasoning. Bill each token once:

```text theme={null}
uncached input = prompt_tokens − cached_tokens − cache_write_tokens
visible output = completion_tokens − reasoning_tokens
request charge = sum(partition tokens × partition rate) / 1,000,000
```

Zero usage detail counters may be omitted. Present nonzero
`prompt_tokens_details.cached_tokens` are charged at the cache-read rate, not
treated as uncached input. Total usage and nonnegative partitions are validated;
unknown usage dimensions prevent automatic settlement. The endpoint accepts only
reasoning `none`, injected when omitted, and does not expose reasoning text.

Round the **whole request** up once to integer micro-USD, then apply the frozen
workspace/model discount and round up to integer micro-USD again. A model-specific
discount replaces the workspace discount rather than stacking. Live discovery
shows base rates plus `discount`/`customer_discount_bps`; do not assume the input
and output base rates have already been discounted. The final charge depends on
the model's verified usage and the workspace's active customer prices.

Before executing the request, this endpoint holds **an input bound plus the requested
output ceiling independently**. Since 2026-10-07 the input estimate is a third of the
UTF-8 byte length of the request sent to the model provider plus 4,096 tokens of fixed overhead, priced
at the uncached input rate and capped by the 400,000-token input ceiling. It is an estimate,
not a token count: when verified usage costs more, the difference is charged only if the
total is at most twice the hold and the wallet, key budget, member limit and platform capacity
all cover it; otherwise the request stays pending reconciliation. Default output is 64 tokens,
with a service maximum of 256. The maximum hold depends on current workspace prices.
A short prompt still needs available wallet/key budget for its hold.
It is not a fixed fee or measured prompt usage.
Final validated usage settles the actual charge and releases unused money.

The model context remains 400,000 tokens; a reservation does not increase context capacity.
Failures, timeouts, cancellations or missing valid final usage after dispatch can
leave the hold `pending` for review. Retain your `X-Request-ID`; the error code tells you whether
the call was charged (see [Errors](https://omnirelay.ai/docs/general/errors.md)), and support can confirm a single call by its ID.

## Image models

Image models (`gpt-image-2`, `gpt-image-2.5`) are called with [Create images](https://omnirelay.ai/docs/api-reference/images/create-images.md) and [Edit images](https://omnirelay.ai/docs/api-reference/images/edit-images.md) (guide: [Image generation and editing](https://omnirelay.ai/docs/images/image-generation.md)) and are priced per image, not per token. The requested `size` sets the tier for every image in the call:

| Tier | Requested `size` | List price per image |
| - | - | - |
| 1K | longest side up to 1024 px, for example `1024x1024` | USD 0.134 |
| 2K | longest side up to 2048 px, for example `1536x1024` or `2048x2048`; also `size` omitted or `auto` | USD 0.201 |
| 4K | longest side up to 4096 px, for example `3840x2160` | USD 0.268 |

`quality` does not change the price. Your discount applies as for text models, and `GET /v1/models` shows each tier's price for your workspace under `pricing.per_image` (micro-USD). A call reserves `n` images at its tier and settles only the images returned. A refused call (bad parameter, rate limit, a provider refusal) is not charged. A call that times out or fails after it was sent (error `image_call_held`) is held for review and charged only if the provider produced the images, because the provider bills a finished image either way. Images are returned as `b64_json` only; `response_format: "url"` is refused before any charge. A call that has not finished after about 25 seconds answers `200` at once and sends spaces until its JSON body arrives, which keeps proxies from closing the connection; read the body before checking for an `error` object.

## Video models

Video models (`doubao-seedance-2-0-260128`) run as background tasks through the [video task API](https://omnirelay.ai/docs/videos/video-generation.md) and are priced at USD 25 per million output tokens. A task generates width × height × (24 × seconds + 1) / 1024 output tokens: a 5-second 480p 16:9 clip is 50,638 tokens, about USD 1.27. Submitting holds the cost of the largest frame at the requested resolution and duration plus 10%; a successful task settles the tokens actually generated, and failed, expired or cancelled tasks release the whole hold. A task that cannot be confirmed when it is submitted (error `video_submit_held`) is held for review and charged only if the video was generated. Your discount applies as for text models, and `GET /v1/models` shows the price for your workspace under `pricing.output` (micro-USD per million tokens).

## Balance and ledger

* Settled charges are linked to request records and the internal settlement ledger; they are shown in Usage rather than the visible funds ledger. A budget rejection before dispatch incurs no call charge.
* Live calls can return `402 inference_budget_or_access_denied` when available funds, key budget or service access cannot satisfy the request; the request has not executed.
* A person with a [member budget](#member-budgets) fails with `402 member_budget_exceeded` once the period's cap is reached.
* Rejected requests before dispatch are not charged. A failed live call after dispatch can retain a hold and later be settled from validated usage and charges.

## Member budgets

An administrator can cap what one person spends per **day**, **week** or **month** (UTC calendar periods; weeks start on Monday). The cap covers every API key that person holds and their playground calls, whichever balance pays.

* Spend in a period is the settled cost of their requests plus any live holds still open, so concurrent calls cannot all squeeze under the cap.
* A call that would go over fails with `402 member_budget_exceeded` before reservation and request execution, and is recorded as a failed request.
* Calls that cost nothing, where the configured workspace call is free, are never blocked by the cap.
* The next period starts fresh; nothing needs resetting.

Members see their cap, what is used and when it resets on the **Billing** page. Administrators set it from **Users** or **Customers** in the admin console.

## In the console

| Page | What you get |
| - | - |
| **Usage** | Four tabs over your real request records. **Overview**: spend, requests, tokens, error rate and average latency against the previous period, plus spend by model and by API key. **Requests**: hourly or daily volume with failures. The paginated per-request log (request ID lookup and CSV export) is off by default for customer accounts; ask support if your workspace needs it. **Explore**: group by model, provider, API key, status, [Tags](https://omnirelay.ai/docs/general/tags.md) or day and measure spend, requests, tokens or errors. **Performance**: success rate and P50, P95 and maximum latency per model. Ranges are 24 hours, 7, 30 or 90 days, in UTC |
| **Billing** | Cash/trial balances, cumulative credited top-ups, wallet movements, payments with their provider and payment method, and each payment's invoice and receipt from the provider |

## Retries

Chat completions are not idempotent yet. Re-sending creates a new request and can create a second charge. Check diagnostics before retrying a live failure.

## Cash, trial credits and cumulative top-ups

**Billing** separates cash and trial balances. Trial credits are used first for request reservation and settlement; cash covers the remainder. Unused reservation amounts return to their original balance category. An unresolved dispatched request can still have an outstanding hold.

**Cumulative top-ups** is the sum of positive, credited payment top-ups and payment-credit corrections. Trial grants are excluded; usage and refunds do not reduce this gross total. It is not your remaining balance or net payments after refunds.

The visible **funds ledger** contains wallet movements such as payments, refunds, trial grants and adjustments, labelled cash or trial credits. Model usage, call reservations and reservation releases are omitted from this list. Find actual model charges in **Usage**. The administrator's customer funds drawer separately shows cash balance, cash deduction, trial balance and trial deduction. Deductions sum actual settled request amounts, exclude pending/released holds, and retain up to six decimal places in USD. Refunds and balance adjustments are not model consumption.

## Top-up currency, invoices and receipts

Top-ups are priced and credited in USD. Paying in a local currency on the provider's page includes the provider's conversion fee and exchange rate; the balance is credited the order's USD amount, and a refund returns the same share in the currency paid. Invoices and receipts are issued by the payment provider (Stripe: invoice and receipt; Airwallex: invoice) to the workspace's billing details, which the first payment fills in when they are empty. See [User manual → Top-ups, budgets, invoices and receipts](https://omnirelay.ai/docs/user-manual.md).

## Log timezone and period comparisons

Choose **Settings → Account timezone** to display request, login, billing and audit log times in a fixed timezone; the default follows your browser. Switching accounts uses that account’s preference. Stored/API timestamps, statistics buckets and budget/billing calendar boundaries remain UTC. A display timezone change does not move a request to another statistics bucket or change a charge.

For **24 hours**, the current rolling 24-hour window is compared with the immediately preceding 24-hour window under the same filters. **No previous-period data** means there is no comparable baseline: the preceding window has no requests, or the relevant metric is zero and cannot form a percentage comparison. It does not mean current records were lost.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.