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. |
Long prompts bill at the vendor's long-context tier. On GPT-5.5, GPT-5.6 Sol, Terra and Luna, and GPT-6 Astra, a prompt over 272K input tokens bills the whole request at 2× input — cache reads and writes too — and 1.5× output, the tier OpenAI publishes; Gemini 3.1 Pro does the same past 200K. Claude has no long-context surcharge: its 1M context bills at the standard rate.
Cached tokens
Chat models cache stable prompt prefixes. Cache reads bill well below the normal input rate — 0.10× on Claude, OpenAI and Gemini alike. Cache writes bill at 1.25× input on every Claude model, 1-hour-TTL writes included (below Anthropic's 2×), and on GPT-5.6 Sol, Terra and Luna, and GPT-6 Astra; on every other model they bill at the plain input rate. Every class carries the model's own discount, so its cache prices sit at the same discount off the vendor's list as its input and output. 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 (Visa, Mastercard, Amex, JCB, UnionPay), Apple Pay, Link, Cash App Pay, Klarna, Amazon Pay, Alipay and WeChat Pay. Country-gated rails appear for the buyer's own market — Pix in Brazil, Bancontact in Belgium, BLIK in Poland, EPS in Austria, MB WAY in Portugal.
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%) |
/app/keys for a hard ceiling on an individual workload: once that key's spend for the calendar month would pass the figure you set, its calls are refused with a 402 insufficient_quota and nothing is charged. Your other keys keep working. The same screen takes an IP allowlist per key — calls from anywhere else get a 403.Auto-recharge
Optional. Save a card once under /app/billing and set three numbers: the balance below which to top up, the amount to add each time, and a monthly cap. From then on the wallet refills itself — within seconds of a settlement that takes the balance under your threshold, and, if a request is refused for balance in the meantime, before that request is answered — so an unattended agent is not stopped by a 402.
| Setting | Range | Notes |
|---|---|---|
| Trigger below | $5 – $1,000 | Set it above your largest single request. |
| Amount each time | $10 – $1,000, whole dollars | $100 and $1,000 carry the same bonus as a manual top-up; other amounts carry none. |
| Monthly cap | amount – $20,000 | Counts what you are charged each calendar month, bonus excluded. |
KUNAVO* AUTOTOPUP.While a top-up is in flight, a refused request gets a 402 with Retry-After: 3; every other refusal says what to do next. Turn it off or change the numbers at any time on the same page.
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; a method that only confirms asynchronously can take days to settle. Those orders show as processing until the funds land, and the settlement webhook credits the wallet then — you do not need to pay again, and nothing expires underneath you. An order that is never completed shows pending and our cleanup job relabels it expired after 24 hours; that label is cosmetic and does not cancel anything.
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.