Higgs Avatar

Features

Instant avatar cloning — zero-shot from a single still image.
Voice- or text-driven — drive the avatar with an existing audio clip, or generate the driving voice from text in the same request with the TTS API (including voice cloning).
Streaming delivery — a dedicated streaming endpoint returns the video as a fragmented-MP4 byte stream, so playback can start before the clip is complete.

Try it in the playground

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

Generate avatars with the API

Higgs Avatar is in public preview. API usage is currently free and rate-limited while we improve reliability, latency, and model quality.

Set the API key in your shell for the current session:

export BOSON_API_KEY=bai-xxxx

Avatar video generation API is asynchronous:

POST /v1/videos creates a job and returns a Video object with video_id.
GET /v1/videos/{video_id} polls the Video object until status is "completed".
GET /v1/videos/{video_id}/content downloads the rendered MP4.

Every request needs a ref_image (the still photo the avatar is generated from) plus exactly one driving input: an input audio clip (audio-to-video) or an input_tts text request (text-to-video).

Drive with an audio clip

Pass the driving voice in input (an http(s) URL, data URI, or base64). The avatar lip-syncs and moves to that audio. The driving audio sets the video length and is capped at 60 s.

# 1. Create the video — returns {"id": "video_…", "object": "video", "status": "queued", …}
VIDEO=$(curl -s 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 -r .id)

# 2. Poll until completed.
until [ "$(curl -s "https://api.boson.ai/v1/videos/$VIDEO" \
  -H "Authorization: Bearer $BOSON_API_KEY" | jq -r .status)" = "completed" ]; do sleep 2; done

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

import os
import time
import requests

BASE = "https://api.boson.ai/v1/videos"
HEADERS = {"Authorization": f"Bearer {os.environ['BOSON_API_KEY']}"}

# 1. Create
video = requests.post(
    BASE,
    headers=HEADERS,
    json={
        "model": "higgs-avatar",
        "ref_image": "https://docs.boson.ai/public/avatar/sample.jpg",
        "input": "https://docs.boson.ai/public/audio/sample.mp3",
        "size": "640x640",
    },
).json()

# 2. Poll the Video object until it is completed.
while True:
    v = requests.get(f"{BASE}/{video['id']}", headers=HEADERS).json()
    if v["status"] == "completed":
        break
    if v["status"] == "failed":
        raise RuntimeError(v.get("error"))
    time.sleep(2)

# 3. Download the rendered MP4.
content = requests.get(f"{BASE}/{video['id']}/content", headers=HEADERS)
with open("out.mp4", "wb") as f:
    f.write(content.content)

import { writeFile } from "node:fs/promises";

const base = "https://api.boson.ai/v1/videos";
const headers = {
  Authorization: `Bearer ${process.env.BOSON_API_KEY}`,
  "Content-Type": "application/json",
};

// 1. Create the video.
const createRes = await fetch(base, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "higgs-avatar",
    ref_image: "https://docs.boson.ai/public/avatar/sample.jpg",
    input: "https://docs.boson.ai/public/audio/sample.mp3",
    size: "640x640",
  }),
});
const video = await createRes.json();

// 2. Poll the Video object until it is completed.
while (true) {
  const pollRes = await fetch(`${base}/${video.id}`, {
    headers: { Authorization: `Bearer ${process.env.BOSON_API_KEY}` },
  });
  const status = await pollRes.json();
  if (status.status === "completed") break;
  if (status.status === "failed") throw new Error(JSON.stringify(status.error));
  await new Promise((resolve) => setTimeout(resolve, 2000));
}

// 3. Download the rendered MP4.
const contentRes = await fetch(`${base}/${video.id}/content`, {
  headers: { Authorization: `Bearer ${process.env.BOSON_API_KEY}` },
});
await writeFile("out.mp4", Buffer.from(await contentRes.arrayBuffer()));

Drive with text

Skip the audio clip and synthesize the driving voice from text in the same request: put a speech request under input_tts (the same body as POST /v1/audio/speech). Pick a speaker with voice, or clone one with ref_audio. Provide exactly one of input or input_tts.

curl -s 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_tts": {
      "model": "higgs-tts-3",
      "input": "Hello, world.",
      "voice": "default"
    },
    "size": "640x640"
  }'

import os
import requests

resp = requests.post(
    "https://api.boson.ai/v1/videos",
    headers={"Authorization": f"Bearer {os.environ['BOSON_API_KEY']}"},
    json={
        "model": "higgs-avatar",
        "ref_image": "https://docs.boson.ai/public/avatar/sample.jpg",
        "input_tts": {
            "model": "higgs-tts-3",
            "input": "Hello, world.",
            "voice": "default",
        },
        "size": "640x640",
    },
)
resp.raise_for_status()
print(resp.json())

const res = await fetch("https://api.boson.ai/v1/videos", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOSON_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "higgs-avatar",
    ref_image: "https://docs.boson.ai/public/avatar/sample.jpg",
    input_tts: {
      model: "higgs-tts-3",
      input: "Hello, world.",
      voice: "default",
    },
    size: "640x640",
  }),
});

console.log(await res.json());

Upload local files

Send the body as multipart/form-data to upload a local ref_image (and input audio) directly, with no base64 encoding. input_tts is passed as a JSON-string field.

