# API overview

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

> REST API for avatars, voice, live sessions and embedding, from any language.

## What the API does

Plain HTTPS and JSON from any language, for backends and scripts where a native SDK does not fit. Every request carries your API secret in the `api-secret` header ([Authentication](https://docs.bithuman.ai/api/authentication)).

## Base URL

Every path on these pages is relative to `https://api.bithuman.ai`. First call: [REST API](https://docs.bithuman.ai/platforms/rest#run-your-first-avatar). Every endpoint: [API reference](https://docs.bithuman.ai/api/reference).

## What you can build

- [Agents](https://docs.bithuman.ai/api/agents): Generate avatars, make them speak and ground them in your documents.
- [Media](https://docs.bithuman.ai/api/video): Talking videos from your audio, gestures and files.
- [Embed and realtime](https://docs.bithuman.ai/api/embedding): An agent in any web page, or a Realtime voice session.
- [Account](https://docs.bithuman.ai/api/billing): Credits, API secrets, organizations and your own provider keys.

## How agents are identified

An agent is named by its code (`A80HVD8577`). Request bodies call it `agent_id` (creation, embed tokens, gestures) or `agent_code` (video, runtime tokens), never both.

## Status and versioning

Endpoints change additively. `/v1` and `/v2` are part of each path, not a version switch. Live status: [status.bithuman.ai](https://status.bithuman.ai).

**Pages in this section**

### Basics

- [API overview](https://docs.bithuman.ai/api.md): REST API for avatars, voice, live sessions and embedding, from any language.
- [Authentication](https://docs.bithuman.ai/api/authentication.md): Authenticate with the api-secret header, check a secret, and use short-lived tokens.
- [Errors](https://docs.bithuman.ai/api/errors.md): The error format, HTTP status codes and every error code, with fixes.
- [Rate limits](https://docs.bithuman.ai/api/rate-limits.md): Request limits per plan and tier, the 429 contract, and a retry strategy.
- [Webhooks](https://docs.bithuman.ai/api/webhooks.md): Receive signed notifications when async work finishes, and verify each signature.
- [Realtime relay](https://docs.bithuman.ai/api/realtime.md): Open a metered OpenAI-Realtime voice session through bitHuman, over WebSocket or WebRTC.

### Agents

- [Agents](https://docs.bithuman.ai/api/agents.md): Create an avatar agent from a portrait, then manage it and make it speak.
- [Runtime sessions](https://docs.bithuman.ai/api/runtime-sessions.md): List live sessions, read a transcript, end a session, or revoke every runtime key.
- [Knowledge](https://docs.bithuman.ai/api/knowledge.md): Ingest documents and URLs into knowledge bases, with an organization API secret.
- [Embedding](https://docs.bithuman.ai/api/embedding.md): Mint short-lived tokens on your backend and embed an avatar in any website.

### Media

- [Talking video API](https://docs.bithuman.ai/api/video.md): Render a talking-video MP4 from your own hosted audio.
- [Gestures API](https://docs.bithuman.ai/api/dynamics.md): Generate gestures (wave, nod, laugh) for an Essence 1 avatar, and trigger them.
- [Files](https://docs.bithuman.ai/api/files.md): Upload images, video, audio and documents by URL or base64.

### Account

- [Billing & usage](https://docs.bithuman.ai/api/billing.md): Read a live credit balance and per-mode minute estimates.
- [API secrets API](https://docs.bithuman.ai/api/api-keys.md): Create, list, and delete your account's API secrets programmatically.
- [Organizations](https://docs.bithuman.ai/api/organizations.md): Create a team, invite members, manage roles and org-scoped API secrets.
- [Providers (BYOK)](https://docs.bithuman.ai/api/providers.md): Bring your own LLM, STT and TTS keys, stored encrypted, for your agents.