Spend caps: what Keylayer reserves, charges and refuses
A Keylayer spend cap reserves a request's worst case before forwarding it, about $0.58 on gpt-5.4-mini with no output limit, and refuses with 403 budget_exceeded when that would pass the cap. Keylayer then charges the reported usage. Hard caps refuse what it can't price; estimated caps can let it through.
Before forwarding, Keylayer reserves an amount for the request. It refuses the request with 403 budget_exceeded if the key's spend so far, plus what running requests hold, plus the new reservation would pass a cap. When the response ends, Keylayer charges the actual cost from the usage the provider reports and frees the rest. A response without usage is charged the full reservation, except an error answer on a route Keylayer prices, which is free unless it's a 504 or 524 timeout. If the client hangs up before Keylayer sends its request to the provider, Keylayer doesn't send it and charges nothing. Once Keylayer has reserved an amount for it, the request still counts toward request caps and the free plan's request limits, like a relayed one.
Hard and estimated caps
- Hard: Keylayer reserves the request's worst-case cost and refuses whatever it can't price up front with 403 unpriced_operation. If a provider ever reports more than the reservation, Keylayer suspends the key.
- Estimated: Keylayer reserves the same worst case when it can price the request. When it can't price a model call, such as one with built-in tools, it reserves a small body-size estimate and lets the request through, so spend can pass the cap. OpenAI's image generation tool also reserves and charges each image. If the client hangs up on such a call, Keylayer reads the provider's answer on for up to 5 seconds and 32 MiB and charges it as if the client had stayed; an answer that isn't done by then is charged the estimate plus any usage it reported so far. When the body still sets a worst case for the call's tokens, such as an OpenAI call with web search, Keylayer charges at least that worst case on top of the estimate, also for a response without usage. The cap counts only the estimate while a call runs, so calls running at the same time can each pass it by that worst case; set Requests at once on the key to limit how many run together. An unknown model gets 403 unpriced_operation, except on OpenRouter chat completions, responses and embeddings, which report their cost. A POST, PUT or PATCH to any other route it can't price gets 403 unpriced_operation, unless the provider doesn't charge for it, such as cancelling a batch, which counts $0.000001. It also refuses with 403 unpriced_operation a body it can't read, a Gemini query parameter other than key or alt, work the provider bills after the response, such as batches, and Anthropic fallbacks, as a hard cap does.
Key limits lists the providers that take each mode, and its escape hatches section covers which of these refusals a key can lift.
How Keylayer prices the worst case
For a model request, the worst case is the input, counted as one token per byte of the body plus 16 per message and 64 more, and the output limit the request sets, such as max_tokens, max_completion_tokens or maxOutputTokens. Without one, Keylayer reserves the model's maximum output. For gpt-5.4-mini that's 128,000 tokens, about $0.58 for every request in flight, so set an output limit to keep reservations small.
Under a hard cap, these OpenAI requests can't be priced and get 403 unpriced_operation: unknown models, audio, predicted outputs, best_of, web search and other built-in tools, remote image URLs and file references, also inside tool call outputs, cache lifetimes other than 30m and 12h, previous_response_id or a stored conversation, and any POST outside chat completions, completions, responses, embeddings, moderations, file uploads, GPT Image 2 and 2.5 generations and edits, and tts-1 and tts-1-hd speech, such as transcriptions. Unknown models, batches, fine-tuning jobs and those other POST routes get 403 unpriced_operation under an estimated cap too, except cancelling a batch, a background response, an eval run or a fine-tuning job, and pausing a fine-tuning job, which count $0.000001, transcriptions and translations, which reserve the upload as 16 kbit/s audio, and gpt-4o-mini-tts speech with stream_format set to sse, which reserves a body-size estimate.
OpenAI's Codex web search, POST /v1/alpha/search, reports no usage, so a hard cap refuses it and an estimated cap charges its flat estimate in full.
Service tiers
Under a hard cap, Keylayer adds the standard service tier to model requests that don't name one, so a premium project default can't raise the price: default on OpenAI, on_demand for chat and default for responses on Groq, and standard_only on Anthropic and Mistral. A request that names a tier Keylayer can't price, such as priority, gets 403 unpriced_operation.
An estimated cap charges a premium tier at its published price. Where none is published, it charges 2.5 times the standard rate on OpenAI and the highest listed rates on Anthropic, Groq and Hugging Face. Anthropic fast mode on Opus 5.5, Opus 5 and Opus 4.8 reserves and charges twice the standard rates under either cap.
Streams and request bodies
With a spend cap on the key or any key above it, Keylayer adds stream_options.include_usage to streamed OpenAI and Mistral chat requests that don't ask for usage, and removes the extra usage chunk before your client sees it. It also reads the whole request body before forwarding, so compressed bodies are refused with 415 content_encoding_unsupported. Without a spend cap anywhere above, the body streams straight through.
Updated