REST API

The REST API creates and manages agents, speaks with text to speech, pushes lines into live sessions and renders talking videos. Every call is HTTPS with your API secret in a header, from any language that can make a request.

Before you start

• An API secret. API use needs the Creator plan or higher.
• curl, or any HTTP client.
• Credits for anything beyond a check: creating an agent is a one-time charge (pricing).

To try an avatar with no account first, use the web embed.

Authenticate

Send your API secret in the api-secret header on every call. POST /v1/validate checks it and spends nothing; it always returns 200, so read valid. The full rules are on Authentication.

First frame

export BITHUMAN_API_SECRET="<your API secret>"
curl -s -X POST https://api.bithuman.ai/v1/validate -H "api-secret: $BITHUMAN_API_SECRET"
# → {"valid":true}
curl -s -X POST https://api.bithuman.ai/v1/tts \
  -H "api-secret: $BITHUMAN_API_SECRET" -H "Content-Type: application/json" \
  -d '{"text": "Hello from bitHuman.", "voice": "F1"}' --output hello.wav
# → hello.wav

/v1/validate always returns 200; read valid. Get an API secret under Developer → API Secrets.

Complete example

Four shell scripts from the examples repository: check your secret, check your balance, create an agent from a prompt, then talk to it in the browser.

Get the code

git clone https://github.com/bithuman-product/bithuman-examples.git
cd bithuman-examples/api/rest-api/curl

Run it

./validate.sh && ./check-credits.sh
BITHUMAN_MODEL=expression-2 ./generate-agent.sh "You are a friendly fitness coach."

validate.sh and check-credits.sh spend nothing. generate-agent.sh spends one creation charge, then polls until the agent is ready (about 2 to 2.5 hours for a second-generation model; a failed creation is refunded).

Expected output

{
    "valid": true
}
Checking credit balance...
Balance:        … credits
…
{"success": true, "agent_id": "<agent_id>", "status": "processing"}
  Status: processing  Progress: 10%
…
Agent is ready!

Open https://www.bithuman.ai/embed/<agent_id> and talk to your agent. While that page is open, ./speak.sh <agent_id> "Hello!" makes it say a line.

How it works

Make it your own

• A face of your own: add "image": "https://…/portrait.jpg" to the JSON in generate-agent.sh.
• A photoreal person: BITHUMAN_MODEL=essence-2, or auto to let the platform choose.
• A video instead of a live session: POST /v1/video/generate renders your agent saying a line to an MP4.
• Other languages: api/rest-api/python has the same calls in Python.

Integrate into your app

Create your own agent

Creation is a one-time charge (pricing); a balance below the creation cost returns 402. Always send model.

curl -s -X POST https://api.bithuman.ai/v1/agent/generate \
  -H "api-secret: $BITHUMAN_API_SECRET" -H "Content-Type: application/json" \
  -d '{"model": "expression-2", "prompt": "You are a friendly fitness coach.", "image": "https://your-site.example/portrait.jpg"}'
# → {"success": true, "agent_id": "A80HVD8577", "status": "processing"}

Poll until status is ready or failed (about 2–2.5 hours for a second-generation model):

curl -s https://api.bithuman.ai/v1/agent/status/A80HVD8577 -H "api-secret: $BITHUMAN_API_SECRET"
# → {"success": true, "data": {"status": "ready", "progress": 1.0, …}}

Make it speak in a live session

Open https://www.bithuman.ai/embed/<your agent code>, then push text from your backend:

curl -s -X POST https://api.bithuman.ai/v1/agent/A80HVD8577/speak \
  -H "api-secret: $BITHUMAN_API_SECRET" -H "Content-Type: application/json" \
  -d '{"message": "Hello! Great to meet you."}'
# → {"agent_code": "A80HVD8577", "delivered_to_rooms": 1, …}

404 means the agent is not yours, or it has no live session (the message says which).

To show a sample agent with no account, embed it:

<iframe src="https://www.bithuman.ai/embed/A23WJF0199" allow="microphone *" style="width:100%;height:600px;border:0"></iframe>

Open the page and talk to it. Keep the * in allow, or the microphone is blocked. For your own site in production, mint an embed token.

Render a talking video

curl -s -X POST https://api.bithuman.ai/v1/video/generate \
  -H "api-secret: $BITHUMAN_API_SECRET" -H "Content-Type: application/json" \
  -d '{"agent_code": "A80HVD8577", "model": "expression-2", "input": {"type": "text", "text": "Welcome to our store."}}'

Poll GET /v1/video/{job_id} until status is completed, then download video_url (Talking video).

Troubleshooting

All error codes: Errors.

Reference

• API reference: every endpoint, generated from the OpenAPI spec.
• Agents · Talking video API · Text to speech · Embedding · Errors