# The avatar file

URL: https://docs.bithuman.ai/models/avatar-file

> The self-contained .imx file every bitHuman avatar ships in — one container for Essence 1, Essence 2 and Expression 2 identities — where it comes from, how it's addressed by agent code, and how to inspect it.

## What an `.imx` is

An `.imx` file is the container a bitHuman avatar ships in: one self-contained
file of identity weights, textures and a manifest (model version, ABI, license)
that an [engine](https://docs.bithuman.ai/models/how-it-works) reads to animate one specific face.
Every model that renders on your own hardware uses it — a first-generation
[Essence 1](https://docs.bithuman.ai/models/first-generation#essence-1) identity, an [Essence 2](https://docs.bithuman.ai/models/essence-2)
identity, and an [Expression 2](https://docs.bithuman.ai/models/expression-2) identity. Every download is
named `<CODE>.imx`; older Expression 2 files may carry the legacy `.avatar`
extension, which opens the same way. The same file opens on every on-device runtime — [Python](https://docs.bithuman.ai/platforms/python),
[Swift](https://docs.bithuman.ai/platforms/ios) and the [CLI](https://docs.bithuman.ai/platforms/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](https://www.bithuman.ai/explore), which opens on Essence 2 and Expression 2 agents. |
| **Dashboard** | Upload a portrait + voice samples in [bithuman.ai → Studio](https://www.bithuman.ai). |
| **API** | [`POST /v1/agent/generate`](https://docs.bithuman.ai/api/reference) returns an `agent_code` whose `.imx` you can download. |

See [Building avatars](https://docs.bithuman.ai/build/create-avatar) 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:

```python
import bithuman

with bithuman.open("A23WJF0199.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`](https://docs.bithuman.ai/api/agents#download-an-agents-model) — see [Caching for offline use](#caching-for-offline-use).

> **Note** Use `agent_code`, never the deprecated `figure_id` — the old identifier returns a 400.

## Caching for offline use

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

```bash
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](https://docs.bithuman.ai/pricing).

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`](https://docs.bithuman.ai/api/agents#download-an-agents-model)
(or `bithuman pull <code>`, with `--model` when the agent has more than one):

| Model | Artifact | What it is |
|---|---|---|
| [`essence-1`](https://docs.bithuman.ai/models/first-generation#essence-1) | `.imx` | The first-generation identity — a pre-rendered base whose mouth is patched to the audio. Opens in the [Python SDK](https://docs.bithuman.ai/platforms/python) and the [CLI](https://docs.bithuman.ai/platforms/cli)'s `run`. |
| [`essence-2`](https://docs.bithuman.ai/models/essence-2) | `.imx` | The Essence 2 bundle; size is per identity, so read `Content-Length`. Licensed weights; renders locally in the [CLI](https://docs.bithuman.ai/platforms/cli#platform-notes), the [Python SDK](https://docs.bithuman.ai/platforms/python), the [Android library](https://docs.bithuman.ai/platforms/android) and the Swift [`Essence2` product](https://docs.bithuman.ai/platforms/ios) — the first local play checks the license with the cloud, so it needs your sign-in. |
| [`expression-2`](https://docs.bithuman.ai/models/expression-2) | `.imx` (older downloads: `.avatar`): the same container under two names (a few early identities use an older format; `bithuman open` tells you which) | Renders locally in the [CLI](https://docs.bithuman.ai/platforms/cli), [Python](https://docs.bithuman.ai/platforms/python), [Apple](https://docs.bithuman.ai/platforms/ios) and [Android](https://docs.bithuman.ai/platforms/android), or on the cloud. |

Older releases saved Essence 2 files as `<CODE>.lebundle.imx`, a legacy extension. Such a file keeps working and `bithuman open` reads it; today's downloads are named `<CODE>.imx`. The model is [`essence-2`](https://docs.bithuman.ai/models/essence-2).

## 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:

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

### The `engine` value is a legacy name

`bithuman open` reports an **`engine`** read from the container header (also
`engine` in [`--json`](https://docs.bithuman.ai/platforms/cli/reference#json-output)), 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 header | The model you actually have |
|---|---|
| `essence1` | [Essence 1](https://docs.bithuman.ai/models/first-generation#essence-1) — also the value an older container with no header resolves to |
| `essence2-light` | **[Essence 2](https://docs.bithuman.ai/models/essence-2)** — request it as `essence-2` |
| `essence2-quality` | Essence 2 Max (Enterprise plan only) — not a model you can request on other plans; treat the file as **[Essence 2](https://docs.bithuman.ai/models/essence-2)** |
| `expression2` | **[Expression 2](https://docs.bithuman.ai/models/expression-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`](https://docs.bithuman.ai/api/agents#errors).

## File-format stability

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.

## Where to go next

- [Building avatars](https://docs.bithuman.ai/build/create-avatar) — design likeness, voice, and personality.
- [Audio streaming](https://docs.bithuman.ai/models/how-it-works#audio-in-frames-out) — drive the `.imx` with audio.
- [CLI reference](https://docs.bithuman.ai/platforms/cli) — `bithuman open`, `pull`, `list`, and more.