Agents API

Generate avatar agents, poll their status, retrieve and update them, then make them speak or inject knowledge into live sessions.

The agent lifecycle

From “I have a face and voice” to “live talking avatar”:

Generate → Poll until ready → Resolve by code → Live session → Speak

This page covers the full REST lifecycle. For the in-process SDK flow, see the Python SDK and agent lifecycle concepts.

Validate your key

POST /v1/validate — verify your API secret before making other calls. Costs no credits.

curl -X POST https://api.bithuman.ai/v1/validate \
  -H "api-secret: $BITHUMAN_API_SECRET"

{ "valid": true }

Generate an agent

POST /v1/agent/generate — create a new avatar agent. Generation is asynchronous and costs 250 credits; the call returns immediately with an agent_id and processing status.

Parameter	Type	Required	Default	Description
`prompt`	string	no	random	System prompt / personality for the agent.
`image`	string	no	—	Image URL or base64 data for appearance.
`video`	string	no	—	Video URL or base64 data for appearance and mannerisms.
`audio`	string	no	—	Audio URL or base64 data for voice cloning.
`aspect_ratio`	string	no	`16:9`	Image aspect ratio (`16:9`, `9:16`, `1:1`).
`video_aspect_ratio`	string	no	`16:9`	Video aspect ratio (`16:9`, `9:16`, `1:1`).
`agent_id`	string	no	auto	Custom agent identifier.
`duration`	number	no	`10`	Source video duration in seconds.

import requests

resp = requests.post(
    "https://api.bithuman.ai/v1/agent/generate",
    headers={"Content-Type": "application/json", "api-secret": "YOUR_API_SECRET"},
    json={
        "prompt": "You are a professional video content creator.",
        "image": "https://example.com/avatar.jpg",
    },
)
print(resp.json())

{
  "success": true,
  "message": "Agent generation started",
  "agent_id": "A91XMB7113",
  "status": "processing"
}

Note The generation endpoint is POST /v1/agent/generate. (Older docs referenced /v1/agent-generation — that path is incorrect.)

Poll status

GET /v1/agent/status/{agent_id} — returns the current state of a generation request. Poll every 5 seconds.

Status	Description
`processing`	Initial state — generation queued.
`generating`	Active generation in progress (sub-steps running).
`completed`	All steps finished (transitional — becomes `ready`).
`ready`	Success — the `.imx` model is available for use.
`failed`	Failure — check `error_message`.

Treat ready and failed as terminal; generating and completed are intermediate, so keep polling. Typical wall-clock is two to five minutes.

{
  "success": true,
  "data": {
    "agent_id": "A91XMB7113",
    "status": "ready",
    "progress": 1.0,
    "progress_msg": "Done",
    "current_step": "lip_created",
    "error_message": null,
    "system_prompt": "You are a professional video content creator.",
    "image_url": "https://...",
    "video_url": "https://...",
    "model_url": "https://...",
    "name": "agent name"
  }
}

Progress field	Type	Description
`progress`	float (0.0–1.0)	Generation progress as a fraction. `1.0` is complete.
`progress_msg`	string	Human-readable progress description.
`current_step`	string	Current generation step (e.g. `lip_created`).

Generate and poll

import os, time, requests

BASE = "https://api.bithuman.ai"
SECRET = os.environ["BITHUMAN_API_SECRET"]
headers = {"Content-Type": "application/json", "api-secret": SECRET}

resp = requests.post(f"{BASE}/v1/agent/generate", headers=headers,
                     json={"prompt": "You are a friendly AI assistant."})
agent_id = resp.json()["agent_id"]

while True:
    data = requests.get(f"{BASE}/v1/agent/status/{agent_id}",
                        headers={"api-secret": SECRET}).json()["data"]
    if data["status"] == "ready":
        print("Ready:", data["model_url"])
        break
    if data["status"] == "failed":
        raise SystemExit(f"Failed: {data['error_message']}")
    time.sleep(5)

Get an agent

GET /v1/agent/{code} — retrieve full details for an agent by its code.

import requests

code = "A91XMB7113"
data = requests.get(
    f"https://api.bithuman.ai/v1/agent/{code}",
    headers={"api-secret": "YOUR_API_SECRET"},
).json()
agent = data["data"]
print(agent["name"], agent["status"])

{
  "success": true,
  "data": {
    "agent_id": "A91XMB7113",
    "status": "ready",
    "system_prompt": "You are a friendly AI assistant",
    "image_url": "https://cdn.bithuman.ai/assets/image.jpg",
    "video_url": "https://cdn.bithuman.ai/assets/video.mp4",
    "model_url": "https://cdn.bithuman.ai/assets/model.imx",
    "name": "My Agent"
  }
}

Update an agent’s prompt

POST /v1/agent/{code} — update the system prompt of an existing agent without regenerating it. The agent must already exist. For a new face or voice, generate a new agent.

import requests

code = "A91XMB7113"
resp = requests.post(
    f"https://api.bithuman.ai/v1/agent/{code}",
    headers={"Content-Type": "application/json", "api-secret": "YOUR_API_SECRET"},
    json={"system_prompt": "You are a professional sales assistant."},
)
print(resp.json())

{ "agent_code": "A91XMB7113", "updated": true }

Make an agent speak

POST /v1/agent/{agent_code}/speak — trigger the agent to speak a message to users in an active session.

Parameter	Type	Required	Description
`message`	string	yes	Text the agent will speak.
`room_id`	string	no	Target a specific room. If omitted, delivers to all active rooms.

curl -X POST https://api.bithuman.ai/v1/agent/A12345678/speak \
  -H "Content-Type: application/json" \
  -H "api-secret: $BITHUMAN_API_SECRET" \
  -d '{
    "message": "We have a 20% discount available today.",
    "room_id": "customer_session_1"
  }'

{
  "agent_code": "A12345678",
  "context_type": "speak",
  "delivered_to_rooms": 1
}

Inject knowledge

POST /v1/agent/{agent_code}/add-context — add background knowledge the agent uses to inform future responses. Set type to speak to trigger speech instead.

Parameter	Type	Required	Default	Description
`context`	string	yes	—	Knowledge to inject (or message to speak).
`type`	string	no	`add_context`	`add_context` injects knowledge silently; `speak` triggers a verbal response.
`room_id`	string	no	—	Target a specific room. If omitted, delivers to all active rooms.

import requests

requests.post(
    "https://api.bithuman.ai/v1/agent/A12345678/add-context",
    headers={"Content-Type": "application/json", "api-secret": "YOUR_API_SECRET"},
    json={
        "context": "Customer has VIP status. Preferred name: Alex. Account since 2021.",
        "type": "add_context",
        "room_id": "vip_session_42",
    },
)

Note /speak and /add-context target agents created on the bitHuman platform that have an active session — not local SDK agents. Without a live room you’ll get 404 NO_ACTIVE_ROOMS. Start a session via the embed flow or a LiveKit worker first.

Error codes

HTTP	Code	When
`401`	`UNAUTHORIZED`	Invalid or missing `api-secret`.
`402`	`INSUFFICIENT_BALANCE`	Not enough credits (generation costs 250).
`404`	`AGENT_NOT_FOUND`	No agent with the given code.
`404`	`NO_ACTIVE_ROOMS`	Agent has no active session to `/speak` or `/add-context`.
`422`	`VALIDATION_ERROR`	Invalid request body (e.g. bad `type` value).

See the full error reference and the interactive API reference.