Quickstart

An avatar inside your iPhone or iPad app

Needs

Xcode 26+ · Physical device · API secret

Models

Essence 2, Expression 2

1. Add the Swift package

   Package.swift Copy

   .package(url: "https://gitlab.com/bithuman/sdk/homebrew-bithuman", from: "2.22.1")
   // then: .product(name: "Expression2", package: "homebrew-bithuman")

2. Download the sample avatar

   Shell Copy

   curl -fL -o A23WJF0199.imx "https://api.bithuman.ai/v1/agent/A23WJF0199/model/download?model=expression-2"

   The iOS page also fetches the shared engine and a 16 kHz speech clip.

3. Feed audio, draw frames

   Swift Copy

   // excerpt: the core loop; the complete first frame is on the iOS page
   import Expression2
   
   Expression2Credential.set(apiSecret)
   let engine = try Expression2Engine.create(
       avatarContainer: avatarURL, sharedEngineContainer: sharedEngineURL, stagingDir: stagingURL)
   engine.feed(samples)      // [Float], 16 kHz mono
   engine.flushTail()        // end of the reply
   for await frame in engine.frames(audioClock: { played() }) {
       show(frame.bgr, frame.width, frame.height)
       if frame.endsReply { break }
   }

An avatar on your Mac

Needs

Apple silicon · Xcode 26+ · API secret

Models

Essence 2, Expression 2

1. Clone the macOS example

   Shell Copy

   git clone https://gitlab.com/bithuman/sdk/bithuman-examples.git
   cd bithuman-examples/swift/macos-expression2
   ./setup.sh

2. Run it

   Shell Copy

   export BITHUMAN_API_SECRET="<your API secret>"
   swift run -c release MacOSExpression2

An avatar inside your Android app

Needs

Physical device · JDK 17 · API secret

Models

Essence 2, Expression 2

1. Add the repository and the dependency

   Gradle Copy

   // excerpt: settings.gradle.kts and app/build.gradle.kts; the full setup is on the Android page
   // settings.gradle.kts
   dependencyResolutionManagement {
       repositories {
           google()
           mavenCentral()
           exclusiveContent {   // ai.bithuman resolves from bitHuman's repository only
               forRepository { maven { url = uri("https://maven.bithuman.ai") } }
               filter { includeGroup("ai.bithuman") }
           }
       }
   }
   // app/build.gradle.kts
   android {
       defaultConfig { ndk { abiFilters += "arm64-v8a" } }
       packaging { jniLibs { useLegacyPackaging = true } }   // required
   }
   dependencies {
       implementation("ai.bithuman:expression2-android:0.6.2")
   }

2. Keep the API secret out of your source

   Put bithuman.apiSecret=… in your project's local.properties (git-ignored), or export BITHUMAN_API_SECRET before you build; the Gradle block on the Android page reads it into BuildConfig.

3. Feed audio, pull frames

   Kotlin Copy

   // excerpt: off the main thread; pcm16k is 16 kHz mono float
   Expression2Credential.set(BuildConfig.BITHUMAN_API_SECRET)
   val model = Expression2ModelStore(context).fetch("A23WJF0199")   // first run only
   Expression2Avatar.create(context, model, Expression2Options()).use { avatar ->
       val frame = avatar.newFrameBitmap()
       avatar.feed(pcm16k)
       avatar.flushTail()
       while (avatar.hasPendingTail || avatar.queuedFrames > 0) {
           if (avatar.pull(frame) != null) show(frame) else Thread.sleep(10)
       }
   }

An avatar inside your Flutter app

Needs

Physical device · Dart 3.11.5+ · API secret

Models

Essence 2, Expression 2

1. Clone the example app

   Shell Copy

   git clone https://gitlab.com/bithuman/sdk/bithuman-examples.git
   cd bithuman-examples/app/avatar_chat
   flutter pub get

2. Run it on your phone

   Shell Copy

   flutter run --release --dart-define=AGENT_CODE=A23WJF0199

