# Changelog URL: https://docs.bithuman.ai/changelog > Release notes for every bitHuman SDK, the CLI, the API and plugins. What changed in each release, newest day first (grouped by artifact within a day). Current versions are on [Downloads & versions](https://docs.bithuman.ai/downloads) and in [/versions.json](https://docs.bithuman.ai/versions.json). Follow new releases with the [RSS feed](https://docs.bithuman.ai/changelog.xml). Entries before August 2026 are in the [archive](https://docs.bithuman.ai/changelog/archive). ## Highlights Recent releases worth a look first. - **One frame stream for Expression 2 on Apple** (Swift package 2.18.0 — 2026-09-27, Swift): `frames(audioClock:)` hands out idle and speech frames on your player's clock, and `events()` reports when each reply starts and ends. [Release notes](https://docs.bithuman.ai/changelog#swift-package-2180--2026-09-27) · [Docs](https://docs.bithuman.ai/platforms/ios) - **One call renders an MP4 from Python** (bithuman 2.11.15 — 2026-09-27, Python): `bithuman.open(path).render(audio, out_mp4=...)` writes the video with its speech, for every model. [Release notes](https://docs.bithuman.ai/changelog#bithuman-21115--2026-09-27) · [Docs](https://docs.bithuman.ai/build/talking-video) - **Talk to any gallery avatar from the CLI** (CLI 2.8.2 — 2026-09-27, CLI): `bithuman run ` plays the gallery avatar with that code, the way `pull`, `render` and `open` already did. [Release notes](https://docs.bithuman.ai/changelog#cli-282--2026-09-27) · [Docs](https://docs.bithuman.ai/platforms/cli) - **The Flutter plugin builds for iOS and macOS** (Flutter plugin 2.6.20 — 2026-09-27, Flutter): iOS and macOS build from the published tag and link the published Expression 2 and Essence 2 engines. [Release notes](https://docs.bithuman.ai/changelog#flutter-plugin-2620--2026-09-27) · [Docs](https://docs.bithuman.ai/platforms/flutter) ## Breaking changes | Date | Artifact | Change | What to do | |---|---|---|---| | 2026-10-18 | REST API | `POST /v1/files/upload` stores files privately: the returned `file_url` is a signed link that expires after 7 days, and the response adds `file_id` and `url_expires_in` | pass `file_id` to agent generation and video generation instead of a saved `file_url`; `file_id` works only for files your account uploaded | | 2026-10-05 | CLI up to 2.8.8, `bithuman` up to 2.11.20 | bitHuman's release files moved from GitHub to `downloads.bithuman.ai`; these versions still fetch first-use files (and the CLI its update check) from GitHub | upgrade to CLI 2.8.9 and `bithuman` 2.11.21 | | CLI 2.9, no earlier than 2026-12-26 (announced 2026-09-27) | CLI | the CLI stops reading the API secret from a `.env` file in the working directory | export `BITHUMAN_API_SECRET`, or run `bithuman login` once | | 2026-12-26 (announced 2026-09-27) | REST API | `POST /v1/agent/generate` requires `model`; the bare names `essence` / `expression` and the `version` field are refused with a `400` | send `essence-2`, `expression-2`, `auto`, `essence-1` or `expression-1` | | 2026-12-26 (announced 2026-09-27) | REST API | `GET /v1/usage` rows drop `activity_type` | read `source` (already in every row) or `pricing_code_meaning` | | 2026-12-26 at the earliest (announced 2026-09-27) | CLI 3.0, bithuman 4.0 | the deprecated alias `BITHUMAN_API_KEY` is no longer read; bithuman 4.0 also drops `bithuman.offline` (use `bithuman.open(path).render(audio, out_mp4=...)`), `token=` and the `AsyncAvatar` alias | rename to `BITHUMAN_API_SECRET`; each old name warns until then | | 2026-10-05 | Flutter plugin 2.6.39 | macOS links the plugin's own static ONNX Runtime, not Homebrew's; Expression 2 renders on iOS 18 / macOS 15 and later, and below that `load(engine: 'expression2')` fails at once with `unsupported` (through 2.6.38 the session started and ended in `MODEL_REJECTED`) | remove `brew install onnxruntime` and do not link another ONNX Runtime into the app; run `scripts/bootstrap.sh` again; an app that renders Expression 2 sets `platform :ios, '18.0'` / `IPHONEOS_DEPLOYMENT_TARGET = 18.0` and `platform :osx, '15.0'` / `MACOSX_DEPLOYMENT_TARGET = 15.0` | | 2026-10-05 | Flutter plugin 2.6.38 | the plugin moved from GitHub to GitLab; versions up to 2.6.37 still download their iOS and macOS engines from GitHub | change the git `url` to `https://gitlab.com/bithuman/sdk/homebrew-bithuman.git` and pin `ref: flutter-plugin-v2.6.38`; `path: packages/flutter-plugin` stays the same | | 2026-10-04 | Flutter plugin 2.6.37 | iOS apps need iOS 16.4 (was 16.0); macOS apps need macOS 14.0 (was 26.0 in 2.6.36); a session whose app is in the background, or takes no frame, for 60 seconds ends and is billed to that point; an API secret whose account may not use the avatar is refused (`AGENT_NOT_ENTITLED`) | set `platform :ios, '16.4'` and `IPHONEOS_DEPLOYMENT_TARGET = 16.4`; set `platform :osx, '14.0'` and `MACOSX_DEPLOYMENT_TARGET = 14.0`; an app that runs on macOS 14 bundles an ONNX Runtime built for macOS 14 (Homebrew's is built for macOS 15); use the API secret of the account that owns the avatar | | 2026-10-04 | essence2-android 0.9.5, expression2-android 0.6.1 | an app in the background for more than 60 s gets no avatar frames and its session ends (billed to the 60 s); the next frame while the app is visible starts a new session; an API secret is refused (`403 AGENT_NOT_ENTITLED`) for an agent its account may not render | nothing to change for an on-screen avatar; do not rely on frames while the app is in the background | | 2026-10-05 | Swift package 2.20.5 | the Swift package moved from GitHub to GitLab; versions up to 2.20.4 still download their binary frameworks from GitHub | change the package URL to `https://gitlab.com/bithuman/sdk/homebrew-bithuman` and update to 2.20.5; the package name (`homebrew-bithuman`) and your `.product(...)` lines stay the same | | 2026-10-04 | Flutter plugin 2.6.36 | macOS apps need macOS 26.0 (iOS stays 16.0); `BithumanEntitlementException` is a new exception from `load` and the installers; on Android, an Expression 2 `load` without `apiSecret` fails; the installers need `apiSecret` for an avatar that is not public | set `platform :osx, '26.0'` and `MACOSX_DEPLOYMENT_TARGET = 26.0`; catch `BithumanEntitlementException` ([Flutter errors](https://docs.bithuman.ai/platforms/flutter/errors#loading-an-avatar)); pass `apiSecret` | | 2026-10-04 | essence2-android 0.9.4 | a private avatar cached on the phone opens only for an API secret bitHuman has accepted for it; after the update, the first open of each cached avatar asks bitHuman once, so that open needs the network | nothing to change; another account on the same phone gets the download's refusal (`NOT_FOUND`) | | 2026-10-04 | expression2-android 0.6.0 | a private avatar cached on the phone opens only for an API secret bitHuman has accepted for it; after the update, the first open of each cached avatar asks bitHuman once, so that open needs the network | nothing to change; another account on the same phone gets the download's refusal (`404`) | | 2026-10-01 | REST API | bitHuman's text-to-speech service is retired: `POST /v1/tts`, `POST /v1/audio/speech`, `GET /v1/voices` and `/v1/studio/*` answer `410 ENDPOINT_RETIRED` | send your own audio (from any TTS provider or a recording) to the [talking video API](https://docs.bithuman.ai/build/talking-video); agent conversation voices and `/v1/agent/{code}/speak` are unchanged | | 2026-10-01 | essence2-android 0.9.0 | `Essence2Metering.basis` is ignored and always reads `"session"`: a file render bills its session time like any other session; `SelfHostMeter.BASIS_OUTPUT` no longer exists | delete any `basis = …` line; call `close()` right after the last frame of a file render | | 2026-09-27 | API | `POST /v1/realtime/ephemeral-token` is retired (`410 ENDPOINT_RETIRED`) | connect through the [Realtime relay](https://docs.bithuman.ai/api/realtime) (`wss://api.bithuman.ai/v1/realtime`) or `POST /v1/realtime/connect`; CLI 2.8.1+ already does | | 2026-09-24 | expression2-android 0.5.0 | `Expression2ModelStore.MODEL`, `CANON` and `IDLE` are no longer compile-time constants | read them at runtime; a `when` branch or annotation that used them as constants must change | | 2026-09-23 | Swift package 2.14.2 | `Expression2Engine.create` refuses without an API secret | call `Expression2Credential.set(_:)` or set `BITHUMAN_API_SECRET` | | 2026-09-23 | expression2-android 0.4.9 | `Expression2Avatar.create` refuses without an API secret | set `Expression2Metering.apiSecret` | | 2026-09-22 | CLI 2.7.0 | retired command spellings exit 2; `account --limit` defaults to 10 | use the [current names](https://docs.bithuman.ai/platforms/cli/reference#commands); pass `--limit 50` for the old window | | 2026-09-16 | bithuman 2.11.0 | the 3.x releases are withdrawn from PyPI | unpin 3.x; `pip install bithuman` | | 2026-09-16 | expression2-android 0.4.7 | `idleLoop` is an `Expression2IdleLoop`, not a `List` | call `idleLoop?.next(bitmap)` | | 2026-09-16 | Swift package 2.13.5 | `Expression2Engine.idleLoop` removed | use `idleNextPixelBuffer()` or `idle(into:)` | | 2026-09-15 | essence2-android 0.5.7 | the `ElevateFrames` constructor (legacy `ai.bithuman.elevate` package, kept for compatibility) drops its execution-provider argument | delete that argument | | 2026-09-14 | CLI 2.6.19 | `bithuman auth …` removed | `bithuman login`, `logout`, `account`, `token` | ## October 2026 ### `bithuman` 2.12.7 — 2026-10-20 - **Essence 2: the mouth is held closed while the avatar is idle.** After a reply, and at the start of a session while no audio is playing, an avatar whose resting photo has a closed mouth settles to that closed mouth within about half a second, instead of staying parted. When speech resumes, the mouth is released over two frames, before the first sound is heard, so there is no jump. Speech frames are unchanged. - **Release checks:** The 6 macOS wheels are byte-identical (sha256) to the measured build. The source distribution and the 5 Windows wheels match their 2026-10-16 build outputs. The 10 Linux wheels were re-checked on 2026-10-20 by re-running the release gates on the shipped files; every Linux-relevant gate passed. All 21 files on PyPI match the approved build hashes (sha256 read back from PyPI after upload). - **Action:** `pip install -U "bithuman[essence-2]"`. ### Swift package 2.22.2 — 2026-10-15 Tag `v2.22.2` on [gitlab.com/bithuman/sdk/homebrew-bithuman](https://gitlab.com/bithuman/sdk/homebrew-bithuman/-/tags). - **The legacy `bitHumanKit` product is retired and is no longer in the package.** `Expression2`, `Essence2Kit` and `Essence2` are unchanged. The `bitHumanKit` downloads for 2.4.0, 2.22.0 and 2.22.1 have been withdrawn and will not return, so a project that still depends on those versions fails to resolve until it updates ([bitHumanKit renamed](https://docs.bithuman.ai/resources/renamed)). - **Action:** `.package(url: "https://gitlab.com/bithuman/sdk/homebrew-bithuman", from: "2.22.2")`, use the `Expression2` or `Essence2Kit` product instead of `bitHumanKit`, then update packages. ### Billing — 2026-10-13 - **Cloud and Live:** In the bitHuman cloud and in bitHuman Live, credits pay for active session time, talking or idle, by the exact second. - **Your own devices or servers:** On your own devices or servers, current versions of the Essence 2 and Expression 2 SDKs, the bitHuman Python SDK and the bitHuman CLI charge credits only for the seconds the character is speaking, not for the time it waits. - **Versions:** Talking-only billing applies from these versions: bitHuman Python SDK 2.11.21, Swift SDK 2.14.2, Essence 2 Android 0.5.14, Expression 2 Android 0.4.9 and bitHuman CLI 2.7.2. Older versions are billed differently; contact support if you need the details for yours. - **Essence 1:** Running Essence 1 yourself with the bitHuman Python SDK 2.11.21 or later charges credits for the seconds the character is speaking. Older versions charge for connected time in whole minutes, with a one-minute minimum. - **Corrected:** the billing lines in the entries from 2026-09-23 to 2026-10-04 are superseded by this entry; each carries a note. Rates are unchanged ([pricing](https://docs.bithuman.ai/pricing)). - **Action:** none. ### Swift package 2.22.1 — 2026-10-11 Tag `v2.22.1` on [gitlab.com/bithuman/sdk/homebrew-bithuman](https://gitlab.com/bithuman/sdk/homebrew-bithuman/-/tags). - **Essence 2 full-body avatars that have their own idle clip play it on iPhone, iPad and Mac** (Essence 2 engine 1.0.6), the same idle clip design as the cloud. The clip is checked against its sha256 when it downloads; a set without a valid clip reports that the full body is still being prepared. - **Check `meteringRefusal` after `warmUp()`.** When the service refuses a session (for example 402: no credits left), `create` throws `meteringRefused`. If you construct the engine yourself and call `warmUp()`, it does not throw: it returns with `isReady == false`, renders no frames, and `engine.meteringRefusal` holds the service's message with the status. Check it right after `warmUp()` returns instead of waiting for `isReady` ([Swift reference](https://docs.bithuman.ai/platforms/swift/reference)). Behaviour is unchanged; this documents it. - **Action:** `.package(url: "https://gitlab.com/bithuman/sdk/homebrew-bithuman", from: "2.22.1")`, then update packages. ### Essence 2 cloud avatars — 2026-10-11 - Cloud-rendered Essence 2 avatars now run our newer Essence 2 engine, with steadier, more natural head movement, including while the avatar listens. Downloadable versions for devices and self-hosting follow as each one is ready; until then, downloads keep working as they do today. - Same avatar IDs, voices and prompts. Nothing to change in your code. - **Action:** none. If an avatar doesn't look right to you, contact support ([team@bithuman.ai](mailto:team@bithuman.ai) or Discord #support) with the avatar ID. ### Swift package 2.22.0 — 2026-10-10 Tag `v2.22.0` on [gitlab.com/bithuman/sdk/homebrew-bithuman](https://gitlab.com/bithuman/sdk/homebrew-bithuman/-/tags). - **Every product ships as a prebuilt binary**, downloaded from `downloads.bithuman.ai`. It includes the Essence 2 engine (1.0.4) and Expression 2 engine 2.20.7, the same engines as 2.21.7. - **Action:** `.package(url: "https://gitlab.com/bithuman/sdk/homebrew-bithuman", from: "2.22.0")`, then update packages. ### Swift package 2.21.7 — 2026-10-10 - Expression 2 engine 2.20.7, and the ONNX Runtime third-party notices ship with the package. - **Action:** none on its own; take 2.22.0. ### `bithuman` 2.12.6 — 2026-10-11 - Essence 2 full-body avatars that have their own idle clip play it in downloaded sets, with the same frames as the cloud. A set without its clip reports that the full body is still being prepared. - Memory: the decoded clip is held in memory (about 1.6 GB for a 10-second 1080p clip). Peak memory of a whole render on Linux (4 render workers) is about 3.9 GB for these avatars, against about 2.3 GB for other full-body avatars. - **Action:** `pip install -U "bithuman[essence-2]"`. ### `bithuman` 2.12.5 — 2026-10-11 - **Action:** `pip install -U "bithuman[essence-2]"`. ### `bithuman` 2.12.4 — 2026-10-11 - The same code as 2.12.3. Comments and private docstrings are removed from the shipped Python files at build time; the public API keeps its docstrings. - One error message (an expression-2 bundle with an unexpected `.tflite` member) is shorter; the exit code is the same. - **Action:** `pip install -U "bithuman[essence-2]"`. ### `bithuman` 2.12.3 — 2026-10-10 - The same code as 2.12.2, published for every platform: macOS (Apple silicon), Linux x86_64 and arm64, and Windows 11 x86_64, Python 3.10–3.14. - **Action:** take 2.12.4. ### Essence 2 naming — 2026-10-10 - There is one Essence 2. Earlier notes that say "the new Essence 2 engine" mean the current Essence 2 engine. Names in code, such as `E2UAvatar` and `E2UModelStore` on Android, keep their spelling. ### `essence2-android` 0.10.3 — 2026-10-10 - The public API is the same as 0.10.0: no class or method was added, removed or changed. The [Android reference](https://docs.bithuman.ai/platforms/android/reference) is now read from 0.10.3. - **Action:** none. 0.10.0 stays the recommended version; see [Android](https://docs.bithuman.ai/platforms/android). - Update (2026-10-11): adds head stabilisation (HeadCalm) to the new engine; known issue: idle keeps rendering at full rate. ### CLI 2.8.11 — 2026-10-09 Tag `cli-v2.8.11`. - **The new Essence 2 renders:** `bithuman render