Overview

Generate talking-head video from a still image and a driving voice or text.

Higgs Avatar turns a single still image into talking-head video with lip sync, head motion, and expression aligned to the driving voice.

Model

higgs-avatar

Video jobs endpoint (POST)

https://api.boson.ai/v1/videos

Streaming endpoint (POST)

https://api.boson.ai/v1/videos/stream

What you can build

Capability	Input	Output
Audio-driven video	Still image and an existing audio clip	Rendered MP4 or fragmented-MP4 stream
Text-driven video	Still image and a Higgs TTS request	Rendered MP4 or fragmented-MP4 stream
Instant avatar cloning	One PNG, JPEG, or WebP image	A new talking-head performance without avatar training

“Streaming” describes how generated video is delivered. Higgs Avatar does not manage a persistent, two-way conversation.

Quickstart

This quickstart creates an audio-driven video from Boson-hosted sample assets. A successful run saves the finished result as out.mp4.

Before you begin

You need:

• A Boson API key stored in BOSON_API_KEY
• cURL and jq, Python 3.10 with requests, or Node.js 18 or later

export BOSON_API_KEY="bai-xxxx"

Create, wait, and download

Avatar video generation is asynchronous:

1. POST /v1/videos creates a job and returns a Video object with an id.
2. GET /v1/videos/{video_id} reports progress until the job is completed or failed.
3. GET /v1/videos/{video_id}/content downloads the rendered MP4.

cURL

# 1. Create the video.
VIDEO_ID=$(curl -fsS https://api.boson.ai/v1/videos \
  -H "Authorization: Bearer $BOSON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "higgs-avatar",
    "ref_image": "https://docs.boson.ai/public/avatar/sample.jpg",
    "input": "https://docs.boson.ai/public/audio/sample.mp3",
    "size": "640x640"
  }' | jq -er .id)

# 2. Wait for the Video object to complete.
while true; do
  VIDEO=$(curl -fsS "https://api.boson.ai/v1/videos/$VIDEO_ID" \
    -H "Authorization: Bearer $BOSON_API_KEY")
  STATUS=$(printf '%s' "$VIDEO" | jq -r .status)

  [ "$STATUS" = "completed" ] && break
  if [ "$STATUS" = "failed" ]; then
    printf '%s' "$VIDEO" | jq .error >&2
    exit 1
  fi

  sleep 2
done

# 3. Download the rendered MP4.
curl -fsS "https://api.boson.ai/v1/videos/$VIDEO_ID/content" \
  -H "Authorization: Bearer $BOSON_API_KEY" \
  --output out.mp4

The integration is working when the job reaches completed and out.mp4 opens in your video player.

Job states

GET /v1/videos/{video_id} returns the current Video object.

Status	Meaning	Client action
queued	The job is waiting to start	Continue polling with backoff
in_progress	Video generation is running	Continue polling
completed	The MP4 is ready	Download content
failed	Generation stopped	Inspect the Video object’s error

GET /v1/videos/{video_id}/content downloads the rendered MP4 after completion. It returns 404 while content is not yet available.

Next steps

Choose inputs and limits

Generate from audio or text, upload local files, and check supported sizes and limits.

Stream generated video

Start playback before the complete video is rendered with fragmented MP4.

Avatar API reference

Look up the generated video endpoints and field-level request details.

Try it in the playground

The fastest way to preview the model is the Boson playground. Pick an avatar, paste text, and press play.

When to use another Higgs API

Need generated speech only?

Use Higgs TTS 3 when your output is audio and you do not need a talking-head video.

Need a live conversation?

Use Higgs Realtime for a persistent, interruptible audio or text session with tool calling.