REST API

The REST API creates agents, drives live sessions and renders talking videos from your audio, from any language.

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: a talking video bills per minute of output (pricing).
• Time: an agent of your own takes minutes with Essence 2, longer with Expression 2. Start with a sample agent meanwhile.

Start with a sample agent: any API secret can read the public samples, such as A23WJF0199 (wise-pup), and render them speaking your audio, GET /v1/models/showcase lists them; each one’s supported_models says which model to pass. Then create an agent of your own.

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.

Run your first avatar

Render the wise-pup sample speaking a 5-second hosted clip (16 kHz mono WAV):

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/video/generate \
  -H "api-secret: $BITHUMAN_API_SECRET" -H "Content-Type: application/json" \
  -d '{"model": "expression-2", "agent_code": "A23WJF0199", "input": {"type": "audio", "audio_url": "https://docs.bithuman.ai/samples/speech-16k-short.wav"}}'
# → {"success": true, "job_id": "vid_…", "status": "processing"}
curl -s https://api.bithuman.ai/v1/video/vid_… -H "api-secret: $BITHUMAN_API_SECRET"
# → … "status": "completed", "video_url": "https://…mp4"

Poll until status is completed, then open video_url. The video costs 4 credits, billed to you; the sample’s owner pays nothing. bitHuman renders the audio you bring: a recording, or a WAV or MP3 from any text-to-speech tool, at a public URL. On a sample, only audio input and the models in its supported_models work, and /speak is the owner’s alone. Get an API secret under Developer → API Secrets.

Complete example

Then make an agent of your own. 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://gitlab.com/bithuman/sdk/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 (pricing), then polls until the agent is ready (minutes for Essence 2, longer for Expression 2; 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. Every model except Expression 2 needs a real human face (Choosing a model).
• A video instead of a live session: POST /v1/video/generate renders your agent speaking your audio 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. Your own agent takes minutes for essence-2 (or expression-1) and longer for expression-2. Always send model: essence-2 for a real person, expression-2 for any character (Choosing a 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:

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": "audio", "audio_url": "https://docs.bithuman.ai/samples/speech-16k-short.wav"}}'

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 · Embedding · Errors