Videos

Create a video

Changed on Nov 3, 2026

Create an avatar talking-head video (async). Returns the Video object with status: "queued"; poll GET /v1/videos/{video_id} and download the rendered MP4 from GET /v1/videos/{video_id}/content. Provide a reference image plus exactly one driving input — input (audio-to-video) or input_tts (text-to-video). The body may be JSON or multipart/form-data (upload ref_image / input as raw files).

post/v1/videos

Request

Base URL
https://api.boson.ai
URL
https://api.boson.ai/v1/videos
Auth
HTTP bearer

Request body

model'higgs-avatar'

Avatar model ID / public alias.

ref_imagestring required

Reference image (the face to animate): an http(s) URL, data URI, or base64-encoded raw image bytes. Supported formats: PNG, JPEG, WEBP. Inline (base64 / data-URI) payloads: max 10 MB.

inputstring nullable

Audio-to-video: the driving speech audio as an http(s) URL, data URI, or base64-encoded raw audio bytes. Supported formats: AAC, WAV, MP3, FLAC, OPUS. Max duration: 60 s (it sets the output video length). Provide exactly one of input / input_tts.

size'640x640' | '640x480' | '480x640'

Output video size (WxH): square 640x640, landscape 640x480, or portrait 480x640.

Example request

{
  "input_tts": {
    "input": "Hello, this is a test."
  }
}

Response

The created Video object.

idstring

Video ID, e.g. video_8a1f....

object'video'

modelstring

status'queued' | 'in_progress' | 'completed' | 'failed'

Job status.

progressinteger

Completion percentage (0–100).

sizestring

Output size (WxH), e.g. 640x640.

created_atinteger

Unix timestamp (seconds).

errorstring nullable

Error message when status is failed.

Example response

{
  "id": "video_8a1f2c3d4e5f6a7b8c9d0e1f"
}

Changes

Nov 3, 202668bf7c248c4c Revision changes
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  added the new optional request property /////
- info
  the ///// request property's maxLength was increased from 5000 to 50000
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status

Operation history