Billing & balance
Every request is paid from your prepaid balance. Before a request runs, part of your balance is held; when it finishes, only actual usage is charged.
Balance and available balance
- Your balance grows with approved USDT deposits and shrinks with usage charges.
- Held funds are the amount reserved by requests that haven’t finished yet.
- Available balance = balance − held funds. New requests can only hold from the available balance, so your balance never goes negative.
You can also read your balance and ledger and create USDT top-up invoices without the dashboard, through the Account API .
Lifecycle of a request
- Hold. Before the request is sent to the model, the maximum possible cost of that request is held.
- Run. The request is forwarded to the model provider.
- Charge. When it finishes, the cost is calculated from the usage the provider reports, at the price in effect when the request started. That amount is charged and the rest of the hold returns to your available balance.
How much is held
The hold is calculated from your own request, not a fixed amount:
- Text: an input bound (the prompt size in bytes plus 1,024 tokens, a little more when the request defines tools, capped at the model’s context limit) times the model’s highest input rate, plus the output bound (
max_tokens, ormax_output_tokenson/v1/responses) times the output rate. - No output limit: the output bound is the model’s context limit, so the hold is much larger. Claude models called through
/v1/chat/completionsare the exception: they default to 16,384 output tokens. For text-and-tools models the output bound is always the context limit, whatevermax_tokenssays. - Images, PDFs and reasoning items: a request that contains an image, a PDF document or (on
/v1/responses) areasoningitem is held for the whole context on the input side, because its token count cannot be read from its size. - Embedding: the byte length of the input text (or the number of elements for an array of token IDs) times the embedding rate.
- Image:
n× the per-image price. - Video:
duration_seconds×n× the per-second price.
Tip
Always setmax_tokens to what you need. A sensible limit keeps the hold small, so more requests can run at the same time on the same balance. Every request also has a maximum hold. A request that needs more than that is rejected with 400, with a message suggesting a lower max_tokens or a shorter prompt.
Insufficient balance (402)
If your available balance is smaller than the hold a request needs, the request is rejected with 402 before it runs, at no cost. The response states the required amount and your available balance, in USD and in nano-dollars (1 USD = 1,000,000,000).
402 · /v1/chat/completions
HTTP/1.1 402 Payment Required{ "error": { "message": "insufficient balance: this request needs a hold of 0.004821 USD (4821000 usd_nanos) but 0.001 USD (1000000 usd_nanos) is available", "type": "insufficient_balance", "required_usd_nanos": "4821000", "available_usd_nanos": "1000000" }, "request_id": "…"} On /v1/messages the same fields appear in the Anthropic error format ({"type": "error", "error": {…}}). In the rare case that your balance changes between the hold and the charge, a 402 with the same type may arrive without the two amount fields.
Billing headers
| Header | Meaning |
|---|---|
x-billing-request-id | The billing ID of this request, as shown on the Usage page. |
x-billing-state: settled | The request has been charged. |
x-billing-state: released | Nothing was charged. The held funds are back in your available balance. |
x-billing-state: pending | The outcome could not be recorded right away. It is resolved automatically shortly afterwards: charged from the usage the provider reported, or released. |
x-billing-state: streaming | A streaming response. The outcome is sent as the SSE comment : x-billing-state settled, released or pending just before the stream closes. |
If the connection drops
Model providers bill for the whole generation even if the client stops listening. So if your connection drops mid-stream, we keep reading the provider’s stream to its end to get the official final usage, and charge that. The same limits apply as for a connected stream: 300 seconds of silence, 30 minutes in total. The cost is still capped by the max_tokens you requested.
If the stream fails before it finishes (it is cut off, the provider errors midway, or it times out), the provider still bills the tokens it already consumed. You are then charged only for the usage the provider reported before the failure: the input (including cache) and the output generated so far. Such a request is marked Partial on the Usage page. If the provider reported no usage at all, nothing is charged and the held funds are released in full. Each request is settled once, so a request is never charged twice.
Two rare cases are charged from the hold rather than from reported usage alone. A reply that finishes normally but arrives without any usage figures is charged the amount held for it. And a stream that we have to cut ourselves (after 300 seconds of silence, or at the 30-minute limit) once output has already been sent to you is charged for the usage reported so far, counting at least the output already delivered and at most the output limit you requested; if no usage was reported at all, the amount held is charged.
The same applies to a non-streaming reply that comes back incomplete (for example without a stop reason) but with usage, and to a reply that only arrives after your request has timed out: you receive the timeout, but we still read the provider’s late reply and charge the usage it reports (for images and video: what was delivered), marked Partial. A late or incomplete reply without usage is not charged.
A request has to get its first response within 90 seconds. Which timeout you receive tells you whether you may be charged. If the request had not reached the provider yet, you get 408: it is never sent afterwards, nothing is charged, and it is safe to retry. If it had already been sent, you get 422 with type timeout_error (“The upstream provider timed out after the request was sent. You may have been charged for partial usage…”) and the header x-should-retry: false, so the OpenAI and Anthropic SDKs don’t retry it automatically and pay a second time. Check the Usage page before sending it again.
If a provider reports more usage than the funds held for the request, the difference is taken from your available balance and then from bonus credit valid for that model; anything beyond that is not charged.
When you are not charged
- The request is rejected before it runs: an invalid key, insufficient balance, an unavailable model or endpoint, or an unsupported field.
- The provider rejects the request with an official validation error (HTTP 400), so nothing is generated.
- You call
/v1/messages/count_tokens: counting tokens is free.
A provider error (for example 429 or 5xx) that reports no usage is not charged either: the held funds are released automatically. Before such an error reaches you, the request has already been tried on the other routes available for the model; each failed attempt is released the same way.
Cached tokens and tool calls
- Cached prompt tokens are billed at the cache rates shown for the model on Models & Pricing. A cache read never costs more than the input rate, and a cache write never costs less than it. For a model that shows no cache-read rate, cache reads are billed at the input rate.
- On Claude models you control caching with
cache_controlon /v1/messages. Tokens written to the 5-minute cache are billed at the cache-write rate and tokens read from it at the cache-read rate. - Function calling has no price of its own. Tool definitions count as input tokens and tool calls as output tokens, in the usage the provider reports, like any reply.