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 range from $20/month (Creator) to $999/month (Enterprise), plus contact-sales Custom for on-prem / volume. Top-up credits are $1 = 100 credits and never expire. Some operations are one-time costs; live sessions bill per minute.

Action	Cost
Agent generation — v1 models (`essence-1`, `expression-1`)	250 credits (one-time, per avatar)
Agent generation — Essence 2 (`essence-2` combined; Max included)	500 credits (one-time, per avatar)
Agent generation — Expression 2 (`expression-2`)	2000 credits (one-time, per avatar)
Agent generation — `auto`	The routed model’s rate (500 or 2000)
Add a model to an existing agent	Same per-model rates (250 / 500 / 2000); adding `expression-1` is free (instant enablement, no training)
Dynamics generation (one-time, per avatar)	250 credits
Book creation (one-time, per book)	250 credits
Talking video — Essence 1	2 credits/min (rounded up)
Talking video — Expression 1, Expression 2, Essence 2	4 credits/min (rounded up)
Talking video — Essence 2 Max	8 credits/min (rounded up)
Live session — Essence 1, self-hosted	1 credit/min
Live session — Essence 1, cloud	2 credits/min
Live session — Expression 1 / Expression 2 / Essence 2, self-hosted	2 credits/min
Live session — Expression 1 / Expression 2 / Essence 2, cloud	4 credits/min
Live session — Essence 2 Max, self-hosted	4 credits/min
Live session — Essence 2 Max, cloud	8 credits/min
Voice chat (managed agent, no avatar)	10 credits/min
Camera chat (managed agent, camera on)	30 credits/min

See the Pricing guide for the full plan ladder (Free, Creator, Pro, Business, Enterprise, Custom) and annual pricing.

Account status

GET /v1/me — your identity, plan, and current credit balance in one call. Handy as a pre-flight check (it’s what the CLI uses) and to look up your user_id for the account endpoints.

curl https://api.bithuman.ai/v1/me -H "api-secret: $BITHUMAN_API_SECRET"

{
  "data": {
    "user_id": "3f9a…-uuid",
    "email": "user@example.com",
    "plan": "pro",
    "plan_code": "membership_pro",
    "credit_balance": 1240,
    "plan_credits_remaining": 1000,
    "topup_credits_remaining": 240,
    "account_status": "active"
  },
  "status": "success",
  "status_code": 200
}

Read-only, no billing side effects. credit_balance is the sum of your plan and top-up credits. Use user_id in the /v2/{user_id}/… account endpoints (API keys, Runtime sessions, Providers).

Get the pricing schedule

GET /v1/pricing — the machine-readable credit schedule, so you can estimate cost before a billable call. Agent creation is priced per model — read agent_generation.by_model (there is no flat creation rate):

curl https://api.bithuman.ai/v1/pricing \
  -H "api-secret: $BITHUMAN_API_SECRET"

{
  "success": true,
  "data": {
    "unit": "credits",
    "agent_generation": {
      "unit": "credits",
      "by_model": {
        "essence-1": 250,
        "expression-1": 250,
        "essence-2-max": 500,
        "expression-2": 2000,
        "essence-2": 500,
        "auto": 2000
      },
      "note": "One-time charge per agent created via POST /v1/agent/generate, PER MODEL …"
    },
    "talking_video": {
      "unit": "credits_per_minute",
      "billing": "ceil(minutes) * rate, minimum 1 minute",
      "rates": { "essence-1": 2, "expression-1": 4, "essence-2": 4, "essence-2-max": 8, "expression-2": 4 }
    },
    "dynamics_generation": { "flat": 250, "note": "…" },
    "notes": "Authoritative charges are enforced server-side at request time. …"
  }
}

by_model keys are the canonical model values POST /v1/agent/generate accepts — the premium model is keyed essence-2-max (8 credits/min). The pre-rename essence-2-quality spelling is no longer accepted (removed 2026-07-29); use essence-2-max. essence-2 is the combined Essence 2 creation (one 500-credit charge covers both models) and auto classifies and routes, charging the routed model’s rate — 500 for essence-2, 2000 for expression-2 (the auto entry in by_model shows the worst case). Post-generation model adds charge the same per-model rates (adding expression-1 is free). Authoritative charges are always enforced server-side — treat this endpoint as an estimate and reference.

Check credit balance

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

The endpoint always returns the caller’s own balance; there is no way to look up another user. (A user_id query param is silently ignored — it does not switch accounts and never returns 404.)

