Tokens, cache and billing

Understand usage, cache discounts, and incomplete-generation estimates.

Text generation is priced in SimpleCredits (SC) per million tokens, with separate rates for uncached input, cached input, and output.

Read usage correctly

In OpenAI-style usage, cached input is included in prompt_tokens. Never add it to the prompt total a second time.

{
  "prompt_tokens": 100000,
  "completion_tokens": 10000,
  "total_tokens": 110000,
  "prompt_tokens_details": {"cached_tokens": 70000}
}

This example means 30,000 uncached input tokens, 70,000 cached input tokens, and 10,000 output tokens. A dashboard may show uncached input and cache separately; check the field semantics before comparing totals.

Calculate text cost

uncached_input = prompt_tokens - cached_tokens
cost_sc = (
    uncached_input * input_rate
    + cached_tokens * cache_rate
    + completion_tokens * output_rate
) / 1_000_000

When price_sc_cached is null, the regular input price applies to cached input too; the current V1 billing implementation also treats a zero cache rate as this fallback, not as free caching. A low cache rate is not a promise of a cache hit.

Worked example

Using DeepSeek-V4-Flash catalogue rates observed on 2026-09-14 (32 SC/M input, 8 SC/M cache, 48 SC/M output):

This is an illustrative estimate using those rates, not an invoice or a guarantee of future pricing. Final recorded usage determines the charge.

Encourage reusable input

Keep stable system instructions, tool definitions, and shared context in a consistent order, and append changing input after stable content where your workflow permits.

Caching is managed by the model service. V1 does not expose a universal cache reservation, cache lifetime, hardware affinity, or guaranteed cache-hit API.

Long conversations resend history and increase input volume. Consider summarization or selective history when the task allows it; do not remove information the model still needs solely to chase a cache percentage.

Partial usage after cancellation

An interrupted streaming request with zero recorded output tokens is not charged; its credit reservation is released. Output includes reported reasoning or tool output, not just visible answer text. Non-streaming requests are streamed internally and buffered until completion. If canceled, output usage comes from provider counts or the output already received by SimpleLLM, including transmitted reasoning and tool calls. Elapsed time alone does not create output charges. Reported input usage may still be charged for a canceled non-streaming request.

Once a stream has produced output, cancellation does not erase that partial usage. When final provider usage is available, the backend can use it; when the stream is interrupted before final usage, V1 can estimate usage from the request and observed output.

Automatically discarded upstream attempts are not added to the customer charge. A failed non-streaming generation that produces no usable answer is not charged.

The current estimated-input fallback assumes 70% cached input. That percentage is a billing fallback, not a measurement of actual cache use or a promised cache hit on the next request.

A cancelled call may appear as 499 in request logs even though the client cannot receive that status after disconnecting. Keep incomplete-response handling separate from whether the request has a charge.

Account balance versus usage window

GET /v1/usage returns daily usage for the last 30 days alongside current balance and lifetime total_spent. Adding 30-day spending to current balance does not reconstruct lifetime purchases.

Inspect usage and key endpoints for integration details. Audio and images have separate units described in their guides.