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

PlanPriceFacesOAuth routing
Free$0Unlimited—
Connect$17/moUnlimitedOpenAI (chat + compile)
On the Free plan, all inference (chat and compile) is billed per-token from your credit balance. On the Connect plan, you link your OpenAI account via OAuth. All inference — both chat and compile interviews — routes through your ChatGPT subscription at no additional cost. If OAuth is unavailable (e.g., you hit OpenAI’s limits), requests fall back to your credit balance at the same per-token rates as the Free plan. See OAuth connections for details.

​
Get current subscription

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

​
Subscribe to Connect

curl -X POST "https://api.faces.sh/v1/billing/checkout?plan=connect" \
  -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).

​
Usage history

curl https://api.faces.sh/v1/billing/usage \
  -H "Authorization: Bearer YOUR_API_KEY"
Returns a breakdown of token usage and costs. Supports query parameters:
  • start_date / end_date — filter by date range
  • group_by — group results by llm_model, api_key_id, or model_username (face alias)

​
Invoices

curl https://api.faces.sh/v1/billing/invoices \
  -H "Authorization: Bearer YOUR_API_KEY"
Returns a list of top-up transactions with amounts and Stripe receipt URLs.

​
Compile overflow

Allow compilation to continue past the quota limit, billing excess tokens to your credit balance: 
curl -X PATCH https://api.faces.sh/v1/billing/compile-overflow \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allow_overflow": true}'
When enabled, compilation continues past quota using credits. When disabled, compilation stops at the quota limit.

​
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

​
Compile thread billing errors

When starting or continuing an interview thread, a 402 is returned if no payment source is available. The response body includes structured fields to help the UI display the right action: 
{
  "detail": {
    "message": "Connect your OpenAI account, or add credits to start an interview.",
    "error_code": "compile_payment_required",
    "needs_oauth": true,
    "needs_credits": true,
    "plan": "connect"
  }
}
FieldMeaning
needs_oauthUser should link their OpenAI account (Connect plan only)
needs_creditsUser should top up their credit balance
planThe user’s current plan
A 502 is returned if the upstream LLM provider fails. This replaces the previous behavior where LLM failures were silently returned as a fake assistant message with status 200.