bitHuman REST API Reference

The bitHuman API lets you programmatically create, manage, and interact with avatar agents.

Base URL

https://api.bithuman.ai

Authentication

All requests require the api-secret header. Get your API secret from Developer → API Keys.

api-secret: YOUR_API_SECRET

Agent Identifiers

All endpoints use the agent code (e.g. A91XMB7113) to identify agents. This is the same value across all endpoints, referred to as {code}, {agent_code}, or {agent_id} depending on the endpoint. You receive this code when you generate an agent or find it in your Library — click any agent to see its Agent ID.

Available APIs

Agent Generation

Create new avatar agents from prompts, images, or video

Agent Management

Validate credentials, retrieve agent details, update prompts

Agent Context

Send real-time messages and inject context into live sessions

File Upload

Upload images, audio, video, and documents

Dynamics

Generate and manage avatar movements and gestures

Credits & Billing

Check credit balance, usage rates, and minutes remaining

Common Error Format

All errors follow the same structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "httpStatus": 401
  },
  "status": "error",
  "status_code": 401
}

See the Error Reference for all error codes.

HTTP Status	Meaning
`200`	Success
`400`	Invalid request parameters
`401`	Invalid or missing `api-secret`
`402`	Insufficient credits
`404`	Resource not found
`413`	Payload too large
`415`	Unsupported media type
`422`	Validation error
`429`	Rate limit exceeded
`500`	Internal server error
`503`	Service unavailable (workers busy)

API Reference

​Base URL

​Authentication

​Agent Identifiers

​Available APIs