Billing API

Read a user's live credit balance and per-mode minute estimates, and understand how credits are consumed.

The credits model

bitHuman bills in credits. The free tier includes 99 credits per month (no credit card); paid plans start at $20/month. Some operations are one-time costs; live sessions bill per minute.

Action	Cost
Agent generation (one-time, per avatar)	250 credits
Dynamics generation (one-time, per avatar)	250 credits
Live session — Essence, self-hosted	1 credit/min
Live session — Essence, cloud	2 credits/min
Live session — Expression, self-hosted	2 credits/min
Live session — Expression, cloud	4 credits/min
Voice chat (managed agent, no avatar)	10 credits/min
Camera chat (managed agent, camera on)	30 credits/min

See the current pricing page for plan tiers and the TTS rate.

Check credit balance

GET /v2/credit-summaries — returns the live balance for a user, broken down by plan vs. topup credits, plus an estimate of how many minutes of each session type they can afford at current rates. Safe to call frequently (cached read-through, no side effects).

Query param	Type	Required	Default	Description
user_id	string	yes	—	User UUID to look up.
app	string	no	imaginex	App identifier for multi-app subscription support.
app_key	string	no	same as app	Explicit subscription key for collection-scoped apps.

curl "https://api.bithuman.ai/v2/credit-summaries?user_id=$USER_ID&app=imaginex" \
  -H "api-secret: $BITHUMAN_API_SECRET"

{
  "success": true,
  "data": {
    "user_id": "229be55d-1c1e-42b9-8517-a22c742668ef",
    "balance": 1842,
    "plan_credits": 99,
    "topup_credits": 1743,
    "is_enterprise": false,
    "minutes_estimate": {
      "voice_chat": 184,
      "camera_chat": 61,
      "essence_cloud": 921,
      "essence_self_hosted": 1842,
      "expression_cloud": 460,
      "expression_self_hosted": 921
    },
    "isEnterprisePlanUser": false
  }
}

Response fields

Field	Type	Notes
balance	number	Sum of plan + topup + reward credits. Can go negative down to -11 (grace window before suspension).
plan_credits	number	Remaining credits from the active subscription; resets at billing-period end.
topup_credits	number	Credits from one-time top-ups; do not reset.
is_enterprise	boolean	true for org-pooled (enterprise) billing.
isEnterprisePlanUser	boolean	Backward-compat alias for is_enterprise — prefer the snake_case field.
minutes_estimate	object	Floor-division of balance by each mode’s credits/min rate.

The minutes_estimate keys map to the two avatar models and the managed conversational agent:

Key	Meaning	Rate
essence_self_hosted	Essence on your hardware	balance ÷ 1
essence_cloud	Essence on bitHuman cloud	balance ÷ 2
expression_self_hosted	Expression on your hardware	balance ÷ 2
expression_cloud	Expression on bitHuman cloud	balance ÷ 4
voice_chat	Managed cloud agent, no avatar	balance ÷ 10
camera_chat	Managed cloud agent, camera on	balance ÷ 30

Notes

• Balance is the source of truth, not the sum of activity rows. The activity ledger is a best-effort audit trail; sub-cent rounding and historical drift mean it can differ from balance by small amounts. Quote balance to users.
• The minute estimates use floor-division on the integer balance and treat the suspension grace window (-11..0) as zero minutes.
• For suspension-status UI, compare balance to the documented threshold -11 rather than relying on a separate flag.
• Check your balance before heavy operations (250-credit generation or dynamics) to avoid wasted calls that fail with 402.

Errors

HTTP	Code	When
401	UNAUTHORIZED / MISSING_AUTH	Missing or invalid api-secret.
402	INSUFFICIENT_BALANCE	Balance too low for the requested operation.
404	USER_NOT_FOUND	user_id does not exist.
500	INTERNAL_ERROR	Upstream database error.

See Rate limits for tier caps and the full error reference.