Query param	Type	Required	Default	Description
`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.

# Your own balance — just the key:
curl https://api.bithuman.ai/v2/credit-summaries \
  -H "api-secret: $BITHUMAN_API_SECRET"

{
  "success": true,
  "data": {
    "user_id": "229be55d-1c1e-42b9-8517-a22c742668ef",
    "balance": 1842.0,
    "plan_credits": 99.0,
    "topup_credits": 1743.0,
    "is_enterprise": false,
    "minutes_estimate": {
      "essence_2_cloud": 460,
      "essence_2_self_hosted": 921,
      "essence_2_max_cloud": 230,
      "essence_2_max_self_hosted": 460,
      "expression_2_cloud": 460,
      "expression_2_self_hosted": 921,
      "essence_1_cloud": 921,
      "essence_1_self_hosted": 1842,
      "expression_1_cloud": 460,
      "expression_1_self_hosted": 921,
      "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 (float)	Sum of plan + topup + reward credits, returned as a float (e.g. `5910592.0`). 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.

There is one minutes_estimate key per serving mode. The rate differs by model — read the key for the model you actually run:

Key	Meaning	Rate
`essence_2_cloud`	Essence 2 on bitHuman cloud	balance ÷ 4
`essence_2_self_hosted`	Essence 2 on your hardware	balance ÷ 2
`essence_2_max_cloud`	Essence 2 Max on bitHuman cloud	balance ÷ 8
`essence_2_max_self_hosted`	Essence 2 Max on your hardware	balance ÷ 4
`expression_2_cloud`	Expression 2 on bitHuman cloud	balance ÷ 4
`expression_2_self_hosted`	Expression 2 on your hardware	balance ÷ 2
`essence_1_cloud`	Essence 1 on bitHuman cloud	balance ÷ 2
`essence_1_self_hosted`	Essence 1 on your hardware	balance ÷ 1
`expression_1_cloud`	Expression 1 on bitHuman cloud	balance ÷ 4
`expression_1_self_hosted`	Expression 1 on your hardware	balance ÷ 2
`voice_chat`	Managed cloud agent, no avatar	balance ÷ 10
`camera_chat`	Managed cloud agent, camera on	balance ÷ 30

:::caution[essence_* and expression_* without a version are Essence 1 and Expression 1] essence_cloud, essence_self_hosted, expression_cloud and expression_self_hosted predate the second-generation models and are aliases of the essence_1_* / expression_1_* rows above. They are not the Essence 2 rate. If you serve Essence 2 or Essence 2 Max and read essence_cloud, you will over-estimate your remaining minutes by 2x and 4x respectively. Use the model-specific key, or compute from the serving rates. :::

Estimates are advisory. The authoritative charge is always computed server-side at request time from the live rate schedule.

Usage history

GET /v1/usage returns your account’s metered events, newest first. Paginate with limit (default 50, max 200) and offset; narrow with start / end (ISO-8601 timestamps) and agent_code.

Note The Python examples below use requests, which is not in the standard library — pip install requests first, or use curl / urllib instead.

import requests

resp = requests.get(
    "https://api.bithuman.ai/v1/usage",
    headers={"api-secret": "YOUR_API_SECRET"},
    params={"limit": 50, "start": "2026-06-01T00:00:00Z"},
).json()

for ev in resp["data"]:
    print(ev["created_at"], ev["pricing_code"], ev["credits_change"])
print(resp["pagination"])   # {limit, offset, total, has_more}

Each row carries activity_type, pricing_code, agent_code, created_at, and credits_change — the signed credit delta (usage events are recorded as positive credits consumed). This is an audit trail; for an authoritative balance use GET /v2/credit-summaries above.

Note — a credit_refund_… row does not mean something failed. Talking-video renders charge the 120-second cap up front and then refund the overcharge, so every render — successful ones included — writes a matched pair. A real 6-second essence-2 render looks like this:
usage_talking_video_essence_2_by_api                 8
credit_refund_usage_talking_video_essence_2_by_api   4      ← true-up, not a failure
Net 4 credits, which is the published rate. Only a refund equal to the full up-front charge means the render failed. Reconcile refunds against their charge rather than alerting on the credit_refund_ prefix.

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 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 (agent generation at 250–2000 credits per model, or dynamics at 250) to avoid wasted calls that fail with 402 — GET /v1/pricing gives the exact per-model rates.

Errors

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

See Rate limits for the plan-tiered request limits and the full error reference.

Next steps

Pricing & credits — how credits and per-minute rates work
Rate limits — quotas and limits per endpoint