Cost

How cost is computed

• Uncached token requests are priced per token: prompt_tokens × prompt price + completion_tokens × completion price, using the decimal per-token rates from the catalogue.
• A model's price is its retail price, the provider's public list price, less any discount AI Hub applies to that route. You pay retail when there is no discount, and never more than retail. The catalogue shows the price you are charged.
• Some token models price the whole request by prompt size: once the prompt reaches a tier's min_prompt_tokens, every token in the request is priced at that tier. Cached prompt tokens, where the provider reports them, are priced at input_cache_read. Both are in the model's pricing in GET /v1/models.
• Image and video pricing depends on the model and serving route. Some images cost per image or per request; others use separate input-text, output-text and output-image token meters. Video can combine output seconds with input-media charges. Speech, music and embeddings also use their own meters. Read every applicable leg of tokenhub_price_table; the output modality does not determine its billing unit.
• The capability endpoints (translation, OCR and the others on the Capabilities page) are priced per successful call. An answer that does not match the documented shape costs nothing. Prices are listed under Console → APIs.
• The token counts come from the response's usage object, which is provider-final. When the gateway could not obtain it the fields are absent rather than guessed.
• Reasoning (thinking) tokens are billed at the completion price and are included in completion_tokens. When the response carries completion_tokens_details.reasoning_tokens, that is the part of completion_tokens spent on reasoning, not an extra charge. Where an upstream reports reasoning separately, the gateway adds it to completion_tokens so the response matches what is billed.
• reasoning_tokens can be 0 or absent when you asked for reasoning. A model with adaptive thinking decides per request and often skips it at low effort. A model that reports no breakdown bills its reasoning inside completion_tokens only.
• Authoritative USD amounts use decimal strings. Compatibility fields such as /generation's numeric total_cost are projections; use exact ledger amounts for accounting. A cost aggregated from per-token rates survives the round trip without binary rounding.
• Each request's cost has a status: priced, unpriced (the model had no price when it ran) or unknown (the provider did not report the usage the price needs). A usage row with a non-zero unpriced_requests or unknown_cost_requests is provisional: its total understates the row.

Customer charge and supplier evidence

A receipt with total_cost: 0 and cost_complete: true resolves the customer charge at zero. Supplier usage or supplier-cost reconciliation can still be incomplete; missing final provider usage alone is insufficient evidence of zero supplier cost. Keep the original request and provider-attempt evidence when investigating a discrepancy.

Releasing a reserved hold restores available spending capacity; it is separate from a payment or refund. The Activity cost_usd and price_version_id fields retain their own cost/price pairing; use the generation receipt for its customer-cost completion state. Contact support with the request ID to resolve an ambiguous charge; do not repeat a paid request to investigate it.

Adding credits

• Every top-up carries a service fee of 5.5% of the credits, at least $0.80. The wallet receives the credits; the fee is not added to them.
• 9% GST applies when the billing country is Singapore or the card was issued in Singapore. It is charged on the subtotal, the credits plus the fee. The billing country comes from the billing address you enter with your first card; edit it, your company name and your GST number in the Billing portal.
• The service fee and GST are shown before you pay, and the invoice shows each line.

Look up one request

Every response carries its request id in the X-Generation-Id header. Pass it to GET /v1/generation with any active key of the same workspace to read that request's tokens, latency, provider and cost. The field names follow OpenRouter's generation endpoint.

curl "https://tokenhub-api.belive.sg/api/v1/generation?id=req_01j9x2rk7m4bqf8ah3zt6cvnwg" \
  -H "Authorization: Bearer $TOKENHUB_API_KEY"

{
  "data": {
    "id": "req_01j9x2rk7m4bqf8ah3zt6cvnwg",
    "created_at": "2026-09-24T02:00:00.000Z",
    "model": "deepseek/deepseek-v4-pro",
    "provider_name": "alibaba-model-studio",
    "status": 200,
    "streamed": false,
    "latency": 812,
    "tokens_prompt": 21,
    "tokens_completion": 9,
    "total_cost": 0.0000936,
    "cost_complete": true,
    "is_byok": false,
    "preset_id": null,
    "workspace_id": "ws_01j9x2rk7m4bqf8ah3zt6cvnwg"
  }
}

• total_cost is what the request counts toward your spend, in US dollars: the price of the request plus any fee of AI Hub's own, as the spend totals and key caps count it. It is null while cost_complete is false, which means the provider's usage for the request is not final yet. A recorded request refused before any work reports 0. Some validation rejections are not written to the generation log: their X-Generation-Id can return 404 even when the original error explicitly says charged: false. Keep that error response; use the original error and settled receipt to determine cost. A bare lookup 404 is insufficient evidence for repeating an uncertain submission. Your account's settled charge is authoritative and can be lower: a failed attempt is not charged.
• A malformed id returns 400 invalid_request. A well-formed id that does not exist, or a request from another workspace, returns 404 not_found. The response never contains the prompt or the completion.
• This endpoint reads one request. For usage totals, export them with a management key that holds usage:read (GET /mgmt/v1/usage; see the Management API).

What a request costs you today

Its settled cost, computed as above. A key's monthly cap also stops requests once the key's spend reaches it — see Rate limits & caps.

A cost question not covered here? The support page has a direct line.

Reading every pricing shape

pricing: null means there is no flat Chat-style price projection. It does not mean free usage or necessarily non-token pricing. Inspect tokenhub_pricing and tokenhub_price_table on the exact model and selected route. Availability, promotions and prices can change; the request's settled price version remains authoritative.

For a price table:

1. Select the row whose when conditions match the request and observed output, including resolution, audio, size or token tiers. A row label is descriptive; its conditions are the rule.
2. For each leg, use its measured quantity and decimal amount divided by per. If the leg declares included, only quantity above that allowance is billable. Sum all priced legs, then apply the table's multiplier and rounding rule. A table may explicitly list unbilled meters; missing usage is otherwise unknown, not zero.
3. Keep the native table and decimal precision. Do not flatten mixed legs or conditional tiers into one per-image or per-million-token price. rounding_unit_usd, when present, applies after the sum and multiplier; compare the settled receipt rather than independently rounding every leg.
4. Use tokenhub_pricing/pricing.overrides for token tiers. Where a tier is selected by total prompt size, its rates apply to the whole request, not just tokens above the threshold.

For example, a token-metered image can have both a text-input charge and an image-output-token charge, while a per-image model uses its measured image count. A one-output music request can use request: 1 even when its duration is several minutes. The response usage and the selected table determine which case applies.