curl -s https://api.boson.ai/v1/videos \
  -H "Authorization: Bearer $BOSON_API_KEY" \
  -F model=higgs-avatar \
  -F size=480x640 \
  -F [email protected] \
  -F [email protected]

import os
import requests

with open("face.png", "rb") as ref_image, open("voice.wav", "rb") as input_audio:
    resp = requests.post(
        "https://api.boson.ai/v1/videos",
        headers={"Authorization": f"Bearer {os.environ['BOSON_API_KEY']}"},
        data={
            "model": "higgs-avatar",
            "size": "480x640",
        },
        files={
            "ref_image": ref_image,
            "input": input_audio,
        },
    )

resp.raise_for_status()
print(resp.json())

import { readFile } from "node:fs/promises";

const form = new FormData();
form.set("model", "higgs-avatar");
form.set("size", "480x640");
form.set("ref_image", new Blob([await readFile("face.png")]), "face.png");
form.set("input", new Blob([await readFile("voice.wav")]), "voice.wav");

const res = await fetch("https://api.boson.ai/v1/videos", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOSON_API_KEY}`,
  },
  body: form,
});

console.log(await res.json());

Retrieve and download

GET /v1/videos/{video_id} returns the Video object — status (queued → in_progress → completed | failed), progress, size, error. Always JSON.
GET /v1/videos/{video_id}/content downloads the rendered MP4 bytes once the video is completed (a 404 until then).

Sizes

size is one of three presets — pick the aspect ratio that matches your reference image so the subject is not cropped:

`size`	Aspect	Use for
`640x640`	1:1	Square (default)
`640x480`	4:3	Landscape
`480x640`	3:4	Portrait

Limits

Field	Limit
`ref_image`	PNG / JPEG / WEBP; inline (base64 / data URI) ≤ 10 MB (URLs are not capped)
`input` (audio)	AAC / WAV / MP3 / FLAC / OPUS; ≤ 60 s (it sets the video length)
`input_tts` (text)	≤ 5000 characters

A request that violates a limit returns a 4xx with an error code — e.g. invalid_image_format, payload_too_large, audio_too_long, input_too_long, invalid_size, or model_not_found.

Stream the video

For live playback, POST the same body to /v1/videos/stream (a non-standard extension). The response body is the fragmented MP4 byte stream — frames arrive as they are generated, so playback can start before the full clip is ready (append the chunks to an MSE SourceBuffer in the browser, or write them to a .mp4 file). The video id comes back in the X-Video-Id header, and the full MP4 is stored too — so a later GET /v1/videos/{video_id}/content still works.

import os
import requests

payload = {
    "model": "higgs-avatar",
    "ref_image": "https://docs.boson.ai/public/avatar/sample.jpg",
    "input": "https://docs.boson.ai/public/audio/sample.mp3",
    "size": "640x640",
}

with open("out.mp4", "wb") as f, requests.post(
    "https://api.boson.ai/v1/videos/stream",
    headers={"Authorization": f"Bearer {os.environ['BOSON_API_KEY']}"},
    json=payload,
    stream=True,
    timeout=300,
) as r:
    r.raise_for_status()
    video_id = r.headers["X-Video-Id"]
    for chunk in r.iter_content(chunk_size=8192):
        if chunk:                       # first non-empty chunk ≈ time-to-first-frame
            f.write(chunk)

import { writeFile } from "node:fs/promises";

const payload = {
  model: "higgs-avatar",
  ref_image: "https://docs.boson.ai/public/avatar/sample.jpg",
  input: "https://docs.boson.ai/public/audio/sample.mp3",
  size: "640x640",
};

const res = await fetch("https://api.boson.ai/v1/videos/stream", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOSON_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});

if (!res.ok || !res.body) throw new Error(`HTTP ${res.status}`);

const chunks: Uint8Array[] = [];
const reader = res.body.getReader();
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  if (value) chunks.push(value);
}

await writeFile("out.mp4", Buffer.concat(chunks));
console.log(`video id: ${res.headers.get("X-Video-Id")}`);

API reference

Full request body (JSON):

{
  "model": "higgs-avatar",            // avatar model ID

  "ref_image": "URL | data URI | base64",  // the face to animate (PNG/JPEG/WEBP, inline ≤ 10 MB)

  // Driving signal — provide exactly one of `input` or `input_tts`.
  "input": "URL | data URI | base64",    // audio-to-video: the driving voice (AAC/WAV/MP3/FLAC/OPUS, ≤ 60 s)
  "input_tts": {                         // …or text-to-video: synthesize the voice from text
    "model": "higgs-tts-3",
    "input": "Text to speak.",
    "voice": "default"                   // preset speaker, or clone with `ref_audio`
  },

  "size": "640x640"                      // "640x640" | "640x480" | "480x640"
}

See the API reference for field details and additional options.

Get Started

Text-to-Speech

Talking Avatar

Realtime Interaction

Higgs Avatar

Features

Try it in the playground

Generate avatars with the API

Drive with an audio clip

Drive with text

Upload local files

Retrieve and download

Sizes

Limits

Stream the video

API reference

​Features

​Try it in the playground

​Generate avatars with the API

​Drive with an audio clip

​Drive with text

​Upload local files

​Retrieve and download

​Sizes

​Limits

​Stream the video

​API reference

Features

Try it in the playground

Generate avatars with the API

Drive with an audio clip

Drive with text

Upload local files

Retrieve and download

Sizes

Limits

Stream the video

API reference