Python API reference

Every public name in the installed bithuman package — signatures, docstrings and the exception hierarchy — read back out of the wheel PyPI serves, not out of a source tree.

The Python library has a small, fixed surface: open an avatar, render audio through it. This page is the full list — every name the installed package exports, the signature each one actually has, and what it raises.

Nobody types this page. A script installs the newest published wheel into an empty virtualenv, with nothing else in it, and reads the surface back out of the installed bytes: the type stub the package ships, each module’s __all__, inspect.signature, the docstrings, and the exception classes. It never reads our source tree.

Why that distinction is the whole point. A name that exists in source but is not exported by the installed package is not something you can call, so it is not documented here. Where the source and the shipped package disagree — a method on the runtime object that no type stub declares, a type the stub declares that will not import — this page says so rather than quietly picking one: Present in the wheel, not callable from it.

It is re-checked against the registry, not against itself. A scheduled job re-runs the extraction against whatever PyPI serves that morning and fails if what is on this page no longer matches the shipped surface. The thing that changes is the registry, not the page.

The wheel this page describes

Every name below was read back out of those bytes, in a virtualenv that had nothing else installed in it. Nothing here was read from a source tree.

bithuman

38 names, declared by the type stub the package ships.

open

open(source: Any) -> Avatar

Open an avatar and return it.

source is the avatar file on this machine. This package runs the avatar here, in your process; nothing is sent anywhere to make a frame.

Raises InvalidAvatar if it cannot be found or is not usable, NotSupported if it cannot run on this machine, NotAuthorised if the key is missing, invalid or out of credit, and Failed if something else went wrong.

Avatar

An open avatar. Get one from bithuman.open.

Usable as a context manager: with closes it for you.

render(audio: Audio) -> Iterator[np.ndarray]

Yield the frames for audio.

audio is 16 kHz mono — a buffer (bytes, or an int16/float array), the path of an audio file, or an iterable of those for a live stream. Passing a stream instead of a whole clip is the same call.

Each frame is a (height, width, 3) uint8 array in RGB order. Frames arrive in order, at the avatar’s own frame rate — which is a property of the avatar, not something to choose.

To stop early — a person interrupting the avatar — stop consuming and close the iterator; the avatar is ready for the next render.

AvatarError

Base class for every refusal this package raises.

InvalidAvatar

We cannot find it, or it is not a usable avatar.

Fix the path or the code, or fetch the avatar again.

NotSupported

This avatar cannot run here.

Use the cloud package, or another device.

NotAuthorised

The key is missing, invalid, or out of credit.

Fix the credential.

Failed

We could not do it — transient, or our fault.

Retry, then report it.

Bithuman

The docstring shipped with this symbol describes internal machinery and is not reproduced here.

AsyncBithuman

The docstring shipped with this symbol describes internal machinery and is not reproduced here.

AsyncAvatar

The docstring shipped with this symbol describes internal machinery and is not reproduced here.

ComposedFrame

The docstring shipped with this symbol describes internal machinery and is not reproduced here.

EP

Execution provider hint. CPU is the canonical baseline; the others are mapped opportunistically by the C ABI when available on the host.

AudioChunk

The docstring shipped with this symbol describes internal machinery and is not reproduced here.

VideoControl

One unit of input to the avatar runtime.

The runtime consumes a stream of these. Each control is either “speaking” (has an AudioChunk), an action / target-video cue, an emotion override, or “idle” (everything None) — in which case the runtime emits idle-loop frames.

VideoFrame

The docstring shipped with this symbol describes internal machinery and is not reproduced here.

Emotion

Emotion label, matches legacy bithuman.api.Emotion.

These are the seven canonical labels the agent worker prompts the LLM with. They flow through JSON as their string values.

EmotionPrediction

Emotion classifier output for one audio segment.

Legacy uses pydantic BaseModel with fields emotion + score; we use dataclass to avoid pulling in pydantic for the core wrapper, while keeping the field names and serialization shape.

BithumanError

Base class for all bitHuman errors.

Carries a stable string code (e.g. “model_not_found”) + a docs_url pointing at the canonical docs page for that error. Catch on this base for any bitHuman error, or on a specific subclass for targeted handling.

TokenError

Base exception for token-related errors.

TokenExpiredError

Raised when the JWT token has expired.

TokenValidationError

Raised when token validation fails (invalid signature, claims, etc.).

TokenRequestError

Raised when a token request to the auth server fails.

AccountStatusError

Raised when the account has a billing/access issue (402, 403).

Legacy bithuman makes this a subclass of TokenError (it surfaces out of the token-refresh path). We keep that inheritance for parity.

ModelError

Base exception for model-related errors.

ModelNotFoundError

Raised when the model file cannot be found.

ModelLoadError

Raised when model loading fails.

ModelSecurityError

Raised when a security restriction blocks model operations.

RuntimeNotReadyError

Raised when an operation is attempted before the runtime is ready.

Fixture

The docstring shipped with this symbol describes internal machinery and is not reproduced here.

Runtime

The docstring shipped with this symbol describes internal machinery and is not reproduced here.

EP_CPU

EP_AUTO

EP_COREML

EP_NNAPI

EP_QNN

version

core_version

abi_version

bithuman.offline

10 names, declared by the module’s own __all__.

5 of them are module constants naming an internal mechanism and are not listed here; they are not part of the two calls this package exists for.

OfflineRenderer

OfflineRenderer(imx_path: str, *, api_secret: Optional[str] = None, api_url: Optional[str] = None, threads: int = 4, model_key: Optional[str] = None, tags: str = 'offline-render')

The docstring shipped with this symbol describes internal machinery and is not reproduced here.

Usable as a context manager: with closes it for you.

close()

render(audio, max_frames: Optional[int] = None, on_frame: Optional[Callable[[np.ndarray, int], None]] = None) -> dict

Render audio (a path, or float32 16 kHz mono PCM) to full RGB frames. on_frame(frame_hw3_u8, frame_idx) receives every frame; returns the honest stats dict (CPU-class fps).

OfflineRenderError

Unspecified run-time error.

MeteringNotArmedError

The v2 metering gate refused frame production (no authenticated heartbeat / grace elapsed / 402-403). Fail-closed by design.

render_offline

render_offline(imx_path: str, audio, out_mp4: Optional[str] = None, **kw) -> dict

One-call offline render. When out_mp4 is given the frames are encoded (h264 + the source audio muxed when audio is a path).

unfold_imx

unfold_imx(imx_path: str, dst_dir: str) -> str

The docstring shipped with this symbol describes the container format, which is proprietary and not documented publicly. See Avatars and the .imx format.

bithuman.tessera_offline

10 names, declared by the module’s own __all__.

5 of them are module constants naming an internal mechanism and are not listed here; they are not part of the two calls this package exists for.

The exception hierarchy

Present in the wheel, not callable from it

A reference generated from a source tree would have listed each of these. They are in the installed package and a developer cannot use them, which is the opposite of being public.

Other modules the package exposes

Public by spelling, and not an API this page documents. They are listed so that finding one by grep is not mistaken for finding something to call.

See also

• Python — install it, get a model, render your first frame
• LiveKit — this library inside an agent worker
• Pricing — what a render costs, and what refuses without a key
• Performance — measured frame rates for every platform