Skip to main content

​
Billing

Faces uses a credit-based billing system. Chat completions are billed against your credit balance in real time. Compile quota is allocated per plan and shared across all your faces.

​
Check your balance

curl https://api.faces.sh/v1/billing/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
    "balance_usd": 12.45,
    "has_payment_method": true,
    "is_frozen": false
  }
}

​
Subscription plans

PlanPriceFace limitCompile quota
Free$0105,000 tokens (never resets)
Standard$X/mo10050,000 tokens / 30 days
Pro$X/mo1,0001,000,000 tokens / 30 days
Chat usage (token costs) is billed from your credit balance on all plans.

​
Get current subscription

curl https://api.faces.sh/v1/billing/subscription \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Upgrade or downgrade

# Start Stripe Checkout session
curl -X POST "https://api.faces.sh/v1/billing/checkout?plan=standard" \
  -H "Authorization: Bearer YOUR_API_KEY"
Returns a checkout_url to redirect the user to Stripe. After payment, the subscription is activated automatically.

​
Cancel subscription

curl -X POST https://api.faces.sh/v1/billing/subscription/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"
Cancels at the end of the current billing period. The account reverts to the Free plan.

​
Adding a payment method

Set up a saved card via Stripe Checkout: 
curl -X POST https://api.faces.sh/v1/billing/card-setup \
  -H "Authorization: Bearer YOUR_API_KEY"
Returns a checkout_url. After completing the setup flow, your card is saved for automatic top-ups.

​
Top up credits

​
Charge saved card

curl -X POST https://api.faces.sh/v1/billing/topup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd": 20.00}'
Requires a saved payment method. Minimum $1.00.

​
Manual / test payment

Pass a payment_ref to record a pre-authorized payment: 
curl -X POST https://api.faces.sh/v1/billing/topup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd": 20.00, "payment_ref": "pi_stripe_payment_intent_id"}'

​
Compile quota

Compile quota tracks tokens consumed during face compilation. It is separate from chat token usage. 
curl https://api.faces.sh/v1/billing/compile-quota \
  -H "Authorization: Bearer YOUR_API_KEY"
Returns per-account quota plus a breakdown by face showing tokens in graph, tokens used this period, and tokens used all-time. See Compile guide for full details on how quota works and what overflow billing does.

​
LLM pricing

curl https://api.faces.sh/v1/billing/llm-costs \
  -H "Authorization: Bearer YOUR_API_KEY"
Returns the current pricing table for all supported models, including per-million-token rates for standard models and per-hour rates for time-based services (e.g. audio transcription).

​
How chat costs are calculated

Each chat completion deducts from your credit balance: 
cost = (prompt_tokens / 1,000,000) × input_price
     + (completion_tokens / 1,000,000) × output_price
     × (1 + markup_rate)
The markup rate covers infrastructure costs. The exact rate is shown in the pricing table.

​
Credit account states

StateEffect
balance > 0Normal operation
balance = 0Chat requests return 402 Payment Required
is_frozen = trueAll requests return 402 regardless of balance