API reference

Every endpoint in the bitHuman OpenAPI spec, grouped by resource.

• Base URLhttps://api.bithuman.ai
• Authenticationapi-secret: $BITHUMAN_API_SECRET header · Authentication
• OpenAPI 3.1openapi.yaml for Postman, Insomnia or a generated client

52 operations. Each one is documented on its resource page with curl, Python and Node samples. Endpoints outside the OpenAPI spec have their own pages: Organizations · Providers · API secrets · Rate limits · Realtime.

Authentication

Method	Path	Operation
POST	/v1/validate	Validate API secret
POST	/v1/runtime-tokens/mint	Mint a scoped runtime token for one agent
POST	/v1/runtime-tokens/request	Request a runtime token, or start a cloud avatar

Agent Generation

Method	Path	Operation
POST	/v1/agent/generate	Generate a new agent
GET	/v1/agent/status/{agent_id}	Get agent generation status

Agent Management

Method	Path	Operation
GET	/v1/agent/{code}	Get agent details
POST	/v1/agent/{code}	Update an agent's prompt or providers
DELETE	/v1/agent/{code}	Delete an agent
POST	/v1/agent/{code}/models	Add a model to an existing agent
GET	/v1/agent/{code}/model/download	Download an agent's model artifact
GET	/v1/models/showcase	List the freely downloadable showcase models
GET	/v1/agents	List agents

Agent Context

Method	Path	Operation
POST	/v1/agent/{code}/speak	Make agent speak
GET	/v1/agent/{code}/sessions	List an agent's live sessions
POST	/v1/agent/{code}/add-context	Add context to agent

Files

Method	Path	Operation
POST	/v1/files/upload	Upload a file

Dynamics

Method	Path	Operation
POST	/v1/dynamics/generate	Generate gesture animations
GET	/v1/dynamics/{agent_id}	Get available gestures
PUT	/v1/dynamics/{agent_id}	Update dynamics configuration

Embedding

Method	Path	Operation
POST	/v1/embed-tokens/request	Generate embed token

Video

Method	Path	Operation
POST	/v1/video/generate	Generate a talking video
GET	/v1/video/{job_id}	Get talking-video status

Billing

Method	Path	Operation
GET	/v2/credit-summaries	Check credit balance
GET	/v1/usage	Usage history

Account

Method	Path	Operation
GET	/v1/me	Get current account
GET	/v1/pricing	Get credit pricing

Self-hosting

Method	Path	Operation
POST	/v1/auth/validate	Live key check for a self-hosted runtime
POST	/v1/meter/beats	Report usage from a self-hosted session

API secrets

Method	Path	Operation
GET	/v2/{user_id}/api-secrets	List API secrets
POST	/v2/{user_id}/api-secrets	Create an API secret
GET	/v2/{user_id}/api-secrets/{alias}/get-value	Reveal an API secret (console only)
DELETE	/v2/{user_id}/api-secrets/{alias}	Delete an API secret

Providers

Method	Path	Operation
GET	/v2/{user_id}/providers	Get provider config
PUT	/v2/{user_id}/providers	Update provider config

Runtime sessions

Method	Path	Operation
GET	/v2/{user_id}/runtime-sessions	List sessions
GET	/v2/{user_id}/runtime-sessions/{session_id}/messages	Read a transcript
POST	/v2/{user_id}/runtime-sessions/{session_id}/terminate	Terminate a session
POST	/v2/{user_id}/runtime/revoke-all	Revoke all runtime keys
GET	/v1/runtime-sessions/{session_id}	Read a cloud avatar session
POST	/v1/runtime-sessions/{session_id}/end	End a cloud avatar session

Knowledge

Method	Path	Operation
POST	/v1/knowledge/files	Ingest a file or URL
GET	/v1/knowledge/kbs	List knowledge bases
POST	/v1/knowledge/kbs	Create a knowledge base
POST	/v1/knowledge/kbs/{kb_id}/rebuild	Rebuild a knowledge base

Realtime

Method	Path	Operation
POST	/v1/realtime/connect	Start or end a WebRTC Realtime call

Status

Method	Path	Operation
GET	/readyz	API readiness

Webhooks

Method	Path	Operation
GET	/v1/webhooks	List webhooks
POST	/v1/webhooks	Create a webhook
GET	/v1/webhooks/{webhook_id}	Get a webhook
DELETE	/v1/webhooks/{webhook_id}	Delete a webhook
POST	/v1/webhooks/{webhook_id}/test	Send a test event
GET	/v1/webhooks/{webhook_id}/deliveries	List delivery attempts