---
title: "Create a video"
method: POST
path: "/v1/videos"
tags: ["Videos"]
---

# Create a video

`POST /v1/videos`

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).

## Request body

- CreateVideoRequest — Provide a `ref_image` plus exactly one driving input: `input` (audio-to-video) or `input_tts` (text-to-video).
  - `model` 'higgs-avatar' — Avatar model ID / public alias.
  - `ref_image` string, 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.
  - `input` string, 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`.
  - `input_tts` CreateSpeechRequest
    - `input` string, required — Text to convert to speech. May contain inline tags. Inputs longer than 5000 characters return a 400 `input_too_long`.
    - `model` 'higgs-tts-3' — TTS model ID / public alias. Resolved to the served model server-side.
    - `voice` string — Preset voice name or custom voice ID. Mutually exclusive with `ref_audio` / `ref_text` when explicitly provided.
    - `response_format` 'mp3' | 'opus' | 'pcm' | 'wav' | 'aac' | 'flac' — Output audio format. Streaming requires `pcm`.
    - `stream` boolean — If true, stream raw PCM chunks as they are decoded. Requires `response_format` to be `pcm`. Speed adjustment is not supported when streaming.
    - `ref_audio` string, nullable — Inline reference audio for one-off cloning: an http(s) URL, data URI, or base64-encoded raw audio bytes. Supported formats: AAC, WAV, MP3, FLAC, OPUS. Inline (base64 / data-URI) payloads: max 10 MB.
    - `ref_text` string, nullable — Recommended transcript of `ref_audio`.
  - `size` '640x640' | '640x480' | '480x640' — Output video size (WxH): square `640x640`, landscape `640x480`, or portrait `480x640`.

## Response `200`

The created Video object.

- Video — A video generation job (the create / retrieve response).
  - `id` string — Video ID, e.g. `video_8a1f...`.
  - `object` 'video'
  - `model` string
  - `status` 'queued' | 'in_progress' | 'completed' | 'failed' — Job status.
  - `progress` integer — Completion percentage (0–100).
  - `size` string — Output size (WxH), e.g. `640x640`.
  - `created_at` integer — Unix timestamp (seconds).
  - `error` string, nullable — Error message when `status` is `failed`.

## Other responses

- `400` — Invalid request (e.g. `invalid_image_format`, `invalid_size`, `audio_too_long`, `empty_input`, `input_too_long`).
- `401` — Missing or invalid API key.
- `404` — Unknown avatar model (`model_not_found`).
- `413` — Inline `ref_image` over the 10 MB cap (`payload_too_large`).
- `422` — Malformed body (e.g. neither or both of `input` / `input_tts`).
- `429` — Rate limited, or all replicas busy (`all_replicas_busy`); retry after `Retry-After`.

---

[API](https://skmtc.dev/boson/apis/boson-ai-api.md) · [All operations](https://skmtc.dev/boson/apis/boson-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/boson/boson-ai-api/revisions/1f9baf8f56ce/schema)