# Embedding

URL: https://docs.bithuman.ai/api/embedding

> Mint short-lived tokens on your backend and embed an avatar in any website.

## Embed an avatar

Drop an agent onto any page as an iframe — no SDK install required:

```html
<iframe src="https://www.bithuman.ai/embed/A23WJF0199" allow="microphone *; camera *; autoplay *" style="width:100%;height:100vh;border:0"></iframe>
```

`A23WJF0199` is the `wise-pup` sample avatar (Expression 2). Replace it with your agent code — find it in the
[Library](https://www.bithuman.ai/#library) or the Deploy & Share dialog.

> **Warning** Keep `microphone *` (and `camera *` for camera chat) in `allow`, with the `*`. The embed redirects to another origin, so a bare `allow="microphone"` leaves the microphone silently blocked. A restrictive `Permissions-Policy` on your page blocks it too.

## Production: mint a token

`POST /v1/embed-tokens/request`

For per-visitor session tracking and rate limiting, mint a short-lived embed
token on your **backend** (never expose your API secret in frontend code) and
append it to the iframe URL.

`POST /v1/embed-tokens/request`

| Field | Type | Required | Description |
|---|---|---|---|
| `agent_id` | string | yes | Your agent's code. This endpoint reads `agent_id` only: `agent_code` returns `400`. |
| `fingerprint` | string | yes | Stable per-visitor string (any format). Used for per-visitor rate limiting and — if you run your own LLM — sent to your endpoint as the OpenAI `user` field so you can tell whose call it is ([details](https://docs.bithuman.ai/api/providers#knowing-which-end-user-a-call-belongs-to)). Supply one value per end user and reuse it across their visits. |
| `model` | string | no | `essence-1`, `essence-2`, `expression-1` or `expression-2`; defaults to the agent's model. A model the agent does not have returns [`409 MODEL_NOT_GENERATED`](https://docs.bithuman.ai/api/errors#model-errors); one outside your plan, `403 PLAN_REQUIRED`. |

Every entry of `supported_models` in the mint response (and in `GET /v1/agent/status/{id}`) is a model name you can send back as `model` unchanged.

Call it from your server, so the API secret never reaches the browser; `data.token` goes on the iframe URL.

```bash
curl -X POST https://api.bithuman.ai/v1/embed-tokens/request \
  -H "api-secret: $BITHUMAN_API_SECRET" -H "Content-Type: application/json" \
  -d '{"agent_id": "A23WJF0199", "fingerprint": "3f9a2c1b8e7d4a6f0b21c4d5e6f70812"}'
```

### Response

```json
{
  "status": "success",
  "status_code": 200,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "sid": "f3c9...",
    "model": "expression-2",
    "supported_models": ["expression-2"]
  }
}
```

The `token` is a **1-hour, HS256-signed JWT**. Mint one per visitor session.
`supported_models` lists the canonical model families the agent can be
launched as right now (useful for building your own model picker). The
response always includes the `model` baked into the token (the agent's own
model when you omit it).

### Use the token in the iframe

Pass it as a query string:

```html
<iframe src="https://www.bithuman.ai/embed/YOUR_AGENT_CODE?token=THE_TOKEN" allow="microphone *; camera *; autoplay *" style="width:100%;height:100vh;border:0"></iframe>
```

## Session events

Every conversation on an embed of your agent can POST `room.join` and `chat.push`
events, including the text of every message, to a URL on your account. See
[session events](https://docs.bithuman.ai/api/webhooks#session-events).

## Notes

- The embed token is more constrained than a [runtime token](https://docs.bithuman.ai/api/authentication)
  — it's purpose-built for cross-origin iframe authentication.
- WebRTC requires a secure context: serve the embedding page over **HTTPS** or
  the browser will block microphone access (except on `localhost`).
- The `fingerprint` should be generated once per device and persisted, so
  per-visitor rate limits track the same visitor across sessions.
- An embedded session bills to the agent's owner at the rates on
  [pricing](https://docs.bithuman.ai/pricing).

See the interactive [API reference](https://docs.bithuman.ai/api/reference) for the full request and
response schema.