bithuman-ai Self Hosting API
The two routes a self-hosted or on-device runtime calls: check that its key is still live, and report the session time it served. See [Pricing](https://docs.bithuman.ai/pricing).
The two routes a self-hosted or on-device runtime calls: check that its key is still live, and report the session time it served. See [Pricing](https://docs.bithuman.ai/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-self-hosting-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 Self Hosting 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 Self-hosting 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: Self-hosting
description: 'The two routes a self-hosted or on-device runtime calls: check that its
key is still live, and report the session time it served. See
Pricing.'
paths:
/v1/auth/validate:
post:
operationId: validateSelfHostedKey
x-codeSamples:
- lang: shell
label: cURL
source: "curl -X POST https://api.bithuman.ai/v1/auth/validate \\\n -H \"Authorization: Bearer $BITHUMAN_API_SECRET\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"billing_type\": \"self-hosted-essence-2-model\"}'\n# → {\"user_id\": \"...\", \"key_id\": \"key_1a2b3c4d5e6f7a8b\"}\n"
summary: Live key check for a self-hosted runtime
description: 'The bitHuman SDKs, the CLI and the plugins call this for you when a
self-hosted session starts and while it runs; you call it only if you
build your own runtime. Deleting a key in the dashboard stops a running
self-hosted session at its next check.
A runtime treats the three answers differently:
| status | meaning | what a runtime should do |
|---|---|---|
| `200` | valid | serve |
| `401` | **definite**: unknown, revoked or disabled | stop |
| `503` | we cannot tell right now | retry, keep serving |
A `503` is never a statement about your key: keep serving and retry.'
tags:
- Self-hosting
security:
- bearerApiSecret: []
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
billing_type:
type: string
description: 'The self-hosted product this runtime serves. Always send
the key for the product you run.
'
example: self-hosted-essence-2-model
responses:
'200':
description: The key is valid.
content:
application/json:
schema:
type: object
properties:
user_id:
type: string
description: 'The account this key bills to. A response with no
`user_id` must be treated as a failure — an
identity-less "ok" cannot be billed to anybody.
'
key_id:
type: string
example: key_1a2b3c4d5e6f7a8b
'401':
description: Definite — unknown, revoked or disabled key.
content:
application/json:
schema:
$ref: '#/components/schemas/SelfHostError'
'429':
$ref: '#/components/responses/RateLimitedFailedAuth'
'503':
description: 'We cannot validate right now. Retry (a `Retry-After` header is
sent) and keep serving — this is not a statement about your key.
'
content:
application/json:
schema:
$ref: '#/components/schemas/SelfHostError'
servers:
- url: https://api.bithuman.ai
description: Production
/v1/meter/beats:
post:
operationId: postMeterBeat
x-codeSamples:
- lang: shell
label: cURL
source: "curl -X POST https://api.bithuman.ai/v1/meter/beats \\\n -H \"Authorization: Bearer $BITHUMAN_API_SECRET\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"session_id\":\"s-1\",\"install_id\":\"i-1\",\"seq\":1,\n \"served_s\":60,\"billing_type\":\"self-hosted-essence-2-model\"}'\n"
summary: Report usage from a self-hosted session
description: 'The bitHuman SDKs, the CLI and the plugins call this for you: a
self-hosted or on-device session reports its running time here, and
that is what bills it (Pricing).
You call it only if you build your own runtime.
A report covers the seconds the session ran, idle included, not frames
rendered. The product (`billing_type`) is fixed by the first report of a
session.
Read **only the status code**:
| status | meaning | what a runtime should do |
|---|---|---|
| `2xx` | the interval is recorded | count it as reported |
| `402` | balance depleted / account suspended | **keep rendering**, report it again later |
| `401` | definite bad key | stop |
| `503` | we cannot tell right now | retry |
A `402` never stops a running session; the next session is refused
until you top up. A retried report (same `session_id`, `install_id`
and `seq`) is never charged twice.'
tags:
- Self-hosting
security:
- bearerApiSecret: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- session_id
- seq
- served_s
properties:
session_id:
type: string
maxLength: 128
description: Stable id for the session being billed.
install_id:
type: string
maxLength: 128
description: Stable id for this installation.
seq:
type: integer
minimum: 1
description: Beat sequence number within the session.
served_s:
type: number
description: 'Seconds of session covered by this beat. Clamped
server-side; wall-clock, idle included.
'
billing_type:
type: string
description: 'The self-hosted product wire key. Always send the key
for the product you run.
'
example: self-hosted-essence-2-model
responses:
'200':
description: The interval is durably recorded. Advance the meter clock. Until 2026-10-19, a Free account's answer also carries `plan_notice` and the `X-Bithuman-Plan-Notice` header; show it as sent.
headers:
X-Bithuman-Plan-Notice:
schema:
type: string
description: 'The same text as `plan_notice`: "Free-plan API and SDK access ends on 2026-10-19. Upgrade at https://www.bithuman.ai/pricing to keep it.", or, for a Free account keeping access on top-up credits bought before 2026-09-27, the wording that says so.'
'400':
description: Malformed beat (`session_id` and a positive `seq` are required).
'401':
description: Definite — unknown, revoked or disabled key.
'402':
description: 'Balance depleted (`error.type` `insufficient_balance`, with a
`topup_url`) or account suspended (`account_suspended`). Do **not**
advance the meter clock; keep rendering.
'
content:
application/json:
schema:
$ref: '#/components/schemas/SelfHostError'
example:
accepted: false
error:
type: insufficient_balance
message: credit balance depleted; top up to continue metered service
topup_url: https://www.bithuman.ai/billing#credits
'403':
description: '`PLAN_REQUIRED` (`error.type` `plan_required`): from 2026-10-19, a
Free account''s API secret, with an `upgrade_url`; or a product your
plan does not include.
'
content:
application/json:
schema:
$ref: '#/components/schemas/SelfHostError'
'429':
$ref: '#/components/responses/RateLimitedFailedAuth'
'503':
description: We cannot record right now. Retry.
servers:
- url: https://api.bithuman.ai
description: Production
components:
schemas:
SelfHostError:
type: object
description: 'The error envelope the self-hosting routes return. `error.type` is the
machine-readable word a runtime switches on; `error.code`,
`error.httpStatus` and `error.message` are the platform envelope every
other endpoint uses. Both are present on purpose — the self-hosted
container''s key validator reads `type`, and the additive `code` means a
developer switching on `error.code` no longer gets `undefined` from
these routes.
'
properties:
error:
type: object
properties:
type:
type: string
example: missing_credentials
code:
type: string
example: MISSING_AUTH
httpStatus:
type: integer
example: 401
message:
type: string
upgrade_url:
type: string
description: On a `plan_required` refusal (403), where to choose a plan.
example: https://www.bithuman.ai/pricing
topup_url:
type: string
description: On an `insufficient_balance` refusal (402), where to top up credits.
example: https://www.bithuman.ai/billing#credits
responses:
RateLimitedFailedAuth:
description: 'Too many **failed** key validations from this network address — 30 per
minute. Only failures spend budget, so a runtime presenting a live key
never reaches this, however often it calls. It says nothing about
whether your key is valid: wait `Retry-After` seconds, retry, and read
the answer you get then. 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/SelfHostError'
example:
error:
type: rate_limited
message: too many failed validations
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