bithuman-ai Account API
Identity, plan, credits, and pricing.
Identity, plan, credits, and pricing.
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-account-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 Account 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 Account 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: Account
description: Identity, plan, credits, and pricing.
paths:
/v1/me:
get:
operationId: getMe
x-codeSamples:
- lang: shell
label: cURL
source: "curl https://api.bithuman.ai/v1/me \\\n -H \"api-secret: $BITHUMAN_API_SECRET\"\n"
summary: Get current account
description: The canonical account preflight — returns your identity, plan, and live credit balance in one call. Use it to show "who am I / how many credits" and to gate features before a billable call.
tags:
- Account
responses:
'200':
description: Account retrieved
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
user_id:
type: string
email:
type: string
plan:
type: string
example: pro
plan_code:
type: string
example: membership_pro
credit_balance:
type: integer
example: 1240
description: Total spendable credits = plan + topup + reward.
plan_credits_remaining:
type: integer
example: 1000
topup_credits_remaining:
type: integer
example: 240
account_status:
type: string
example: active
upgrade_url:
type: string
pricing_url:
type: string
status:
type: string
example: success
status_code:
type: integer
example: 200
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimitedByAddress'
servers:
- url: https://api.bithuman.ai
description: Production
/v1/pricing:
get:
operationId: getPricing
x-codeSamples:
- lang: shell
label: cURL
source: "curl https://api.bithuman.ai/v1/pricing \\\n -H \"api-secret: $BITHUMAN_API_SECRET\"\n"
summary: Get credit pricing
description: Machine-readable credit pricing for billable operations, so you can estimate cost before a call. Authoritative charges are always enforced server-side at request time. For forward per-minute realtime estimates based on your current balance, see `GET /v2/credit-summaries` (`minutes_estimate`).
tags:
- Account
responses:
'200':
description: Pricing retrieved
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
unit:
type: string
example: credits
agent_generation:
type: object
description: Agent creation is priced **per model** — read `by_model` (there is no flat rate). `expression-2` costs 2000 credits; the Essence 2 family costs 500 (`essence-2` is the combined Essence 2 creation — one 500-credit charge covers both models); the v1 families cost 250. `auto` charges the routed model's rate (500 for `essence-2`, 2000 for `expression-2`). Post-generation adds via `POST /v1/agent/{code}/models` charge the same per-model rates (adding `expression-1` is free).
properties:
unit:
type: string
example: credits
by_model:
type: object
additionalProperties:
type: integer
description: One-time creation cost per canonical `model` value accepted by `POST /v1/agent/generate`. `essence-2-quality` returns a `400`.
example:
essence-1: 250
expression-1: 250
expression-2: 2000
essence-2: 500
auto: 2000
note:
type: string
talking_video:
type: object
properties:
unit:
type: string
example: credits_per_minute
billing:
type: string
example: ceil(minutes) * rate, minimum 1 minute
rates:
type: object
additionalProperties:
type: integer
example:
essence-1: 2
expression-1: 4
expression-2: 4
essence-2: 4
dynamics_generation:
type: object
properties:
flat:
type: integer
example: 250
note:
type: string
notes:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
servers:
- url: https://api.bithuman.ai
description: Production
components:
responses:
RateLimitedByAddress:
description: 'Too many requests from this network address. These routes carry their
own credential and are checked by the service behind them, so there is
no account to meter at the edge — they get one flat limit per
address (120 requests/minute) instead of the per-plan cost tiers, and
no `X-RateLimit-*` headers. Wait `Retry-After` seconds and retry. See
[Rate limits](https://docs.bithuman.ai/api/rate-limits).
'
headers:
Retry-After:
schema:
type: integer
description: Seconds to wait before retrying.
example: 1
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: RATE_LIMITED
message: Too many requests from this address. Retry in ~1s.
httpStatus: 429
status: error
status_code: 429
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
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