3. Add the plugin to your own app

   pubspec.yaml Copy

   dependencies:
     bithuman:
       git:
         url: https://gitlab.com/bithuman/sdk/homebrew-bithuman.git
         path: packages/flutter-plugin
         ref: flutter-plugin-v2.6.40

   Then, in android/app/build.gradle.kts, set minSdk = 29, ndk { abiFilters += "arm64-v8a" } and packaging { jniLibs { useLegacyPackaging = true } }; the Flutter page's Install section shows the block.

Render from Python

Needs

Python 3.10+ · API secret

Models

Essence 2, Expression 2

1. Install

   Shell Copy

   python3 -m venv .venv && source .venv/bin/activate
   pip install "bithuman[expression-2]"

2. Download the sample avatar and speech

   Shell Copy

   export BITHUMAN_API_SECRET="<your API secret>"
   curl -fL -o wise-pup.imx "https://api.bithuman.ai/v1/agent/A23WJF0199/model/download?model=expression-2"
   curl -fsSLo speech.wav https://docs.bithuman.ai/samples/speech.wav

3. Render

   Python Copy

   import bithuman
   
   with bithuman.open("wise-pup.imx") as avatar:
       frames = [image for image in avatar.render("speech.wav")]
   print(len(frames), "frames of", frames[0].shape)
   # → 300 frames of (720, 416, 3)

An avatar from your terminal

Needs

macOS or Linux · ffmpeg

Models

Essence 2, Expression 2

1. Install the CLI

   Shell Copy

   # macOS: brew tap bithuman/bithuman https://gitlab.com/bithuman/sdk/homebrew-bithuman && brew install bithuman/bithuman/bithuman-cli
   curl -fsSL https://install.bithuman.ai | sh

2. Sign in

   Shell Copy

   bithuman login

3. Render a talking video

   Shell Copy

   curl -fsSLo speech.wav https://docs.bithuman.ai/samples/speech.wav
   bithuman render wise-pup speech.wav -o out.mp4
   # → out.mp4: 416×720, 300 frames, 15.0 s

   bithuman run wise-pup opens a live conversation instead.

A face for your LiveKit voice agent

Needs

A LiveKit project · API secret

Models

Essence 2, Expression 2

1. Install

   Shell Copy

   pip install "livekit-agents[openai,silero]" livekit-plugins-bithuman python-dotenv

2. Set the credentials

   Shell Copy

   export BITHUMAN_MASTER_SECRET="<your API secret>"
   export BITHUMAN_AGENT_ID=A23WJF0199
   export LIVEKIT_URL=wss://your-project.livekit.cloud
   export LIVEKIT_API_KEY=… LIVEKIT_API_SECRET=…
   export OPENAI_API_KEY=…

3. Run the worker

   Shell Copy

   python agent.py dev
   # → join the room from the LiveKit Agents Playground; the avatar appears and answers

   Copy agent.py, a complete worker, from the LiveKit page.

Call the REST API

Needs

API secret

Models

Essence 2, Expression 2

1. Check your API secret

   Shell Copy

   export BITHUMAN_API_SECRET="<your API secret>"
   curl -s -X POST https://api.bithuman.ai/v1/validate -H "api-secret: $BITHUMAN_API_SECRET"
   # → {"valid":true}

2. Render a sample agent speaking your audio

   Shell Copy

   curl -s -X POST https://api.bithuman.ai/v1/video/generate \
     -H "api-secret: $BITHUMAN_API_SECRET" -H "Content-Type: application/json" \
     -d '{"model": "expression-2", "agent_code": "A23WJF0199", "input": {"type": "audio", "audio_url": "https://docs.bithuman.ai/samples/speech-16k-short.wav"}}'
   # → {"success": true, "job_id": "vid_…", "status": "processing"}

A kiosk, fully offline

Needs

Business or Enterprise plan · Expression 2 on Linux x86_64; Essence 1 on Linux (x86_64, ARM64) and Apple silicon Macs; Essence 2 later

Models

Expression 2, Essence 1

Offline license is only available to Business and Enterprise clients who want to run realtime avatars completely locally, off the internet — e.g. kiosks, trade shows, ATM machines, embedded screens. Linux and macOS computers (Apple silicon); bought in the Console or through sales.