docs
Billing

Reserves and charges

Markdown

How Ailoot handles billing: a reserve before the request, one charge afterward, and a balance that never goes below zero.

In brief

  • Reserve — before sending a new text request, Ailoot reserves an estimate of the input and a typical response under the request’s accepted terms. Image, video and audio output retain a reserve for the full cost of the result.
  • Charge — one charge, based on the actual usage in usage. Any unused reserve is released immediately.
  • If there is not enough money even for the minimum reserve — the request is not sent to the model. You receive a 402 error with a clear message, and nothing is charged.
Full guide

In brief

  • Price — in dollars per 1 million input and output tokens, or per unit: an image, a second of video, or characters. Each model’s prices are listed in the catalog.
  • Reserve — before sending a new text request, Ailoot reserves an estimate of the input and a typical response under the request’s accepted terms. Image, video and audio output retain a reserve for the full cost of the result.
  • A lower limit instead of a rejection — if the calculated reserve exceeds the available balance or key limit, the response limit can be reduced only for the exact model and method that respect it, and only to an affordable output length at or above the applicable minimum. See which models support this below.
  • Charge — one charge, based on the actual usage in usage. Any unused reserve is released immediately.
  • If the response costs more than the reserve — the difference is taken from the available balance not held by other reserves. The charge never exceeds your balance, so your balance never goes below zero.
  • If there is not enough money even for the minimum reserve — the request is not sent to the model. You receive a 402 error with a clear message, and nothing is charged.
  • A failure with no result is not billed. If the connection drops, check the request by its Request ID in your Dashboard history before sending it again.

How the reserve is calculated

  • Input is reserved using an estimate of the request size and supported attachments, rather than an already known actual usage amount. New text requests use an estimate of the body and attachments according to their type. The calculation “4 tokens per byte, with a minimum of 4096 tokens” applies to previously accepted reserves under the old version; it does not describe new text reserves. If an attachment is supplied by URL (fileData) or built-in tools are enabled, supported text requests include a separate estimate for attachments and tool activity; their presence alone does not mean the full input window is reserved. Existing reserves retain their accepted terms, while media output retains a reserve for the full result.
  • Output for a new text request’s reserve is estimated from a typical response length and the accepted terms. The requested limit is set through max_tokens (max_output_tokens in Responses). The requested limit is not automatically the token count used to calculate the reserve, and does not guarantee the actual response length for a model without reliable capping. The default value of 4096 applies only to the corresponding routes; the exact rule depends on the model and method.
  • Price for new text reserves that account for the request’s terms reflects the standard or priority mode and the price tiers reachable by the input estimate. The calculation remains conservative within the selected conditions; flex mode does not reduce the reserve. For a priority request, the reserve may account for the most expensive applicable mode, including priority, flex or fast. Previously accepted reserves without these terms retain their original calculation using the highest rates.
  • Reducing the limit — when the calculated reserve does not fit and the exact model and method support response capping: the available funds must cover the input estimate and the minimum output length. The reduced limit never falls below 256 tokens (1025 with thinking in Anthropic format). The model receives this reduced limit.

Calculation example

Model claude-sonnet-5-5: input $2 and output $10 per 1 million tokens. You sent 20,000 tokens, and the model returned 1,200 tokens.

StepCalculationAmount
Actual input20 000 × $2 / 1 000 000$0.0400
Actual response1 200 × $10 / 1 000 000$0.0120
Chargedone charge based on actual usage$0.0520

In this arithmetic example, the actual cost is $0.0520. The debit shown assumes that the accepted reserve and available free balance cover that cost. The reserve amount is not calculated here: for a new text request, it is calculated separately using the estimated input and a typical response, and may be higher or lower than the actual cost. Any unused reserve is released; the debit limit is shown in the formula below.

Actual charge = min(full actual cost, accepted reserve + free unreserved balance). Other open reserves remain protected, so the total balance does not necessarily fall to zero. The balance never becomes negative. If the actual cost exceeds the accepted reserve and free unreserved balance, Ailoot absorbs the uncovered difference as a loss: it does not become your debt and is not collected later.

Client disconnection

Closing the connection, an application timeout, or choosing not to read a completed response does not automatically cancel the request: a completed model response is billed once. If the result is not delivered because of an Ailoot failure, the money is returned. If the connection drops, check the request by its Request ID in your Dashboard history before sending it again.

Why you may need a larger balance

  • For new text requests, the response reserve uses a typical response length, taking into account the supplied max_tokens and the exact model’s terms. This estimates the reserve; it does not guarantee the actual response length or cost.
  • For models without a reliable limit on the actual response, the reserve estimate does not become a length cap. New text requests do not automatically reserve the cost of the longest possible response instead. Previously accepted reserves retain their original terms.
  • Input images add their estimated cost to the reserve.
  • Agents such as Claude Code, Codex CLI, and Cline send a large context at every step. A single step may reserve tens of cents. Keep at least a few dollars in your balance.
  • Tip: set a reasonable max_tokens — this reduces the reserve for models whose response length can be capped.

Prompt caching

Models with caching have separate rates for cache writes and cache reads. Reads usually cost several times less than regular input. Prices are shown on the model’s catalog card.

402 error

If your available balance cannot cover even the minimum reserve, Ailoot does not send the request and returns 402 with the code insufficient_balance. If the key’s total spending limit is exhausted, the code is api_key_quota_exhausted. If the account has outstanding debt from a disputed payment, the code is payment_disputed: new requests are paused until that debt is repaid.

402 Payment Required
{
  "error": {
    "code": "insufficient_balance",
    "reason": "insufficient_balance",
    "type": "insufficient_quota",
    "param": null,
    "message": "Your balance is too low to start this request. … Request ID: 5c0e7a1d-….",
    "request_id": "5c0e7a1d-…"
  }
}

Where to view spending

Your request and charge history is in the Dashboard at ailoot.ai. Each request shows the model, token usage, and amount charged.

Still have questions? Send your Request ID and a description — we'll help you troubleshoot.Contact support