Docs index: /llms.txt · every page as Markdown: add .md

bitHuman Docs
Pricing Console Discord Get API secret
‹ Overview

Renamed and retired names

Find what an older command, flag or API name is called now.

View as Markdown Open in ChatGPT Open in Claude

Older spellings you may still meet in scripts, code and saved links, and what to use now.

Renamed in 2.7.3

The old spellings still work for now. Each prints one line on stderr naming what to use instead, and --json output is unchanged.

WasNow
render X -a in.wavrender X in.wav
render writing output.mp4render writes <avatar>.mp4 unless you pass -o
render --quality, --target-sizeone preset, each avatar’s default size
run --allow-public-bindBITHUMAN_ALLOW_PUBLIC_BIND=1
run --cloud, --offscreen, --frames, --embedded-livekit, --livekit-*not needed: run <avatar> picks and starts what it needs; frames without a window come from render --limit N
chat, info, avatars, list --agentsrun, open, list, list --mine
list --limit/--offset/--status, account --start/--end/--agentthe full list; filter the --json output
--api-basenot needed: the CLI talks to https://api.bithuman.ai
--destBITHUMAN_CACHE_DIR
--quiet, --no-color, BITHUMAN_JSON/QUIET/NO_COLOR--json, NO_COLOR=1

Older names

Older SDK and API names you may still meet:

Older nameWhat to use now
BITHUMAN_API_KEYBITHUMAN_API_SECRET. The deprecated alias is still read, with a warning, until CLI 3.0 and bithuman 4.0.
POST /v1/realtime/ephemeral-token (ek_… tokens)Retired; connect through the realtime relay.
bithuman.offline, render_offlineDeprecated; use bithuman.open(path).render(audio, out_mp4=...) (Python).
bitHumanKitA legacy Swift package, not the current one; use the Swift package products Expression2 and Essence2Kit.

Retired model and file names

Every other page uses the four model names. Some older names are still strings you may read in links, logs or files:

Legacy name you may meetWhereWhat it meansDo you type it?
essence, expressionolder ?model= links and request bodiesEssence 1, Expression 1No — write essence-1 / expression-1
essence2-lightthe Engine: line from bithuman open — a legacy engine valueEssence 2No — read the Family: line
essence-2-lightthe retired tier name (the old Light tier)Essence 2No — a request naming it gets a 400; write essence-2
elevate, essence-2-qualityretired names of a premium tiera separate tier, not Essence 2No — a request naming them gets a 400
embodya retired request spellingExpression 2No — a request naming it gets a 400 naming expression-2
.lebundle.imx, .avatarolder file extensionsan Essence 2 or Expression 2 model fileOnly if you already have one; it opens as-is
[embody]the legacy prefix on log lines of the Apple Expression2 engineExpression 2Grep your logs for it
BITHUMAN_EMBODY_DIR, EMBODY_DEBUG_FAIL_PREDICTlegacy variables the Apple Expression2 engine still reads beside their EXPRESSION2_ twinsExpression 2No — set BITHUMAN_EXPRESSION2_DIR
libelevate, libelevate-androidlegacy library namesEssence 2No — the Android coordinate is ai.bithuman:essence2-android
libelevate-webthe legacy path of the in-browser runtimeEssence 2 in a browserNo — embed with https://www.bithuman.ai/embed/<CODE>
older Python module and class names for MP4 renderinglegacy names, still importable — listed under Older namesthe Essence 2 MP4 routeNo — write bithuman.offline, OfflineRenderer, render_offline, OfflineRenderError
bithuman[offline] and the other older pip extraslegacy pip extras, removed from the wheel in 2.11.6nothing — pip warns and installs the base wheelNo — pip install bithuman

Saved links keep working: essence-2-light-gpu / essence-2-light-cpu still pin their tiers, links carrying essence-2-light or essence-2-light-ane route to the Essence 2 default chain, and the older essence-2-ane / expression-2-ane spellings of the Apple tier stay accepted. A link carrying the retired ?model=essence-2-quality falls back to the agent’s stored model.

The cloud’s Apple tier is called Apple, not “ANE”: it is the whole Apple silicon target, not one accelerator inside it.

The engine value is a legacy name

bithuman open reports an engine read from the container header (also engine in --json), and the Python runtime quotes the same string verbatim in load errors — for example backend loader for engine='essence2-light'.

These engine ids are legacy names kept for compatibility. They are the literal strings readers parse, spelled here exactly as you will see them:

engine in the headerThe model you actually have
essence1Essence 1 — also the value an older container with no header resolves to
essence2-lightEssence 2 — request it as essence-2
essence2-qualitya retired premium-tier name, not a model you can request; treat the file as Essence 2
expression2Expression 2 — request it as expression-2

So a current Essence 2 bundle reports engine: essence2-light. The model is Essence 2, requested as essence-2: the engine id names the loader family, not the product, so the value is expected, not a mismatch.

Warning Never send an engine id to the API. model takes essence-2, expression-2, auto, essence-1 or expression-1; any other value returns 400 VALIDATION_ERROR.