Docs
Billing
Pay-as-you-go from a prepaid wallet. Every call is metered to the micro-cent and recorded in an immutable ledger. No subscription, no commitment, balance never expires.
Top up via Stripe → balance sits in your wallet → each API call deducts its cost in real time. If your balance hits zero, calls return 402 insufficient_quota until you top up again.
The pricing model
For each call, Kunavo computes the user's cost as the larger of two numbers:
- Catalog cost — the displayed price on the model card (per 1M tokens, per image, per second of video, etc.) × the actual usage units.
- Upstream cost — what the upstream provider charged Kunavo for the specific call, denominated in credits where 1 credit = $0.005.
- Markup factor — typically
1.5(50% margin). For some China-provider models where the upstream wholesale is closer to the provider's official rate, the factor is reduced to1.2so we stay below official.
The max() ensures: (a) you never pay less than the advertised catalog price, and (b) we never lose money on a call where the upstream cost spikes unexpectedly.
Billing units by modality
| Modality | Unit | Granularity |
|---|---|---|
| Chat | per 1M input tokens + per 1M output tokens | Token-exact; reasoning tokens billed at output rate. |
| Image (t2i / edit) | per image | Per generated image; partial generations not charged. |
| Video | per video | Flat per-clip price, keyed by the resolution tier. |
Cached tokens
Chat models cache stable prompt prefixes. Cache reads bill well below the normal input rate — for the Claude family at 0.10×, for OpenAI and Gemini at 0.20×. Cache writes bill at the plain input rate; Kunavo does not pass through Anthropic's upstream write surcharge. The max() floor above is computed cache-aware, so the discount reaches you instead of being flattened by the catalog price.
See the Prompt caching guide for the full pricing table, how to enable cache_control, and how Kunavo's affinity routing keeps the cache warm.
Precision
All amounts in Kunavo are stored in micro_cents:
1 USD = 100,000,000 micro_cents1 cent = 1,000,000 micro_cents- Minimum resolvable charge:
0.0001 cent($0.000001). Practical chat calls often bill at this floor.
Dashboard display rounds to 6 decimals (USD) for small values and 2 decimals once it crosses cents. Internal accounting is exact.
Top-up
Fund your wallet at /app/billing via Stripe Checkout. Cards, Apple Pay, Google Pay, ACH, and Stripe's local methods all work.
Tier pricing
| Top-up | You get | Bonus |
|---|---|---|
| $10 | $10.00 | — |
| $100 | $110.00 | +$10 (10%) |
| $1,000 | $1,250.00 | +$250 (25%) |
| $5,000 | $7,000.00 | +$2,000 (40%) |
monthly_spend_cap per API key from /app/keys for hard spending limits on individual workloads.Webhook timing
After you complete Stripe Checkout, your balance updates via webhook. The webhook typically fires within 5–10 seconds of payment confirmation. For card payments this is near-instant; for async methods (ACH, SEPA) the deposit can take days to settle — but you'll see the order as pending the entire time.
The credit ledger
Every balance change is recorded in an append-only ledger:
| Type | Direction | When |
|---|---|---|
| topup | credit (+) | Stripe payment confirmed. |
| consume | debit (−) | API call billed at completion. |
| refund | credit (+) | Stripe refund or manual admin credit. |
| manual_adjust | credit (+/−) | Operator correction (e.g. incident refund). |
balance_after_micro_cents is stamped on each row, giving you a per-event snapshot. View the full history at /app/billing.
Usage logs
Every API call gets a row in usage_logs:
- Model, status (success / error), HTTP status code
- Input / output tokens, cached + cache-write tokens, image count, seconds, characters
upstream_cost_micro_cents— what Kunavo paid the upstreamcost_micro_cents— what you paid (after markup)- Latency, request IP, user agent, API key prefix
Visible at /app/usage with filters and per-call detail pages.
Failed calls — do they cost anything?
No. Kunavo only bills on status = success. If the upstream returns 4xx / 5xx, or our task times out, the call is recorded but the cost is $0. We absorb the upstream cost ourselves rather than passing it through.
Refunds
Refunds are case-by-case via support@kunavo.com. Common cases we refund:
- Outage on Kunavo's side that caused you to lose budget.
- Pricing bugs where you were overcharged vs the displayed catalog.
- Accidental double top-up via Stripe.
Refunds are issued as credit to your wallet by default; bank-account refunds via Stripe are also available on request.