bithuman-ai Self Hosting API

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