bithuman-ai Embedding API
Mint short-lived tokens for website avatar embeds.
Mint short-lived tokens for website avatar embeds.
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-embedding-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 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