bithuman-ai Embedding API

openapi: 3.2.0
info:
  title: Bithuman Ai Embedding 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 Embedding 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: Embedding
  description: Mint short-lived tokens for website avatar embeds.
paths:
  /v1/embed-tokens/request:
    post:
      operationId: requestEmbedToken
      x-codeSamples:
      - lang: shell
        label: cURL
        source: "curl -X POST https://api.bithuman.ai/v1/embed-tokens/request \\\n  -H \"api-secret: $BITHUMAN_API_SECRET\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\"agent_id\": \"A23WJF0199\", \"fingerprint\": \"<device-fingerprint>\"}'\n# → data.token is a 1-hour JWT for the embed widget\n"
      summary: Generate embed token
      description: Generate a JWT token for embedding an avatar on a website. Use this from your backend — never expose your API secret in frontend code.
      tags:
      - Embedding
      security:
      - apiSecret: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - agent_id
              - fingerprint
              properties:
                agent_id:
                  type: string
                  description: Agent code (e.g. A23WJF0199)
                  example: A23WJF0199
                fingerprint:
                  type: string
                  description: Stable per-device hex string used for session tracking and per-visitor rate limiting. Required.
                  example: <device-fingerprint>
                model:
                  type: string
                  description: 'Optional. Request a specific avatar model for the embed session — a model name (`essence-1`, `expression-1`, `essence-2`, `expression-2`) or a force-tier slug that pins one serving tier (`expression-2-gpu/-cpu/-apple`, `essence-2-gpu/-apple/-cpu`; the older `-ane` spelling of the Apple tier stays accepted). This is the **early artifact gate**: if the requested model folds onto the `expression-2` / `essence-2` families and the agent''s trained per-identity model hasn''t been generated yet, the request is rejected `409 MODEL_NOT_GENERATED` instead of failing later at session dispatch. Unknown values return `400 VALIDATION_ERROR` listing the accepted names. Omitted → the agent''s own default model.'
                  example: expression-2
      responses:
        '200':
          description: Token generated. The returned `token` is a JWT (HS256-signed) with a 1-hour TTL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  status_code:
                    type: integer
                    example: 200
                  data:
                    type: object
                    properties:
                      token:
                        type: string
                        description: 1-hour JWT to pass as the `data-token` attribute on the embed widget script tag.
                      sid:
                        type: string
                        description: Session identifier for tracking this embed instance.
                      model:
                        type: string
                        description: The model baked into the token claim (present when `model` was requested).
                      supported_models:
                        type: array
                        items:
                          type: string
                        description: Canonical model families this agent can be launched as right now (e.g. a ready expression-2 agent lists `expression-2`). Tier slugs inherit their family and are not listed.
                        example:
                        - essence-2
                        - expression-2
        '400':
          description: '`MISSING_PARAM` — the body left out `agent_id` or `fingerprint`; both are required and neither has a default. `VALIDATION_ERROR` — the `model` field names something that is not an accepted model; the message lists the names that are.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_fingerprint:
                  summary: No fingerprint
                  value:
                    error:
                      code: MISSING_PARAM
                      message: Missing fingerprint parameter
                      httpStatus: 400
                    status: error
                    status_code: 400
                missing_agent_id:
                  summary: No agent_id
                  value:
                    error:
                      code: MISSING_PARAM
                      message: Missing agent_id parameter
                      httpStatus: 400
                    status: error
                    status_code: 400
                unknown_model:
                  summary: A model name that does not exist
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: 'Invalid model ''essence-3''; must be one of: essence-1, expression-1, essence-2, expression-2 (legacy names and tier slugs are still accepted)'
                      httpStatus: 400
                    status: error
                    status_code: 400
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: '`NOT_FOUND` — no agent matches `agent_id` under this API secret. A **deleted** agent answers this too, so a delete takes the agent out of the embed path immediately.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NOT_FOUND
                  message: 'Agent not found for code: A95SXN5716'
                  httpStatus: 404
                status: error
                status_code: 404
        '409':
          description: '`MODEL_NOT_GENERATED` — the requested `model` folds to a known family the agent can''t be launched as right now (it is missing from the agent''s `supported_models`). For the trained families (`expression-2` / `essence-2`) the message is `agent <code>''s <model> model hasn''t been generated yet`. Add the model (`POST /v1/agent/{code}/models`) or create the agent with it, then retry.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: MODEL_NOT_GENERATED
                  message: agent A56ZFX6217's expression-2 model hasn't been generated yet
                  httpStatus: 409
                status: error
                status_code: 409
        '429':
          $ref: '#/components/responses/RateLimitedByAddress'
    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
  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