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.

本文件為英文版。如果你需要繁體中文版的快速接入指引，請看：繁體中文快速開始 — 從台灣調用 Claude API →

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:

user_cost = max(catalog_cost, upstream_cost × markup_factor)

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 to 1.2 so 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_cents
1 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, US bank transfer (ACH), 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.

Top-ups are priced in USD, and Stripe converts. The checkout page shows the amount in your own currency and settles it there — that is how Pix charges in reais and BLIK in złoty against a dollar price. What that does not cover is SEPA Direct Debit and BACS: those are not among the methods enabled on our account, so they never appear, and no currency setting changes it. Any card issued in those countries works normally, including a debit card drawn on a SEPA account. US customers get ACH as a genuine bank-debit option, on its own larger bonus tier.

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%)

Balance never expires. Top up once, drain it over months. You can also set a monthly spend limit per API key from /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.

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 delayed-notification methods such as ACH 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 upstream
cost_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.