The avatar file

The self-contained .imx file every bitHuman avatar ships in.

What an `.imx` is

An .imx file is one avatar in one file: everything an engine needs to animate one face, downloaded once and rendered on your own hardware. Every model that renders on your own hardware uses it — a first-generation Essence 1 identity, an Essence 2 identity, and an Expression 2 identity.

Every download is named <CODE>.imx. The same file opens on every on-device runtime — Python, Swift and the CLI — and bithuman open tells you which model a file you were given holds.

Where `.imx` files come from

Source	How
Showcase	`bithuman pull <slug>` — pre-built avatars from bithuman.ai → Explore, which opens on Essence 2 and Expression 2 agents.
Dashboard	Upload a portrait + voice samples in bithuman.ai → Studio.
API	`POST /v1/agent/generate` returns an `agent_code` whose `.imx` you can download.

See Building avatars for the full creation flow and media tips.

Agent codes

The .imx is keyed by an agent code (e.g. A23WJF0199). The cloud runtime and REST API resolve an agent by its code — you don’t ship a file. The on-device SDKs open a local .imx — the file you downloaded for that code — and the key comes from BITHUMAN_API_SECRET in the environment, checked at the first frame:

import bithuman

with bithuman.open("wise-pup.imx") as avatar:     # the local file — required on-device
    for image in avatar.render("speech.wav"):      # (height, width, 3) uint8, RGB
        ...

To get the file for a local run, download it by code or slug — bithuman pull <CODE> on macOS or Linux, or GET /v1/agent/{code}/model/download — see Download an avatar file.

Download an avatar file

Pull the file down and pass it by path. A showcase slug needs no account — bithuman pull downloads it anonymously:

bithuman pull sofia-ramirez
# → ~/.cache/bithuman/showcase/sofia-ramirez.imx

sofia-ramirez (agent code A52DHS2219) is an Essence 2 sample identity from the showcase, about 148 MB. bithuman list prints every showcase slug; a slug that is not in that list is refused with slug '<name>' not found in manifest.

bithuman pull <slug>, bithuman list and bithuman open need no credential for a sample avatar. Pulling your own agent by code, and playing any model with bithuman run or bithuman render, need bithuman login or BITHUMAN_API_SECRET; session time bills at the published rates.

Cache locations by surface:

Surface	Cache location
CLI	pulls in `~/.cache/bithuman/showcase/` (samples) and `~/.cache/bithuman/agents/` (your agents); unpacked copies in `~/.cache/bithuman/bundles/`
Python	unpacked copies in `~/.cache/bithuman/avatars/`; engine files in `~/.bithuman/deps/`
Swift (Expression on Mac/iPad)	`~/.cache/bithuman/expression/`

Downloads are integrity-verified and cached. Later launches skip the download.

One container, one file per model

Each model produces its own per-identity file in that container, downloaded with GET /v1/agent/{code}/model/download (or bithuman pull <code>, with --model when the agent has more than one):

Model	What it is
`essence-1`	The first-generation identity — a pre-rendered base whose mouth is patched to the audio. Opens in the Python SDK and the CLI’s `run`.
`essence-2`	The Essence 2 file; its size varies per avatar. Renders locally in the CLI, the Python SDK, the Android library and the Swift `Essence2` product — the first local play checks the license with the cloud, so it needs your sign-in.
`expression-2`	The Expression 2 file. Renders locally in the CLI, Python, Apple and Android, or on the cloud.

Older file extensions (.lebundle.imx, .avatar) still open: Renamed and retired names.

Disk use and compatibility

The .imx format is forward-compatible within a major version. The first open unpacks the file into that cache, using about its size again on disk; later opens reuse it. Your file is never rewritten.

Inspecting an `.imx`

bithuman open <file> prints the container format, the model family (Family: essence-2 (Essence 2)) and the files inside; --json adds the manifest. It reads the file on your own disk, so it needs no account and no network:

bithuman open ~/.cache/bithuman/showcase/sofia-ramirez.imx

The engine value it prints is a legacy name: what each one means.

Where to go next

Building avatars — design likeness, voice, and personality.
Audio streaming — drive the .imx with audio.
CLI reference — bithuman open, pull, list, and more.

What an .imx is

Where .imx files come from