Usage and costs
How to calculate the API cost of a task
Start with the model, service tier, request conditions, and billing unit. Then add up the requests made for the task. An input rate, discount percentage, or single generation price does not tell you the cost of the whole task.
Start with rates and usage
Use current rates to estimate a new request and Usage to check charges already recorded. All amounts below are in USD and are hypothetical examples, not quotes from XiuAI or a model provider.
Match the conditions before comparing rates
The same model can have different rates for its service tier, context length, processing mode, or image settings. Keep those conditions consistent and use the applicable XiuAI rate. Provider reference prices are comparison points, not the rates used to calculate your bill.
- Read the unit first: a price per million tokens cannot be compared directly with a price per request or another stated unit.
- If a cache rate or additional charge is not shown, check that model’s documentation. A missing field does not mean a zero charge.
Text and cache: calculate each billable category
For token pricing, each charge is the billable token count ÷ 1,000,000 × the corresponding rate. Add the applicable charges. Split ordinary input, output, cache reads, and cache writes using the model’s usage definitions. Some protocols include cached tokens in the input total, so do not count the same tokens twice.
- Assume one context band, the default processing mode, and no extra tool charges. The four categories below have already been separated for billing and do not overlap. All rates are hypothetical.
- Ordinary input: 100,000 tokens × $1 per million tokens = $0.10.
- Output: 20,000 tokens × $5 per million tokens = $0.10.
- Cache reads: 50,000 tokens × $0.10 per million tokens = $0.005.
- Cache writes: 10,000 tokens × $1.25 per million tokens = $0.0125.
- Example total: $0.2175. A real request does not necessarily incur both cache reads and writes. Reconcile it using the model’s applicable metering and settlement rules.
Images: distinguish request pricing from token pricing
Image requests are not all billed by image count. Check the model’s pricing unit, whether per request, per token, or another measure, along with resolution, quality, and input/output conditions. Do not multiply a per-request price by the returned image count again unless the pricing rules require it.
- Assume a model charges $0.03 per billable request at one fixed configuration. Four billable requests cost 4 × $0.03 = $0.12. This is a per-request example, not a general quote of $0.03 per image.
- If the selected model uses token pricing, use its actual input and output metering instead of the per-request formula above.
Video: duration is not a universal billing unit
Use the pricing conditions for the exact video model and parameters. With video-token pricing, use the task’s actual metering. Dividing one video’s charge by its duration does not create a per-second rate that applies to every model. Inputs such as reference video can change both the rate and usage.
- Assume a task has a confirmed usage of 200,000 video tokens at a hypothetical rate of $8 per million tokens: 200,000 ÷ 1,000,000 × $8 = $1.60. Both figures are examples for the calculation.
- A successful submission does not mean the result is ready or the charge is final. A timeout does not prove that the upstream rejected the task. Check the existing task ID and recorded charge before creating another task.
Budget for the whole agent task
An agent task can include several model calls, tool results, and retries. History and tool results included in later calls affect input usage. Add the applicable request charges instead of estimating only the user’s initial prompt.
- Measure calls, input/output usage, caching, and cost on a small set of your own tasks. Estimate from the same workload and check again after changes to context or retry behavior.
- Use the records to determine whether a failed request incurred a charge and whether a task has settled. Do not assume every non-2xx response is free or infer a final charge from a successful submission alone.
Reconcile estimates against request records
Compare the same time range, model ID, actual service tier, context band, processing mode, usage units, and currency. Today’s rates may differ from those applied to an earlier request. Use the relevant request record for past charges. To bring those records into internal reports, use the separate Account & usage API.
Continue with model selection and integration
Choose a model for the task
Narrow your options by input/output needs, API format, and task cost.
Pricing and Usage documentation
Check current fields, units, and cost troubleshooting steps.
Bring cost data into your own system
Separate model requests from read-only account access and issue the key you need.