bithuman-ai Billing API
Check credit balance, plan details, and usage history.
Check credit balance, plan details, and usage history.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/bithuman-ai:bithuman-ai-billing-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Bithuman Ai Billing API
version: '1.0'
contact:
name: bitHuman Support
url: https://www.bithuman.ai/discord
x-logo:
url: https://docs.bithuman.ai/bithuman-mark.png
description: 'Operations tagged Billing across 2 of this provider''s published API definitions: openapi.yaml, bithuman-ai-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.bithuman.ai
description: Production
security:
- apiSecret: []
tags:
- name: Billing
description: Check credit balance, plan details, and usage history.
paths:
/v2/credit-summaries:
get:
operationId: getCreditSummaries
x-codeSamples:
- lang: shell
label: cURL
source: "curl https://api.bithuman.ai/v2/credit-summaries \\\n -H \"api-secret: $BITHUMAN_API_SECRET\"\n"
summary: Check credit balance
description: 'Returns the current credit balance, plan details, and estimated minutes
remaining for each usage type. Always scoped to the **authenticated
account** (the owner of the `api-secret`) — there is no way to look up
another user.'
tags:
- Billing
security:
- apiSecret: []
responses:
'200':
description: Credit balance retrieved
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
user_id:
type: string
description: The authenticated account's UUID.
balance:
type: number
format: float
description: Sum of plan + topup + reward credits, returned as a float (e.g. 1240.0).
example: 1240.0
plan_credits:
type: number
format: float
topup_credits:
type: number
format: float
minutes_estimate:
type: object
description: 'Advisory forward runway: balance divided by each serving mode''s credits/min rate. One key per model and hosting mode (essence_2_cloud, essence_2_self_hosted, expression_2_cloud, expression_2_self_hosted, essence_1_cloud, essence_1_self_hosted, expression_1_cloud, expression_1_self_hosted), plus voice_chat and camera_chat for managed agents. The unversioned essence_* / expression_* keys are retained aliases for the FIRST-generation models - they are NOT the Essence 2 rate.'
additionalProperties:
type: integer
is_enterprise:
type: boolean
isEnterprisePlanUser:
type: boolean
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
servers:
- url: https://api.bithuman.ai
description: Production
/v1/usage:
get:
operationId: getUsage
x-codeSamples:
- lang: shell
label: cURL
source: "curl \"https://api.bithuman.ai/v1/usage?limit=50&start=2026-06-01T00:00:00Z\" \\\n -H \"api-secret: $BITHUMAN_API_SECRET\"\n"
summary: Usage history
description: 'Return your account''s usage / activity history, newest first. Each row
is a metered event. `credits_change` is the signed credit delta — usage
events are recorded as **positive** credits consumed.'
tags:
- Billing
security:
- apiSecret: []
parameters:
- name: limit
in: query
description: Page size (1–200).
schema:
type: integer
default: 50
minimum: 1
maximum: 200
- name: offset
in: query
schema:
type: integer
default: 0
minimum: 0
- name: start
in: query
description: ISO-8601 timestamp; only return events at/after this time.
schema:
type: string
format: date-time
- name: end
in: query
description: ISO-8601 timestamp; only return events at/before this time.
schema:
type: string
format: date-time
- name: agent_code
in: query
description: Only return events for this agent.
schema:
type: string
responses:
'200':
description: A page of usage events
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: array
items:
$ref: '#/components/schemas/UsageEvent'
pagination:
$ref: '#/components/schemas/Pagination'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
servers:
- url: https://api.bithuman.ai
description: Production
components:
responses:
Unauthorized:
description: 'Authentication failed. `UNAUTHORIZED` when the `api-secret` header is
present but invalid; `MISSING_AUTH` when it is absent. The HTTP status
equals `status_code` (401).
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: UNAUTHORIZED
message: Invalid API secret
httpStatus: 401
status: error
status_code: 401
RateLimited:
description: 'Too many requests. The limiter is **per account** — every API secret on
the account draws from one bucket — and **per cost tier**, so a burst of
reads never uses up your generate budget. Your plan sets the number for
each tier; the matrix, the tier each route belongs to and a retry
recipe are on
[Rate limits](https://docs.bithuman.ai/api/rate-limits).
Wait `Retry-After` seconds and retry. The `X-RateLimit-*` headers let a
client slow down *before* it gets here, but header coverage is uneven
across routes — read them defensively and fall back to exponential
backoff when they are absent.
On a route that can also be called without an API secret, an anonymous
call is metered per network address instead: same body, same
`Retry-After`, no `X-RateLimit-*`.
'
headers:
Retry-After:
schema:
type: integer
description: Seconds to wait before retrying.
example: 1
X-RateLimit-Limit:
schema:
type: integer
description: Requests per minute your plan allows on this request's cost tier.
example: 30
X-RateLimit-Remaining:
schema:
type: integer
description: Whole requests left in the bucket right now.
example: 0
X-RateLimit-Reset:
schema:
type: integer
description: Unix time at which the bucket is fully refilled.
example: 1758380460
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: RATE_LIMITED
message: Too many generate requests for this api-secret. Retry in ~1s.
httpStatus: 429
status: error
status_code: 429
schemas:
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: UNAUTHORIZED
message:
type: string
example: Invalid API secret
httpStatus:
type: integer
example: 401
upgrade_url:
type: string
description: 'On `PLAN_REQUIRED`, `AGENT_LIMIT_REACHED` and `CONCURRENCY_LIMIT_REACHED` (403): where to choose a plan. Send the user there instead of retrying. See [Plan and credit refusals](https://docs.bithuman.ai/api/errors#plan-and-credit-refusals).'
example: https://www.bithuman.ai/pricing
topup_url:
type: string
description: 'On `INSUFFICIENT_BALANCE` (402): where to top up credits.'
example: https://www.bithuman.ai/billing#credits
details:
type: object
description: Code-specific fields. `CONCURRENCY_LIMIT_REACHED` sends `tier`, `cap`, `active` and `upgrade_url`.
additionalProperties: true
status:
type: string
example: error
status_code:
type: integer
example: 401
UsageEvent:
type: object
properties:
id:
type: string
format: uuid
activity_type:
type: string
example: bithuman-serve
pricing_code:
type: string
example: usage_essence_model_self_hosted
app:
type: string
example: my-app
agent_code:
type:
- string
- 'null'
credits_change:
type: number
description: Signed credit delta; usage events are positive credits consumed.
example: 1
frames_rendered:
type:
- integer
- 'null'
room_name:
type:
- string
- 'null'
start_time:
type:
- string
- 'null'
format: date-time
end_time:
type:
- string
- 'null'
format: date-time
created_at:
type: string
format: date-time
Pagination:
type: object
properties:
limit:
type: integer
example: 20
offset:
type: integer
example: 0
total:
type: integer
description: Total matching rows across all pages.
example: 137
has_more:
type: boolean
example: true
securitySchemes:
apiSecret:
type: apiKey
name: api-secret
in: header
description: 'Your bitHuman API secret. Get one at
[www.bithuman.ai/developer/api-keys](https://www.bithuman.ai/developer/api-keys).
'
bearerApiSecret:
type: http
scheme: bearer
description: 'The same API secret, sent as `Authorization: Bearer <api-secret>`. Self-
hosted runtimes send it this way; the classic `api-secret` header works
on the same routes.
'
x-refined-from:
- openapi.yaml
- bithuman-ai-openapi.yaml
x-tagGroups:
- name: Get started
tags:
- overview
- quickstart
- auth-guide
- models
- pricing
- name: Core concepts
tags:
- avatars-imx
- audio-streaming
- agent-lifecycle
- name: SDKs
tags:
- sdk-python
- sdk-swift
- cli
- name: Guides
tags:
- local-mode
- building-avatars
- name: Deployment
tags:
- deploy-livekit
- deploy-self-hosted
- deploy-embed
- name: API reference
tags:
- Authentication
- Agent Generation
- Agent Management
- Agent Context
- Files
- Dynamics
- Embedding
- Video
- Billing
- Account
- Self-hosting
- API secrets
- Providers
- Runtime sessions
- Knowledge
- Realtime
- Status
- Webhooks
- name: Resources
tags:
- community
- changelog
- support