How a call is paid
A call reserves its worst case, runs, then pays only what the model wrote.
Balances can never go into debt by surprise. So before a call starts, it reserves its worst-case cost. When it ends, the real cost is taken and the rest goes back at once.
- CheckKey, model and body
- ReserveHold the worst case
- AnswerThe model writes
- ChargeTake the real cost
A 1,200-token prompt, from an agent with $0.50.
max_tokens allows. You pay only what the model wrote, and the rest goes back at once. Without a limit the reserve is the model's whole output, 128,000 tokens here, and a small balance can't cover it.The steps
- Check. The key, the agent, the model and the body. Anything wrong answers at once, free.
- Reserve. The worst case is held from the balance: the whole prompt plus the longest answer the call allows. If the balance can't cover it, the answer is
402 insufficient_balance, with both amounts, and nothing runs. - Answer. The model runs and the answer streams back to you as it's written.
- Charge. The real cost is taken, and the rest of the reserve is freed. Every answer that carries a cost reports this charge in
usage.cost.
What the reserve counts
- The prompt: its text at about 3 characters a token, 8,000 tokens per image, and the model's whole context for files sent by link.
- The answer:
max_tokens(max_output_tokenson Responses). Without it, the model's whole output limit. - The price: the dearest provider that could run the call, so a fallback never costs more than was held.
- Tool loops: every step a search loop could take. Cap it with
max_tool_calls. - At least $0.001, for the smallest call.
The one habit that matters
Set max_tokens to what you need. A hello with no limit on a frontier model reserves
dollars; with max_tokens: 256 it reserves a fraction of a cent. It changes what the
call holds, never what it costs.
Running calls hold money
A call's reserve is held while it runs, so ten long calls at once hold ten reserves. spendable_usd in GET /balance is what new calls can reserve now; reserved_usd is what running calls hold.
When no cost comes back
If a call is cut before the answer carries its cost (you disconnected, the stream broke or the format carries none), the call is priced from the provider's own record within a minute. Its reserve stays held until then.