bithuman

bitHuman Go SDK

Go SDK for the bitHuman Real-Time Avatar Animation API.

bitHuman creates digital avatars that lip-sync to audio in real time. Audio in, animated video out at 25 FPS.

Installation

go get github.com/plexusone/bithuman-go

Quick Start

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/plexusone/bithuman-go"
    "github.com/plexusone/bithuman-go/api"
)

func main() {
    // Create client (uses BITHUMAN_API_KEY env var if not specified)
    client, err := bithuman.NewClient(
        bithuman.WithAPIKey(os.Getenv("BITHUMAN_API_KEY")),
    )
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    // Validate credentials
    resp, err := client.Validate(ctx)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Credentials valid: %v\n", resp.Valid)

    // List agents
    agents, err := client.Agents().List(ctx, api.ListAgentsParams{})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Found %d agents\n", len(agents.Agents))

    // Create a real-time session
    session, err := client.Sessions().Create(ctx, &api.CreateSessionRequest{
        AgentID: "your-agent-id",
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Session created: %s\n", session.ID)
    fmt.Printf("LiveKit URL: %s\n", session.LivekitURL.Value)
}

Features

• 🤖 Agents: Create, manage, and interact with avatar agents
• 📡 Sessions: Real-time conversation sessions with LiveKit integration
• 🗣️ TTS: Text-to-speech synthesis with 30+ language support
• 🎬 Videos: Generate talking video MP4 files
• 📁 Files: Upload images, video, audio, and documents
• 🔔 Webhooks: Event notifications for async operations
• 🔌 OmniAvatar Adapter: Use bitHuman render behind the provider-agnostic OmniAvatar interfaces

Environment Variables

API Reference

Client Options

client, _ := bithuman.NewClient(
    bithuman.WithAPIKey("your-api-key"),
    bithuman.WithBaseURL("https://api.bithuman.ai"),  // Optional
    bithuman.WithTimeout(60 * time.Second),           // Optional
    bithuman.WithHTTPClient(customClient),            // Optional
)

Services

Low-Level API Access

For endpoints not covered by the high-level services:

apiClient := client.API()
// Use ogen-generated methods directly

LiveKit Integration

bitHuman sessions can connect to LiveKit for real-time WebRTC streaming:

session, _ := client.Sessions().Create(ctx, &api.CreateSessionRequest{
    AgentID:      "your-agent-id",
    LivekitURL:   api.NewOptString("wss://your-livekit-server"),  // Optional external LiveKit
    LivekitToken: api.NewOptString("your-token"),                  // Optional external token
})

// Use session.LivekitURL and session.LivekitToken to connect

Development

Regenerating the API Client

The SDK uses ogen to generate Go code from the OpenAPI specification:

# Install ogen
go install github.com/ogen-go/ogen/cmd/ogen@latest

# Regenerate API client
./generate.sh

Running Tests

go test ./...

Linting

golangci-lint run

OmniAvatar Integration

The omniavatar subpackage implements the provider-agnostic OmniAvatar render interfaces (render.Provider, render.AudioUploader) on top of this SDK, so bitHuman video generation can be used behind the OmniAvatar abstraction. It depends only on omniavatar-core.

import bithumanomni "github.com/plexusone/bithuman-go/omniavatar"

p, err := bithumanomni.NewRenderProvider(bithumanomni.RenderConfig{
    APIKey: os.Getenv("BITHUMAN_API_KEY"),
})

Provider adapters live in the provider SDK repos so all bitHuman-specific knowledge stays here; the real-time live adapter, which requires LiveKit, lives in the batteries-included omniavatar package.

Related

• bitHuman Documentation
• bitHuman API Reference
• LiveKit - Real-time WebRTC platform

License

MIT License - see LICENSE for details.