AI Studio
Create
ImageVideoCanvasExplore
Experts
Overview
DocsAPI KeysDiscord
Documentation
Documentation
IntroductionWhy Router9

Studio

Using Studio

For Developers

Quick StartInstall MCP Server

Integrations

Token Plan

Plan ManagementPer-Key Harness ManagementBilling & PlansCredits & UsageAudit LogsSecurity

API Reference

Token Plan

Credits & Usage

How the per-period credit allowance meters usage and pay-as-you-go overage

What a Credit Is

Every Router9 plan includes a credit allowance for each billing period. Credits are a single, normalized unit of usage that lets one flat-rate plan cover hundreds of models fairly — a request to an expensive model draws down more credits than the same number of tokens on a cheap one.

A credit is derived from USD at a fixed rate:

1 credit  = $0.0001
$1        = 10,000 credits

Each request consumes credits proportional to its per-model token cost — the same cost used internally for metering. You never have to reason about per-token prices: just watch your credit balance.

Quota by Plan

Each plan grants a fresh credit quota at the start of every billing period. The period is your own plan's, not a shared calendar month: it starts on the day your plan began — the day you subscribed on a paid plan, the day you signed up on Free — and renews on that same day each month.

PlanCredits per period≈ USD value
Free10,000~$1
Pro500,000~$50
Max1,500,000~$150

The quota is shared across everything the account does — Studio generations and every request made with any of its API keys, including Skill calls. Audio, vision, and image-generation Skills consume from this same allowance — see Tool Usage & Credits.

Credits Reset Each Period

Unused credits do not roll over. At the end of each billing period the allowance resets to the plan's quota, whatever was left of the last one.

Only a subscription that already existed when this rule changed is treated differently: until the end of the calendar month in which the change took effect, it keeps the old rollover (60% of unused credits on Pro, 80% on Max, capped at 2× the quota). After that month it resets each period like every other plan. For such an account the headers and API fields below report the rolled-over amount; for everyone else they report 0.

How Credits Are Consumed

request → resolved model → per-model token cost (USD) → credits = cost ÷ $0.0001

Because credits track real per-model cost:

  • A long chat completion on a frontier model consumes more credits than a short one on a small model.
  • Input, output, and multimodal tokens all count toward the cost.
  • The credit charge is applied after the response completes (the exact output token count is only known then), so your remaining balance updates once the request finishes.

Pay-As-You-Go Overage

When your effective allowance for the period is exhausted, Router9 does not immediately block your harness. Instead:

  1. Further usage is drawn from your account's prepaid balance (a USD pool for pay-as-you-go overage).
  2. Requests are rejected with 429 only when both the effective allowance and the prepaid balance are exhausted.
  3. Top up the prepaid balance at any time from Studio's Billing page (/settings/billing) to keep running past your allowance before the next billing period.

This means you can run a flat-rate plan with confidence, and only pay more in the periods you genuinely exceed your allowance.

Credit Headers

Token endpoints (/v1/chat/completions) return your live credit state on every response:

X-Credits-Limit: 500000
X-Credits-Rollover: 0
X-Credits-Remaining: 327320
  • X-Credits-Limit — your effective allowance for the period
  • X-Credits-Rollover — credits carried in from the previous period; 0 unless the account is still finishing a pre-change cycle (see above)
  • X-Credits-Remaining — credits left in the current period (before overage)

429 — Credits Exhausted

When both the effective allowance and the prepaid balance are gone:

HTTP/1.1 429 Too Many Requests
X-Credits-Reset: 2026-07-01T00:00:00.000Z

X-Credits-Reset — when the allowance next resets, the end of your billing period — is sent only on this response.

{
  "error": "Monthly credit quota exhausted. Resets at 2026-07-01T00:00:00.000Z. Upgrade your plan or top up credits to continue."
}

To resolve it, either top up your balance (immediate) or upgrade your plan for a larger allowance.

Free plan: videos and speech that cost more than you have left

On the free plan a video or a piece of speech is priced before it runs. If it costs more credits than you have left this month, the request is refused with 402 and the code upgrade_required, and nothing is made or charged:

{
  "error": {
    "code": "upgrade_required",
    "type": "insufficient_quota",
    "message": "This needs more credits than your free plan has left. Upgrade to continue.",
    "estimated_credits": 112500,
    "remaining_credits": 10000,
    "upgrade_url": "/checkout?plan=PRO"
  }
}

If a call still goes over what you have (a picture whose cost was not known beforehand, say), it is made and kept, but locked: you can see that it exists in your library, with a blurred cover, and it is not delivered until you subscribe. Subscribing unlocks every locked work at once. A locked work is kept for 14 days.

Monitoring Credits

Track your credit usage on Studio's Usage page (/settings/usage). It shows:

  • A Credit Allowance bar — credits used vs. your effective allowance
  • Remaining credits and the reset date
  • Any prepaid (overage) credits consumed this period

You can also query it programmatically via GET /v1/billing/credits.

API

GET /v1/billing/credits returns the current period's credit state:

{
  "success": true,
  "data": {
    "plan": "PRO",
    "allowance": 500000,
    "rolledOverCredits": 0,
    "effectiveAllowance": 500000,
    "planCreditsUsed": 12680,
    "paidCreditsUsed": 0,
    "remaining": 487320,
    "paidBalanceCredits": 250000,
    "periodEnd": "2026-07-01T00:00:00.000Z",
    "rolloverEligible": false
  }
}
FieldDescription
planCurrent plan tier
allowanceThe plan's base credit quota per period
rolledOverCreditsCredits carried in from the previous period — 0 unless rolloverEligible
effectiveAllowanceYour usable quota this period — the base quota plus any carried-in or bonus credits
planCreditsUsedCredits consumed against the effective allowance this period
paidCreditsUsedOverage credits paid from the prepaid balance this period
remainingEffective allowance credits left before overage kicks in
paidBalanceCreditsPrepaid balance, expressed in credits
periodEndWhen the allowance resets — the end of your billing period
rolloverEligibletrue only while the account is finishing a cycle that began before rollover was removed

FAQs

Do credits roll over to the next period? No. The allowance resets to your plan's quota at the start of every billing period. The only exception is a subscription still finishing a cycle that began before rollover was removed — see Credits Reset Each Period.

What's the difference between credits and rate limits? The 4-hour rate limit is a short-window burst guard (requests per 4 hours). Credits govern your total volume for the period, weighted by how expensive each model is. Both apply independently.

How do I get more credits? Top up your prepaid balance from Studio's Billing page (/settings/billing) for immediate pay-as-you-go headroom, or upgrade to a higher plan for a larger allowance. See Billing & Plans.

Billing & Plans

Subscription tiers, pricing, and billing management

Audit Logs

Track and analyze every request made with a harness key

On this page

What a Credit IsQuota by PlanCredits Reset Each PeriodHow Credits Are ConsumedPay-As-You-Go OverageCredit Headers429 — Credits ExhaustedFree plan: videos and speech that cost more than you have leftMonitoring CreditsAPIFAQs