Usage and billing
Usage accounting, balance checks, and charge records.
Real usage first; conservative estimation when necessary
DINGJIAI first extracts real upstream usage for the matching API/wire family, then settles against the current model-product price. A valid non-streaming success JSON object billed by tokens, or a streaming response from which the gateway has extracted model output, may use a conservative lower-bound estimate when usage is missing or invalid.
From call to settlement
Pre-call checks
Validate the user API key, concurrency limit, model state, and account balance. Available balance after subtracting in-flight request reservations must be greater than zero before a model call can start.
Select an upstream candidate
Select an available upstream according to the internal call entry and the model product's public model id.
Forward the request and read the response
Read the complete non-streaming response. For streaming responses, observe usage according to the API/wire family: OpenAI Chat and Gemini retain the last valid usage, Anthropic merges stream usage, and Responses reads response usage from the completion event.
Extract usage and settle
Write real usage when it is valid. When usage is missing or invalid but the safety conditions are met, write an estimate marker. If the call cannot be settled safely, fail closed. When a charge is created, write the corresponding ledger entry at the same time.
Balance boundary
Settlement may make the balance negative
Before a call starts, account balance after subtracting in-flight request reservations must be greater than zero. After the call is settled, the account balance may be charged below zero. An available balance of zero or less blocks new model calls.
Usage sources by API family and operation
Prop
Type
Usage anomalies
| Gateway string | Meaning | Common causes |
|---|---|---|
usage_missing | The upstream response is missing usage required for settlement. | The upstream did not return usage, or a streaming response did not expose the usage required by its API/wire family. |
usage_invalid | The usage format does not meet the requirements. | A token field is negative, has the wrong type, or cached tokens exceed input tokens. |
Conservative lower-bound estimation
- Estimation applies only to a valid non-streaming success JSON object billed by tokens, or a streaming response from which the gateway has extracted model output. Both
usage_missingandusage_invalidmay enter this fallback. - Only output is estimated. The estimate may include visible text,
reasoning/reasoning_content, Anthropicthinkingandtool_use.input, OpenAI Chat / Responses tool or function arguments and reasoning summaries, and GeminifunctionCall; approximately four Unicode characters count as one token. - Input tokens and cached input tokens are not estimated. The reasoning, thinking, and tool arguments above are generated output and therefore count toward the output estimate.
- A valid non-streaming success JSON object uses at least one output token even when no output can be extracted, including
{}. This does not represent the upstream's actual consumption. A streaming response with no valid usage and no extractable output is not estimated; heartbeats, empty events, and raw transport chunks are not billing evidence. - A truly empty or malformed non-streaming body fails closed and is charged zero. A streaming response with no trusted usage or extractable output is also charged zero, but an already submitted 2xx response cannot be rewritten as an error body; its body may be empty or contain only SSE keepalives. When there is no billing evidence, the reservation is released. A disconnect, client cancellation, or delivery failure may still settle trusted partial usage or output already observed by the gateway; settlement does not require the client to have successfully received a chunk. A delivery failure after non-streaming settlement does not roll back the charge, and a failure status does not necessarily mean zero charge.
- Per-image products do not use token estimation. OpenAI and Gemini image entries charge by the actual number of valid images in the response. If there is no valid image, the call fails closed with zero charge; Gemini image products do not depend on
usageMetadata. - Usage records are marked as estimated so they can be distinguished from real upstream usage.
Do not submit client-side estimates
Token counts calculated by the client are not used as billing evidence. The gateway decides between real usage, a server-side estimate, and failure-closed settlement from the actual response.
Last updated on