bithuman-ai Account API

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