# AI clipping
Source: https://heygen-1fa696a7.mintlify.app/ai-clipping

Turn a long-form video into short, ready-to-share highlight clips with the HeyGen AI Clipping API — the model picks the best moments, cuts them to your target durations, and scores each clip's virality.

<img alt="" />

## Create a Clip Job

* Endpoint: [`POST /v3/ai-clipping`](/reference/create-ai-clipping)
* Purpose: Start a clipping job for a source video. Returns an `ai_clipping_id` to poll.

### Quick Example

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/ai-clipping" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video": { "type": "url", "url": "https://example.com/interview.mp4" },
    "title": "Founder interview",
    "output_settings": {
      "duration_types": ["30", "60"],
      "aspect_ratio": "portrait",
      "captions": false,
      "prompt": "Pull the moments where the founder talks about pricing and growth."
    }
  }'
```

```json Response theme={null}
{
  "data": {
    "ai_clipping_id": "edf8d2c44ba441b89f395072b3ef7e34"
  }
}
```

### Request Body

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `video` | object | Yes | — | Source video. Provide as `{ "type": "url", "url": "https://..." }` or `{ "type": "asset_id", "asset_id": "..." }` (from [`POST /v3/assets`](/reference/upload-asset) — see [Upload Assets](/docs/upload-assets)). |
| `title` | string | No | — | Title for the job. Defaults to the source video's title when omitted. |
| `input_language` | string | No | auto-detect | ISO-639-1 source language code (e.g. `en`, `es`). Omit to auto-detect. |
| `output_settings` | object | No | — | Configuration for the produced clips — see [Output settings](#output-settings). |
| `callback_url` | string | No | — | [Webhook](/docs/webhooks) URL — receives a POST when the job completes or fails. |
| `callback_id` | string | No | — | Arbitrary ID echoed back in the webhook payload. |

### Output settings

| Field | Type | Required | Default | Description |
| - | - | - | - | - |
| `duration_types` | array of strings | No | — | Target clip durations to produce: `"30"`, `"60"`, `"180"`, or `"long"` (1–4 entries). Each duration produces a separate clip. |
| `aspect_ratio` | string | No | `portrait` | Framing for all produced clips: `portrait` (9:16, social-ready), `landscape` (16:9), or `square` (1:1). |
| `captions` | boolean | No | `true` | Captions are burned into the clips by default. Set `false` for clean, caption-free footage — as in the example above. |
| `caption_style` | string | No | — | Named caption style preset (e.g. `classic`, `bold`) when captions are on. Omit for the default style. |
| `prompt` | string | No | — | Editorial guidance for the highlight model — which speaker, what topics (max 500 chars). When omitted, the model selects highlights on its own. |

<Tip>
  Want captions on some clips and clean footage on others? Captions are a per-job setting, so submit two jobs from the same source `video` — one with `"captions": false` — and pick per platform. To style burned-in captions on other footage, `caption_style` presets like `classic` and `bold` keep the look consistent.
</Tip>

## Get a Clip Job

* Endpoint: [`GET /v3/ai-clipping/{job_id}`](/reference/get-ai-clipping)
* Purpose: Fetch a clip job's live status and, as they render, its finished clips.

### Quick Example

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/ai-clipping/edf8d2c44ba441b89f395072b3ef7e34" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

### Path Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `job_id` | string | Yes | Unique job identifier returned by `POST /v3/ai-clipping` as `ai_clipping_id`. |

### Response

```json theme={null}
{
  "data": {
    "id": "edf8d2c44ba441b89f395072b3ef7e34",
    "title": "Founder interview",
    "status": "completed",
    "input_language": "en",
    "source_duration": 1264.4,
    "progress": 100,
    "clips": [
      {
        "id": "92799db89cdf444eb40a3d3db4378f4c",
        "status": "completed",
        "title": "Why we changed our pricing",
        "duration_seconds": 26.4,
        "aspect_ratio": "portrait",
        "virality_score": 65,
        "thumbnail_url": "https://resource2.heygen.ai/video_repurpose/.../1280x720.jpeg",
        "video_url": "https://resource2.heygen.ai/video_repurpose/.../1280x720.mp4?..."
      }
    ],
    "created_at": 1784649990
  }
}
```

### Response Fields

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique job identifier. |
| `title` | string or null | Display title for the job. |
| `status` | string | Job lifecycle status: `pending`, `running`, `completed`, `failed`, or `cancelled`. |
| `input_language` | string or null | Detected or supplied source language code. |
| `source_duration` | number or null | Duration of the source video in seconds. |
| `progress` | integer | Approximate progress (0–100). `100` when all clips are completed. |
| `clips` | array | Produced clips. Populates as each clip renders — empty until the first one finishes. |
| `clips[].id` | string | Unique clip identifier. |
| `clips[].status` | string | Per-clip status: `pending`, `completed`, or `failed`. |
| `clips[].title` | string or null | Model-generated clip title. |
| `clips[].duration_seconds` | number or null | Final clip length in seconds. Populated when the clip completes. |
| `clips[].aspect_ratio` | string or null | Framing of the finished clip. |
| `clips[].virality_score` | integer or null | Model-predicted virality score (0–100). |
| `clips[].thumbnail_url` | string or null | Pre-signed thumbnail URL. |
| `clips[].video_url` | string or null | Pre-signed MP4 download URL. |
| `callback_id` | string or null | Client-provided callback ID. |
| `created_at` | integer | Unix timestamp (seconds) of job creation. |
| `failure_message` | string or null | Error description. Only present when status is `failed`. |

<Note>
  Each `video_url` and `thumbnail_url` is a pre-signed link with a limited lifetime. Download the file (or hand the URL to a downstream step) soon after the job completes rather than caching it for later.
</Note>

## List Clip Jobs

* Endpoint: [`GET /v3/ai-clipping`](/reference/list-ai-clipping)
* Purpose: List clip jobs with cursor-based pagination.

### Quick Example

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/ai-clipping?limit=10" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

### Query Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `limit` | integer | No | `10` | Results per page. |
| `token` | string | No | — | Opaque cursor token. Pass the `next_token` from a prior response to fetch the next page. |

### Response

```json theme={null}
{
  "data": [
    {
      "id": "edf8d2c44ba441b89f395072b3ef7e34",
      "title": "Founder interview",
      "status": "completed",
      "progress": 100,
      "created_at": 1784649990
    }
  ],
  "has_more": false,
  "next_token": null
}
```

The list endpoint reports coarse `progress`; poll [`GET /v3/ai-clipping/{job_id}`](#get-a-clip-job) for live in-flight progress on a specific job.

## Delete a Clip Job

* Endpoint: [`DELETE /v3/ai-clipping/{job_id}`](/reference/delete-ai-clipping)
* Purpose: Permanently delete a clip job and its clips.

### Quick Example

```bash theme={null}
curl -X DELETE "https://api.heygen.com/v3/ai-clipping/edf8d2c44ba441b89f395072b3ef7e34" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

### Response

```json theme={null}
{
  "data": {
    "id": "edf8d2c44ba441b89f395072b3ef7e34"
  }
}
```

## Polling Pattern

Clip jobs are processed asynchronously. Poll until status reaches `completed` or `failed`.

Status transitions: `pending` → `running` → `completed` | `failed`

```bash theme={null}
while true; do
  STATUS=$(curl -s "https://api.heygen.com/v3/ai-clipping/$JOB_ID" \
    -H "X-Api-Key: $HEYGEN_API_KEY" | jq -r '.data.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] && break
  sleep 10
done
```

For long recordings, prefer a [`callback_url`](/docs/webhooks) over tight polling — HeyGen will POST you the finished job instead (`ai_clipping.success` / `ai_clipping.fail` [webhook events](/docs/webhook-events)).

## Asset Inputs

The `video` field accepts two input formats:

**By URL** — any publicly accessible HTTPS link:

```json theme={null}
{ "type": "url", "url": "https://example.com/recording.mp4" }
```

**By asset ID** — reference a file previously uploaded via [`POST /v3/assets`](/reference/upload-asset) (see [Upload Assets](/docs/upload-assets)):

```json theme={null}
{ "type": "asset_id", "asset_id": "asset_xyz789" }
```

## Full Example

```python theme={null}
import time
import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://api.heygen.com"
HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}


def clip_video(video_url, prompt=None):
    """Start a clip job, wait for it, and return the finished clips."""
    body = {
        "video": {"type": "url", "url": video_url},
        "output_settings": {
            "duration_types": ["30", "60"],
            "aspect_ratio": "portrait",
            "captions": False,
        },
    }
    if prompt:
        body["output_settings"]["prompt"] = prompt

    job_id = requests.post(
        f"{BASE}/v3/ai-clipping", headers=HEADERS, json=body
    ).json()["data"]["ai_clipping_id"]

    while True:
        job = requests.get(f"{BASE}/v3/ai-clipping/{job_id}", headers=HEADERS).json()["data"]
        if job["status"] in ("completed", "failed"):
            break
        time.sleep(10)

    if job["status"] == "failed":
        raise RuntimeError(job.get("failure_message") or "clip job failed")
    return job["clips"]


for clip in clip_video("https://example.com/interview.mp4", prompt="Best product moments"):
    print(f"{clip['title']} ({clip['duration_seconds']}s) -> {clip['video_url']}")
```

Pairing clips with audio? The same [Tools](/background-music) suite covers [background music](/background-music) and [sound effects](/sound-effects) to score your cuts.


# Assets
Source: https://heygen-1fa696a7.mintlify.app/assets

Upload, list, and manage images, audio, and video files via the HeyGen Assets API. Reference uploaded assets in any avatar video, translation, or lipsync.

<img alt="" />

Upload images, videos, audio, or PDFs to get an `asset_id` you can reference in other endpoints — like `POST /v3/video-agents`, `POST /v3/videos`, or `POST /v3/avatars`.

## Upload an Asset

```bash theme={null}
curl -X POST https://api.heygen.com/v3/assets \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@./my-photo.png"
```

```json Response theme={null}
{
  "data": {
    "asset_id": "ast_abc123",
    "url": "https://files.heygen.com/asset/ast_abc123.png",
    "mime_type": "image/png",
    "size_bytes": 204800
  }
}
```

## Supported File Types

| Category | Formats |
| - | - |
| Image | PNG, JPEG |
| Video | MP4, WebM |
| Audio | MP3, WAV |
| Document | PDF |

Max file size: **32 MB**. MIME type is auto-detected from file bytes. For larger files, use the direct upload flow below.

## Direct Upload for Large Files

`POST /v3/assets` proxies file bytes through the API, which is why it's capped at 32 MB. For larger files, use the presigned direct upload flow — three required steps:

1. [`POST /v3/assets/direct-uploads`](/reference/create-asset-upload) with `filename`, `content_type`, and exact `size_bytes` → returns `asset_id`, a presigned `upload_url`, and `upload_headers`.
2. `PUT` the raw file bytes to `upload_url`, sending `upload_headers` verbatim, before the URL expires (`expires_in_seconds`).
3. [`POST /v3/assets/{asset_id}/complete`](/reference/complete-asset-upload) to finalize. Idempotent. The `asset_id` is not usable until this step succeeds.

```bash theme={null}
# 1. Initialize
curl -X POST https://api.heygen.com/v3/assets/direct-uploads \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "footage.mp4", "content_type": "video/mp4", "size_bytes": 134217728}'

# 2. PUT the file bytes to the returned upload_url (with upload_headers)
curl -X PUT "UPLOAD_URL" -H "Content-Type: video/mp4" --upload-file ./footage.mp4

# 3. Complete
curl -X POST https://api.heygen.com/v3/assets/ASSET_ID/complete \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Direct upload accepts up to 200 MB per video, image, or PDF file and 1.5 GB per audio file (also returned as `max_bytes` in the initialize response). See [Upload Assets](/docs/upload-assets#upload-large-files-direct-upload) for full examples in Python and Node.js. To upload up to 100 files in one call, use the [batch variant](/batch-assets) of this flow.

## Using Assets

Once uploaded, reference the `asset_id` anywhere the API accepts asset inputs:

```json theme={null}
// In POST /v3/video-agents (file attachments)
{
  "prompt": "Explain this diagram",
  "files": [{ "type": "asset_id", "asset_id": "ast_abc123" }]
}
```

```json theme={null}
// In POST /v3/avatars (photo avatar)
{
  "type": "photo",
  "name": "My Avatar",
  "file": { "type": "asset_id", "asset_id": "ast_abc123" }
}
```

Anywhere that accepts an asset also accepts a direct URL (`{"type": "url", "url": "https://..."}`) or base64 (`{"type": "base64", "media_type": "image/png", "data": "..."}`). URL inputs are capped at 16 MB for images and 32 MB for video, audio, and PDF, and signing the URL does not change that. For larger files, upload via the direct upload flow and pass the `asset_id`. Use `asset_id` when you need to reuse the same file across multiple requests. An `asset_id` does not expire: reuse it across requests and retries until you delete it.

## Delete an Asset

```bash theme={null}
curl -X DELETE https://api.heygen.com/v3/assets/ast_abc123 \
  -H "x-api-key: YOUR_API_KEY"
```

[`DELETE /v3/assets/{asset_id}`](/reference/delete-asset) removes the asset, and later requests that use its `asset_id` return `asset_not_found`. Deleting an avatar group with [`DELETE /v3/avatars/{group_id}`](/reference/delete-avatar-group) does not delete the assets used to create it, so delete each `asset_id` separately. See [Asset lifetime and deletion](/docs/upload-assets#asset-lifetime-and-deletion).


# Audio to Video
Source: https://heygen-1fa696a7.mintlify.app/audio-to-video

Bring your own audio — a voice memo, a podcast segment, a dubbed track — and lip-sync it onto your avatar, digital twin, or any image with one HeyGen API call.

<img alt="" />

## Overview

Audio to Video turns a recorded audio track into a talking video: you supply the audio, pick who says it, and HeyGen handles the delivery and render. It's the same [`POST /v3/videos`](/reference/create-video) endpoint used for script-driven videos — the difference is that you pass `audio_url` (or `audio_asset_id`) instead of `script`, and the video's length follows your audio, up to 30 minutes.

Two subject choices, both accepting the same audio fields:

| `type` | Subject | You provide |
| - | - | - |
| `avatar` | An avatar you already have — digital twin, studio avatar, or photo avatar look | `avatar_id` |
| `image` | Any single-person image, animated on the fly | `image` (URL, asset ID, or base64) |

Use it when the voice already exists: preserving a real person's recorded voice on their digital twin, dubbing localized audio onto one presenter, or lip-syncing audio produced by another tool.

## Quick Example

Lip-sync an audio file onto an avatar:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar",
    "avatar_id": "YOUR_AVATAR_ID",
    "audio_url": "https://example.com/narration.mp3",
    "title": "Audio to video — narration",
    "aspect_ratio": "auto",
    "resolution": "1080p"
  }'
```

```json Response theme={null}
{
  "data": {
    "video_id": "4086e92fc7a54d67b62ef93b1ccf53db",
    "status": "waiting",
    "output_format": "mp4"
  }
}
```

Generation is asynchronous. Poll [`GET /v3/videos/{video_id}`](/reference/get-video) until `status` is `completed`, then download `video_url` — or pass a `callback_url` to receive a [webhook](/docs/webhooks) instead.

## Audio Sources

Provide exactly one audio source per request — audio fields are mutually exclusive with `script`:

| Field | What it takes |
| - | - |
| `audio_url` | Public HTTPS URL of an audio file. |
| `audio_asset_id` | Asset ID of an uploaded audio file (MP3 or WAV, max 32 MB) — from [`POST /v3/assets`](/reference/upload-asset). |

<Note>
  One request renders up to **30 minutes** of audio. For a longer recording, split it into segments of 30 minutes or less and send one per request — or compose them as scenes of a [studio video](/studio-videos) to get a single output. See [Usage Limits](/docs/usage-limits#output-video-specifications).
</Note>

<Tip>
  Have text and a voice instead of a recording? Two options: pass `script` + `voice_id` directly (skip the audio step entirely), or synthesize audio first with [`POST /v3/voices/speech`](/reference/generate-speech) — its response `audio_url` can be passed straight into `audio_url` here. The TTS route is handy when you want to reuse the same generated narration across several videos or archive it separately.
</Tip>

## With an Avatar or Digital Twin

`"type": "avatar"` works with any avatar ID you own — a [digital twin](/generate-avatar-video) trained from real footage, a studio avatar, or a [photo avatar](/photo-avatar) look.

```json theme={null}
{
  "type": "avatar",
  "avatar_id": "YOUR_AVATAR_ID",
  "audio_asset_id": "YOUR_AUDIO_ASSET_ID",
  "background": { "type": "color", "value": "#0b1220" }
}
```

| Parameter | Type | Required | Description |
| - | - | - | - |
| `type` | string | Yes | Must be `avatar`. |
| `avatar_id` | string | Yes | Video avatar or photo avatar look ID. Browse with [`GET /v3/avatars/looks`](/reference/list-avatar-looks). |
| `audio_url` / `audio_asset_id` | string | One required | The audio to lip-sync — see [Audio Sources](#audio-sources). |
| `engine` | object | No | Defaults to [Avatar IV](/avatar-iv). Pass `{ "type": "avatar_v" }` for [Avatar V](/avatar-v) on eligible looks (check `supported_api_engines` on the look). |
| `motion_prompt` | string | No | Natural-language body-motion and gesture control. Photo avatars on either engine; video avatars on Avatar V. |
| `expressiveness` | string | No | Expressiveness level for photo avatars on Avatar IV. Defaults to `low`. |
| `background` | object | No | Background behind the avatar: `{ "type": "color", "value": "#RRGGBB" }` for a solid color, or `{ "type": "image", ... }` with a `url` or `asset_id`. |
| `remove_background` | boolean | No | Remove the avatar background (video avatars must be trained with matting enabled). |
| `output_format` | string | No | `mp4` (default) or `webm` for a transparent background — see [Transparent Background Videos](/transparent-background-videos). |

## With an Image

`"type": "image"` animates any single-person image with lip-sync to your audio — no avatar creation step. It's [Image to Video](/image-to-video) with your own soundtrack.

```json theme={null}
{
  "type": "image",
  "image": { "type": "asset_id", "asset_id": "YOUR_IMAGE_ASSET_ID" },
  "audio_url": "https://example.com/narration.mp3"
}
```

| Parameter | Type | Required | Description |
| - | - | - | - |
| `type` | string | Yes | Must be `image`. |
| `image` | object | Yes | Image to animate: `{ "type": "url", "url": "..." }`, `{ "type": "asset_id", "asset_id": "..." }`, or `{ "type": "base64", "media_type": "image/png", "data": "..." }`. |
| `audio_url` / `audio_asset_id` | string | One required | The audio to lip-sync — see [Audio Sources](#audio-sources). |
| `motion_prompt` | string | No | Natural-language body-motion control. |
| `expressiveness` | string | No | Expressiveness level. Defaults to `low`. |

## Output Settings

Both subject types share the same output controls:

| Parameter | Type | Default | Description |
| - | - | - | - |
| `title` | string | — | Display title in the HeyGen dashboard. |
| `aspect_ratio` | string | `16:9` | `16:9`, `9:16`, `4:5`, `5:4`, `1:1`, or `auto` (preserves the source's aspect ratio — recommended). |
| `resolution` | string | — | `720p` or `1080p`. |
| `fit` | string | — | How the subject fills the canvas: `cover` (fill, may crop) or `contain` (fit entirely, may show background). |
| `caption` | object | — | Caption settings. A sidecar subtitle file is returned via `subtitle_url`; add `"style": "default"` to also burn captions into the video. |
| `callback_url` | string | — | [Webhook](/docs/webhooks) URL notified when the video is ready. |
| `callback_id` | string | — | Caller-defined identifier echoed back in the webhook payload. |

## Full Example

Record-to-video in one script: upload the audio, lip-sync it onto an avatar, and wait for the result.

```python theme={null}
import time
import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://api.heygen.com"
HEADERS = {"x-api-key": API_KEY}


def audio_to_video(audio_path, avatar_id):
    """Upload an audio file, lip-sync it onto an avatar, return the video URL."""
    with open(audio_path, "rb") as f:
        asset = requests.post(
            f"{BASE}/v3/assets", headers=HEADERS, files={"file": f}
        ).json()["data"]

    video_id = requests.post(
        f"{BASE}/v3/videos",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={
            "type": "avatar",
            "avatar_id": avatar_id,
            "audio_asset_id": asset["id"],
            "aspect_ratio": "auto",
            "resolution": "1080p",
        },
    ).json()["data"]["video_id"]

    while True:
        video = requests.get(f"{BASE}/v3/videos/{video_id}", headers=HEADERS).json()["data"]
        if video["status"] in ("completed", "failed"):
            break
        time.sleep(10)

    if video["status"] == "failed":
        raise RuntimeError(video.get("failure_message") or "video generation failed")
    return video["video_url"]


print(audio_to_video("narration.mp3", "YOUR_AVATAR_ID"))
```

Swap the `json` payload for the [`image` shape](#with-an-image) to drive the same pipeline from a photo instead of an avatar.


# Avatar III
Source: https://heygen-1fa696a7.mintlify.app/avatar-iii

Avatar III is a HeyGen rendering engine on the v3 API, built around a dedicated photo-to-video pipeline — a higher-quality re-engineered model for photo avatars and video avatars (digital twins and studio avatars).

<img alt="" />

A single `engine` value resolves to the right product based on the avatar look type — mirroring how `avatar_iv` already serves both photo and video avatars:

| Look type | Resolves to | Max resolution |
| - | - | - |
| `digital_twin` | Digital Twin | 4K |
| `studio_avatar` | Digital Twin | 4K |
| `photo_avatar` | Photo Avatar | 1080p |

## Supported avatar types

`digital_twin`, `studio_avatar`, `photo_avatar` — pass the look's `avatar_id` in the request.

Studio avatar looks are video avatars, so they take the same Digital Twin pipeline as `digital_twin` looks, including 4K support.

For `motion_prompt`, `expressiveness`, or animating an arbitrary image, use [Avatar IV](/avatar-iv).

## Example request

Select Avatar III by passing `"engine": { "type": "avatar_iii" }` in your [`POST /v3/videos`](/reference/create-video) request:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar",
    "avatar_id": "YOUR_PHOTO_AVATAR_LOOK_ID",
    "script": "Hello from Avatar III.",
    "voice_id": "YOUR_VOICE_ID",
    "resolution": "1080p",
    "engine": { "type": "avatar_iii" }
  }'
```

Video generation is asynchronous — the response returns a `video_id` you poll with `GET /v3/videos/{video_id}`. To compare engines, see [Models](/models).


# Avatar IV
Source: https://heygen-1fa696a7.mintlify.app/avatar-iv

Avatar IV is the default HeyGen v3 rendering engine - the broadest avatar support, arbitrary image animation, motion_prompt, and expressiveness control.

<img alt="" />

## Supported avatar types

`studio_avatar`, `digital_twin`, `photo_avatar`, `image` (arbitrary), `prompt`

## Exclusive features

* `motion_prompt` — a natural-language string controlling body motion and hand gestures (e.g. `"walk towards the camera slowly"`). Available for photo avatars and arbitrary images.
* `expressiveness` — controls energy and range of movement: `high`, `medium`, or `low`. Available for photo avatars and arbitrary images. Defaults to `low`.
* **Arbitrary image support** — animate any image by setting `type: "image"`, with no registered avatar required.

## Example request

Avatar IV is the default engine, so you can omit `engine` entirely in your [`POST /v3/videos`](/reference/create-video) request:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar",
    "avatar_id": "YOUR_LOOK_ID",
    "script": "Hello from Avatar IV.",
    "voice_id": "YOUR_VOICE_ID",
    "resolution": "1080p"
  }'
```

To request it explicitly — or to be unambiguous in code that switches engines — pass `"engine": { "type": "avatar_iv" }`:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar",
    "avatar_id": "YOUR_LOOK_ID",
    "script": "Hello from Avatar IV.",
    "voice_id": "YOUR_VOICE_ID",
    "resolution": "1080p",
    "engine": { "type": "avatar_iv" }
  }'
```

Video generation is asynchronous — the response returns a `video_id` you poll with `GET /v3/videos/{video_id}`. For a full walkthrough of creating a Digital Twin video and polling for completion, see the [Digital Twin guide](/generate-avatar-video). To compare engines, see [Models](/models); for the highest-fidelity motion, see [Avatar V](/avatar-v).


# Avatar V
Source: https://heygen-1fa696a7.mintlify.app/avatar-v

Avatar V is HeyGen's highest-fidelity v3 rendering engine, using cross-reference-driven animation for the most natural motion and lip-sync. Opt-in per look.

<img alt="" />

## Supported avatar types

`digital_twin` — for eligible looks.

## Supported parameters

* `motion_prompt` — natural-language control of body motion and hand gestures.
* `reference_look_id` *(optional)* — a `digital_twin` look to use as the animation reference. Must belong to the same avatar group as `avatar_id`, and a non-public one must clear its group's consent requirements. When omitted, the digital twin self-references.

For `expressiveness` control, use [Avatar IV](/avatar-iv).

## Checking eligibility

Avatar V is opt-in per look. Before using it, fetch the look and check `supported_api_engines`:

```bash theme={null}
GET /v3/avatars/looks/{look_id}
```

```json theme={null}
{
  "id": "lk_abc123",
  "name": "My Digital Twin",
  "avatar_type": "digital_twin",
  "supported_api_engines": ["avatar_iv", "avatar_v"]
}
```

Avatar V is available when `"avatar_v"` appears in `supported_api_engines`.

## Example request

Select Avatar V by passing `"engine": { "type": "avatar_v" }` in your [`POST /v3/videos`](/reference/create-video) request:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar",
    "avatar_id": "YOUR_LOOK_ID",
    "script": "Hello from Avatar V.",
    "voice_id": "YOUR_VOICE_ID",
    "resolution": "1080p",
    "engine": { "type": "avatar_v" }
  }'
```

Video generation is asynchronous — the response returns a `video_id` you poll with `GET /v3/videos/{video_id}`. See the [Digital Twin guide](/generate-avatar-video) for the end-to-end request and polling flow, [Models](/models) for an engine comparison, or [Avatar IV](/avatar-iv) for the default engine.


# Background music
Source: https://heygen-1fa696a7.mintlify.app/background-music

Search HeyGen's background-music catalog with natural language and get ready-to-use, pre-signed audio URLs for your videos via the HeyGen API.

<img alt="" />

Find background music by describing the vibe you want — "upbeat lofi hip-hop", "tense cinematic riser", "subtle ambient corporate" — and get back ranked tracks, each with a pre-signed download URL. Search is semantic, not keyword-based, so plain-language descriptions work best.

## Search the Catalog

Send a `GET` request to `/v3/audio/sounds` with a natural-language `query`:

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/audio/sounds?query=upbeat%20corporate%20background%20music&limit=3" \
  -H "x-api-key: YOUR_API_KEY"
```

```json Response theme={null}
{
  "data": [
    {
      "id": "4cbcca493220487bbae26a2c42dba5e9",
      "name": "Astral Generated Music: 4cbcca49",
      "description": "upbeat professional background music",
      "audio_url": "https://heygen-product.s3-accelerate.amazonaws.com/astral_generated_music/4cbcca49...wav?X-Amz-Algorithm=...",
      "duration": 30.0,
      "score": 0.933,
      "type": "music"
    },
    {
      "id": "93a98c35d9654029be397d8d27a06da0",
      "name": "Astral Generated Music: 93a98c35",
      "description": "Modern, upbeat, and inspiring corporate background music with a light electronic beat.",
      "audio_url": "https://heygen-product.s3-accelerate.amazonaws.com/astral_generated_music/93a98c35...wav?X-Amz-Algorithm=...",
      "duration": 60.0,
      "score": 0.911,
      "type": "music"
    }
  ],
  "has_more": true,
  "next_token": "eyJvZmZzZXQiOiAzLCAiX3R5cGUiOiAibXVzaWMifQ=="
}
```

## Query Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `query` | string | — | **Required.** Natural-language description of the audio you want, e.g. `tense cinematic riser`. Results are ranked by semantic similarity to this text. |
| `limit` | integer | `10` | Maximum number of results to return (1–50). |
| `min_score` | number | `0.7` | Minimum semantic similarity score (0–1). Tracks scoring below this are omitted. Raise it for tighter matches; lower it to widen the net. |
| `type` | string | `music` | Audio content type. `music` (the default) searches the background-music catalog; set `sound_effects` to search [sound effects](/sound-effects). |
| `token` | string | — | Opaque pagination cursor. Pass the `next_token` from a prior response to fetch the next page. |

## Response Fields

| Field | Type | Description |
| - | - | - |
| `data[].id` | string | Stable identifier for the track. |
| `data[].name` | string | Display name of the track. |
| `data[].description` | string | Human-readable description of the track's mood and instrumentation. |
| `data[].audio_url` | string | Pre-signed download URL for the audio file (WAV). |
| `data[].duration` | number | Track length in seconds. |
| `data[].score` | number | Semantic similarity score (0–1) against your `query`. Results are returned highest-first. |
| `data[].type` | string | `music` for results from the background-music catalog. |
| `has_more` | boolean | `true` if more results are available beyond this page. |
| `next_token` | string | Cursor for the next page. Pass it as `token` on your next request. Absent when `has_more` is `false`. |

<Note>
  Each `audio_url` is a pre-signed link with a limited lifetime. Download the file (or hand the URL to a downstream step) soon after searching rather than caching it for later.
</Note>

## Paginate Through Results

When `has_more` is `true`, pass the returned `next_token` as the `token` parameter to fetch the next page:

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/audio/sounds?query=upbeat%20corporate%20background%20music&limit=3&token=eyJvZmZzZXQiOiAzLCAiX3R5cGUiOiAibXVzaWMifQ==" \
  -H "x-api-key: YOUR_API_KEY"
```

## Full Example

```python theme={null}
import requests
from urllib.parse import urlencode

API_KEY = "YOUR_API_KEY"
BASE = "https://api.heygen.com"
HEADERS = {"x-api-key": API_KEY}

def search_music(query, limit=10, min_score=0.7):
    """Yield every matching track, following pagination."""
    token = None
    while True:
        params = {"query": query, "limit": limit, "min_score": min_score}
        if token:
            params["token"] = token
        resp = requests.get(
            f"{BASE}/v3/audio/sounds?{urlencode(params)}",
            headers=HEADERS,
        )
        page = resp.json()
        for track in page["data"]:
            yield track
        if not page.get("has_more"):
            break
        token = page["next_token"]

# Grab the single best-matching track
best = next(search_music("calm ambient piano for a product walkthrough", limit=1))
print(f"{best['name']} ({best['duration']}s, score {best['score']:.2f})")
print(f"Download: {best['audio_url']}")
```

<Tip>
  Searching from an AI agent instead of code? The same catalog is available through the [HeyGen MCP](/mcp/overview) via the `search_audio_sounds` tool.
</Tip>


# Assets
Source: https://heygen-1fa696a7.mintlify.app/batch-assets

Upload up to 100 files in one batch: request presigned S3 slots in a single call, PUT the bytes in parallel, then finalize and poll one batch id.

<img alt="" />

## Overview

Asset batches parallelize the [direct upload flow](/assets#direct-upload-for-large-files): instead of presigning, uploading, and completing files one by one, you request up to 100 presigned upload slots in a single call, PUT all the files in parallel, and finalize the whole batch with one request.

The flow has three steps:

1. [`POST /v3/assets/direct-uploads/batches`](/reference/create-asset-upload-batch) — get an `asset_id` + presigned `upload_url` per file.
2. `PUT` each file's raw bytes to its `upload_url`, sending `upload_headers` verbatim.
3. [`POST /v3/assets/complete/batches`](/reference/complete-asset-upload-batch) — finalize, then poll [`GET /v3/assets/batches/{batch_id}`](/reference/get-asset-batch).

<Note>
  A batch holds up to **100** files. No file bytes flow through the HeyGen API — uploads go straight to S3. On completion, each file is validated and ingested independently, so one bad file does not fail the rest.
</Note>

## Step 1 — Create a Batch of Upload Slots

* Endpoint: `POST /v3/assets/direct-uploads/batches`
* Purpose: Presign up to 100 direct-to-S3 upload slots and return them synchronously with a `batch_id`.

### Quick Example

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/assets/direct-uploads/batches" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Webinar recordings — October",
    "files": [
      { "filename": "session-1.mp4", "content_type": "video/mp4", "size_bytes": 157286400 },
      { "filename": "session-2.mp4", "content_type": "video/mp4", "size_bytes": 183500800 }
    ]
  }'
```

```json Response theme={null}
{
  "data": {
    "batch_id": "batch_as_abc123",
    "items": [
      {
        "asset_id": "asset_9f2c...",
        "upload_url": "https://heygen-uploads.s3.amazonaws.com/...",
        "upload_headers": { "Content-Type": "video/mp4" },
        "expires_in_seconds": 86400,
        "max_bytes": 209715200,
        "status": "pending_upload"
      },
      {
        "asset_id": "asset_81aa...",
        "upload_url": "https://heygen-uploads.s3.amazonaws.com/...",
        "upload_headers": { "Content-Type": "video/mp4" },
        "expires_in_seconds": 86400,
        "max_bytes": 209715200,
        "status": "pending_upload"
      }
    ]
  }
}
```

Slots are returned **in the submitted order**, one per file.

### Request Body

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `files` | array | Yes | — | Files to presign, each the same shape as [`POST /v3/assets/direct-uploads`](/reference/create-asset-upload). Between 1 and 100 items. |
| `title` | string | No | `null` | Display name for the batch, shown in the HeyGen app. |
| `callback_url` | string | No | `null` | Reserved for parity with the other batch APIs — track completion by [polling the batch](#step-3--complete-and-poll). |

Each entry in `files`:

| Field | Type | Required | Description |
| - | - | - | - |
| `filename` | string | Yes | Original filename for reference/metadata. The stored object's extension is derived from `content_type`. |
| `content_type` | string | Yes | Declared MIME type (e.g. `video/mp4`, `image/png`, `audio/mpeg`, `application/pdf`). Verified against the stored bytes when the batch is completed. |
| `size_bytes` | integer | Yes | Exact byte size of the file. Signed into the upload URL so it cannot be exceeded. |
| `checksum_sha256` | string | No | SHA-256 of the file as hex. When provided, S3 enforces it on upload. |

Each file can be up to 200 MB (209,715,200 bytes), or 1.5 GB for audio. The limit for each file's type is returned as `max_bytes`. A larger `size_bytes` fails the whole request with `Invalid file(s) at index N: File too large`.

### Idempotency

Pass an `Idempotency-Key` header to make retries safe — replaying the same key returns the same batch and the same slots.

## Step 2 — Upload the Files

`PUT` each file's raw bytes to its `upload_url`, sending the returned `upload_headers` verbatim. Uploads are plain S3 PUTs, so you can run them in parallel from any HTTP client:

```bash theme={null}
curl -X PUT "https://heygen-uploads.s3.amazonaws.com/..." \
  -H "Content-Type: video/mp4" \
  --data-binary @session-1.mp4
```

Each `upload_url` expires after `expires_in_seconds` — request a fresh batch if a slot lapses before you upload.

## Step 3 — Complete and Poll

* Endpoint: `POST /v3/assets/complete/batches`
* Purpose: Finalize every uploaded file in the batch. Call once, after all PUTs return `200`.

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/assets/complete/batches" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "batch_id": "batch_as_abc123" }'
```

```json Response theme={null}
{
  "data": {
    "batch_id": "batch_as_abc123"
  }
}
```

The call returns `202 Accepted` — validation and ingestion run asynchronously per file. The call is idempotent: repeating it re-drives the same batch.

Poll [`GET /v3/assets/batches/{batch_id}`](/reference/get-asset-batch) for per-item progress:

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/assets/batches/batch_as_abc123?limit=100" \
  -H "x-api-key: YOUR_API_KEY"
```

```json Response theme={null}
{
  "data": {
    "batch_id": "batch_as_abc123",
    "title": "Webinar recordings — October",
    "status": "processing",
    "total_items": 2,
    "counts_by_status": {
      "completed": 1,
      "processing": 1
    },
    "created_at": 1783891200,
    "items": [
      {
        "item_index": 0,
        "status": "completed",
        "video_id": "asset_9f2c...",
        "error": null
      },
      {
        "item_index": 1,
        "status": "processing",
        "video_id": null,
        "error": null
      }
    ],
    "has_more": false,
    "next_token": null
  }
}
```

<Info>
  The batch read model is shared across the batch APIs, so the per-item id field is named `video_id` — for asset batches it holds the **asset id**. Once an item is `completed`, that asset id is usable anywhere assets are accepted, e.g. as `audio_asset_id` in [video creation](/generate-avatar-video) or as an `asset_id` source in [translation](/batch-video-translations) and [lipsync](/batch-lipsyncs) batches.
</Info>

### Query Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `limit` | integer | No | `100` | Items per page, `1`–`100`. |
| `token` | string | No | — | Opaque pagination cursor from a previous response's `next_token`. |

The response shape matches the [video batch](/batch-videos#response-fields): aggregate `status` (`processing`, `completed`, or `failed`), `total_items`, `counts_by_status`, and a paged `items` array where each item carries `item_index`, `status` (`queued`, `processing`, `completed`, or `failed`), its id, and `error` details when failed.

## Bulk Statuses

* Endpoint: `GET /v3/assets/statuses`
* Purpose: Check up to 100 assets in one request — across batches, or for assets uploaded individually.

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/assets/statuses?batch_ids=batch_as_abc123" \
  -H "x-api-key: YOUR_API_KEY"
```

| Parameter | Type | Required | Description |
| - | - | - | - |
| `asset_ids` | string | No | Comma-separated asset ids to look up. |
| `batch_ids` | string | No | Comma-separated batch ids; each expands to its member assets. |

Statuses are `queued`, `processing`, `completed`, or `failed`, plus `not_found` for unknown or unowned ids.


# Lipsyncs
Source: https://heygen-1fa696a7.mintlify.app/batch-lipsyncs

Submit up to 100 lipsync requests in a single call. Re-sync many videos to new audio tracks together, then poll one batch id for per-item progress.

<img alt="" />

## Overview

Lipsync batches let you submit many lipsync jobs in one request instead of calling [`POST /v3/lipsyncs`](/reference/create-lipsync) once per job. You send an array of lipsync payloads, get back a single `batch_id` right away, and poll that one id for the status and id of every item.

Each item in a batch is a standard lipsync payload — the exact shape [`POST /v3/lipsyncs`](/reference/create-lipsync) accepts — so anything you can lipsync on its own can be batched, in either [Speed](/lipsync-speed) or [Precision](/lipsync-precision) mode.

<Note>
  A batch holds up to **100** items. Each payload becomes exactly one batch item, and each item is created and processed independently — one bad source does not fail the rest.
</Note>

## Create a Batch

* Endpoint: `POST /v3/lipsyncs/batches`
* Purpose: Queue up to 100 lipsync payloads and return a `batch_id` immediately.

### Quick Example

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/lipsyncs/batches" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Course module redubs",
    "callback_url": "https://example.com/hooks/heygen",
    "lipsyncs": [
      {
        "video": { "type": "url", "url": "https://example.com/module-1.mp4" },
        "audio": { "type": "url", "url": "https://example.com/module-1-v2.mp3" },
        "title": "Module 1 — updated narration",
        "mode": "speed"
      },
      {
        "video": { "type": "asset_id", "asset_id": "asset_abc123" },
        "audio": { "type": "asset_id", "asset_id": "asset_def456" },
        "title": "Module 2 — updated narration",
        "mode": "precision"
      }
    ]
  }'
```

```json Response theme={null}
{
  "data": {
    "batch_id": "batch_ls_abc123"
  }
}
```

The call returns `202 Accepted` — the batch is queued, not finished. Use the returned `batch_id` to [poll for progress](#get-a-batch).

### Request Body

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `lipsyncs` | array | Yes | — | Lipsync payloads, each identical in shape to [`POST /v3/lipsyncs`](/reference/create-lipsync). Between 1 and 100 items. |
| `title` | string | No | `null` | Display name for the batch, shown in the HeyGen app. |
| `callback_url` | string | No | `null` | [Webhook](/docs/webhooks) URL invoked once when every item in the batch reaches a terminal state. |

Each entry in `lipsyncs` takes the full set of lipsync options — `video` and `audio` (each as a `url` or `asset_id`), `mode` (`speed` or `precision`), plus captions, partial-range, and format controls. See [`POST /v3/lipsyncs`](/reference/create-lipsync) for every field.

### Idempotency

Pass an `Idempotency-Key` header to make retries safe — replaying the same key returns the original batch instead of creating a duplicate.

## Get a Batch

* Endpoint: `GET /v3/lipsyncs/batches/{batch_id}`
* Purpose: Return the batch's aggregate status plus one page of items with their id and per-item status.

### Quick Example

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/lipsyncs/batches/batch_ls_abc123?limit=100" \
  -H "x-api-key: YOUR_API_KEY"
```

```json Response theme={null}
{
  "data": {
    "batch_id": "batch_ls_abc123",
    "title": "Course module redubs",
    "status": "processing",
    "total_items": 2,
    "counts_by_status": {
      "completed": 1,
      "processing": 1
    },
    "created_at": 1783891200,
    "items": [
      {
        "item_index": 0,
        "status": "completed",
        "video_id": "ls_9f2c...",
        "error": null
      },
      {
        "item_index": 1,
        "status": "processing",
        "video_id": null,
        "error": null
      }
    ],
    "has_more": false,
    "next_token": null
  }
}
```

<Info>
  The batch read model is shared across the batch APIs, so the per-item id field is named `video_id` — for lipsync batches it holds the **lipsync id**. Use it with [`GET /v3/lipsyncs/{lipsync_id}`](/reference/get-lipsync) for the full record and download URL.
</Info>

### Query Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `limit` | integer | No | `100` | Items per page, `1`–`100`. |
| `token` | string | No | — | Opaque pagination cursor from a previous response's `next_token`. |

The response shape matches the [video batch](/batch-videos#response-fields): aggregate `status` (`processing`, `completed`, or `failed`), `total_items`, `counts_by_status`, and a paged `items` array where each item carries `item_index`, `status` (`queued`, `processing`, `completed`, or `failed`), its id, and `error` details when failed.

## Bulk Statuses

* Endpoint: `GET /v3/lipsyncs/statuses`
* Purpose: Check up to 100 lipsyncs in one request — across batches, or for jobs created individually.

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/lipsyncs/statuses?batch_ids=batch_ls_abc123" \
  -H "x-api-key: YOUR_API_KEY"
```

| Parameter | Type | Required | Description |
| - | - | - | - |
| `lipsync_ids` | string | No | Comma-separated lipsync ids to look up. |
| `batch_ids` | string | No | Comma-separated batch ids; each expands to its member lipsyncs. |

Statuses are `queued`, `processing`, `completed`, or `failed`, plus `not_found` for unknown or unowned ids.

## Tracking completion

* **Webhook (push).** Set `callback_url` on the batch to be notified once, when the last item reaches a terminal state. See [Webhooks](/docs/webhooks) to register an endpoint and verify signatures.
* **Polling (pull).** Call `GET /v3/lipsyncs/batches/{batch_id}` and read `counts_by_status`. Items surface their lipsync id as soon as the job is created, so you can start fetching finished renders with [`GET /v3/lipsyncs/{lipsync_id}`](/reference/get-lipsync) while the rest of the batch is still processing.


# Video Translations
Source: https://heygen-1fa696a7.mintlify.app/batch-video-translations

Submit up to 100 video translation requests in a single call. Fan one source video out to many languages, then poll one batch id for per-item progress.

<img alt="" />

## Overview

Translation batches let you submit many translations in one request instead of calling [`POST /v3/video-translations`](/reference/create-video-translation) once per job. You send an array of translation payloads, get back a single `batch_id` right away, and poll that one id for the status and id of every item.

Each item in a batch is a standard translation payload — the exact shape [`POST /v3/video-translations`](/reference/create-video-translation) accepts — so anything you can translate on its own can be batched, in either [Speed](/docs/video-translate) or [Precision](/docs/video-translation-precision) mode.

<Note>
  A batch holds up to **100** items. A single payload targeting multiple `output_languages` expands to **one batch item per language**, and the expanded count is what the 100-item cap applies to. Each item is created and processed independently, so one bad source does not fail the rest.
</Note>

## Create a Batch

* Endpoint: `POST /v3/video-translations/batches`
* Purpose: Queue up to 100 translation payloads and return a `batch_id` immediately.

### Quick Example

One source video fanned out to three languages — this creates three batch items:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/video-translations/batches" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Q3 keynote — localized cuts",
    "callback_url": "https://example.com/hooks/heygen",
    "video_translations": [
      {
        "video": { "type": "url", "url": "https://example.com/keynote.mp4" },
        "title": "Q3 keynote",
        "output_languages": ["Spanish (Spain)", "French", "Japanese"],
        "mode": "speed"
      }
    ]
  }'
```

```json Response theme={null}
{
  "data": {
    "batch_id": "batch_tr_abc123"
  }
}
```

The call returns `202 Accepted` — the batch is queued, not finished. Use the returned `batch_id` to [poll for progress](#get-a-batch).

### Request Body

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `video_translations` | array | Yes | — | Translation payloads, each identical in shape to [`POST /v3/video-translations`](/reference/create-video-translation). Up to 100 items after language expansion. |
| `title` | string | No | `null` | Display name for the batch, shown in the HeyGen app. |
| `callback_url` | string | No | `null` | [Webhook](/docs/webhooks) URL invoked once when every item in the batch reaches a terminal state. |

Each entry in `video_translations` takes the full set of translation options — `video` (as a `url` or `asset_id`), `output_languages` (use [`GET /v3/video-translations/languages`](/reference/list-supported-translation-languages) for valid values), `mode` (`speed` or `precision`), plus captions, [brand glossary](/docs/brand-glossary), stock voice, partial-range, and format controls. See [`POST /v3/video-translations`](/reference/create-video-translation) for every field.

### Idempotency

Pass an `Idempotency-Key` header to make retries safe — replaying the same key returns the original batch instead of creating a duplicate.

## Get a Batch

* Endpoint: `GET /v3/video-translations/batches/{batch_id}`
* Purpose: Return the batch's aggregate status plus one page of items with their id and per-item status.

### Quick Example

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/video-translations/batches/batch_tr_abc123?limit=100" \
  -H "x-api-key: YOUR_API_KEY"
```

```json Response theme={null}
{
  "data": {
    "batch_id": "batch_tr_abc123",
    "title": "Q3 keynote — localized cuts",
    "status": "processing",
    "total_items": 3,
    "counts_by_status": {
      "completed": 2,
      "processing": 1
    },
    "created_at": 1783891200,
    "items": [
      {
        "item_index": 0,
        "status": "completed",
        "video_id": "vt_9f2c...",
        "error": null
      },
      {
        "item_index": 1,
        "status": "completed",
        "video_id": "vt_81aa...",
        "error": null
      },
      {
        "item_index": 2,
        "status": "processing",
        "video_id": null,
        "error": null
      }
    ],
    "has_more": false,
    "next_token": null
  }
}
```

<Info>
  The batch read model is shared across the batch APIs, so the per-item id field is named `video_id` — for translation batches it holds the **video translation id**. Use it with [`GET /v3/video-translations/{video_translation_id}`](/reference/get-video-translation) for the full record and download URL.
</Info>

### Query Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `limit` | integer | No | `100` | Items per page, `1`–`100`. |
| `token` | string | No | — | Opaque pagination cursor from a previous response's `next_token`. |

The response shape matches the [video batch](/batch-videos#response-fields): aggregate `status` (`processing`, `completed`, or `failed`), `total_items`, `counts_by_status`, and a paged `items` array where each item carries `item_index`, `status` (`queued`, `processing`, `completed`, or `failed`), its id, and `error` details when failed.

## Bulk Statuses

* Endpoint: `GET /v3/video-translations/statuses`
* Purpose: Check up to 100 translations in one request — across batches, or for jobs created individually.

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/video-translations/statuses?batch_ids=batch_tr_abc123" \
  -H "x-api-key: YOUR_API_KEY"
```

| Parameter | Type | Required | Description |
| - | - | - | - |
| `video_translation_ids` | string | No | Comma-separated translation ids to look up. |
| `batch_ids` | string | No | Comma-separated batch ids; each expands to its member translations. |

Statuses are `queued`, `processing`, `completed`, or `failed`, plus `not_found` for unknown or unowned ids.

## Tracking completion

* **Webhook (push).** Set `callback_url` on the batch to be notified once, when the last item reaches a terminal state, or subscribe to `video_translate.success` / `video_translate.fail` [webhook events](/docs/webhook-events) for per-item notifications.
* **Polling (pull).** Call `GET /v3/video-translations/batches/{batch_id}` and read `counts_by_status`. Items surface their translation id as soon as the job is created, so you can start fetching finished translations with [`GET /v3/video-translations/{video_translation_id}`](/reference/get-video-translation) while the rest of the batch is still processing.


# Videos
Source: https://heygen-1fa696a7.mintlify.app/batch-videos

Submit up to 100 video creation requests in a single call. Queue avatar, image, and cinematic avatar videos together, then poll one batch id for per-item progress.

<img alt="" />

## Overview

Video batches let you submit many videos in one request instead of calling [`POST /v3/videos`](/reference/create-video) once per video. You send an array of video payloads, get back a single `batch_id` right away, and poll that one id for the status and `video_id` of every item.

Each item in a batch is a standard video creation payload — the exact shape [`POST /v3/videos`](/reference/create-video) accepts — so any [Digital Twin](/generate-avatar-video), [image](/image-to-video), or [Cinematic Avatar](/cinematic-avatar) video you can create on its own can be batched.

<Note>
  A batch holds up to **100** items. Submission is asynchronous: the response acknowledges the batch, and each video renders on its own. Poll the batch to collect video ids as they become available.
</Note>

## Create a Batch

* Endpoint: `POST /v3/videos/batches`
* Purpose: Queue up to 100 video creation payloads and return a `batch_id` immediately.

### Quick Example

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/videos/batches" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "October product update — regional cuts",
    "callback_url": "https://example.com/hooks/heygen",
    "videos": [
      {
        "type": "avatar",
        "avatar_id": "YOUR_DIGITAL_TWIN_LOOK_ID",
        "script": "Hello from the North America team!",
        "voice_id": "YOUR_VOICE_ID"
      },
      {
        "type": "avatar",
        "avatar_id": "YOUR_DIGITAL_TWIN_LOOK_ID",
        "script": "Hello from the EMEA team!",
        "voice_id": "YOUR_VOICE_ID"
      }
    ]
  }'
```

```json Response theme={null}
{
  "data": {
    "batch_id": "batch_abc123"
  }
}
```

The call returns `202 Accepted` — the batch is queued, not finished. Use the returned `batch_id` to [poll for progress](#get-a-batch).

### Request Body

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `videos` | array | Yes | — | Video creation requests, each identical in shape to [`POST /v3/videos`](/reference/create-video). Between 1 and 100 items. |
| `title` | string | No | `null` | Display name for the batch, shown in the HeyGen app. |
| `callback_url` | string | No | `null` | [Webhook](/docs/webhooks) URL invoked once when every item in the batch reaches a terminal state. |

Each entry in `videos` is discriminated by `type`:

| `type` | Item shape | Guide |
| - | - | - |
| `avatar` | Avatar video from a script and voice | [Digital Twin](/generate-avatar-video) |
| `image` | Video from a still image | [Image to Video](/image-to-video) |
| `cinematic_avatar` | Cinematic Avatar video | [Cinematic Avatar](/cinematic-avatar) |

### Idempotency

Pass an `Idempotency-Key` header to make retries safe — replaying the same key returns the original batch instead of creating a duplicate. If a request with that key is still being processed, the API responds with `409`.

## Get a Batch

* Endpoint: `GET /v3/videos/batches/{batch_id}`
* Purpose: Return the batch's aggregate status plus one page of items with their `video_id` and per-item status.

### Quick Example

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/videos/batches/batch_abc123?limit=100" \
  -H "x-api-key: YOUR_API_KEY"
```

```json Response theme={null}
{
  "data": {
    "batch_id": "batch_abc123",
    "title": "October product update — regional cuts",
    "status": "processing",
    "total_items": 2,
    "counts_by_status": {
      "completed": 1,
      "processing": 1
    },
    "created_at": 1711929600,
    "items": [
      {
        "item_index": 0,
        "status": "completed",
        "video_id": "vid_9f2c...",
        "error": null
      },
      {
        "item_index": 1,
        "status": "processing",
        "video_id": null,
        "error": null
      }
    ],
    "has_more": false,
    "next_token": null
  }
}
```

### Query Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `limit` | integer | No | `100` | Items per page, `1`–`100`. |
| `token` | string | No | — | Opaque pagination cursor from a previous response's `next_token`. |

### Response Fields

| Field | Type | Description |
| - | - | - |
| `batch_id` | string | Batch identifier. |
| `title` | string | Batch display name, if one was set. |
| `status` | string | Aggregate status derived from item states: `processing`, `completed`, or `failed`. |
| `total_items` | integer | Number of items submitted in this batch. |
| `counts_by_status` | object | Item counts keyed by item status. |
| `created_at` | integer | Batch creation time as a Unix timestamp. |
| `items` | array | One page of batch items, ordered by `item_index`. |
| `has_more` | boolean | Whether more items exist beyond this page. |
| `next_token` | string | Cursor for the next page; `null` on the last page. |

Each entry in `items`:

| Field | Type | Description |
| - | - | - |
| `item_index` | integer | Zero-based position of this item in the submitted `videos` array. |
| `status` | string | Item status: `queued`, `processing`, `completed`, or `failed`. |
| `video_id` | string | Video id, present once the underlying video has been created. Use it with [`GET /v3/videos/{video_id}`](/reference/get-video) for the full record and download URL. |
| `error` | object | Failure details, present when `status` is `failed`. |

## Tracking completion

You have two ways to know when work finishes, and they pair well:

* **Webhook (push).** Set `callback_url` on the batch to be notified once, when the last item reaches a terminal state. See [Webhooks](/docs/webhooks) to register an endpoint and verify signatures.
* **Polling (pull).** Call `GET /v3/videos/batches/{batch_id}` and read `counts_by_status`. Individual items surface a `video_id` the moment their video is created, so you can start downloading finished videos while the rest of the batch is still rendering.

For large batches, page through `items` with `limit` and `next_token` until `has_more` is `false`, then fetch each finished video with [`GET /v3/videos/{video_id}`](/reference/get-video).


# Changelog
Source: https://heygen-1fa696a7.mintlify.app/changelog

Track every HeyGen API change, new endpoint, deprecation, and version bump in the API changelog. Subscribe via RSS or webhook to get notified on the next.

<Update label="Professional voices without a language" description="Updated - October 2026">
  **`language` is optional for professional voices**

  [`POST /v3/models/audio/voices`](/reference/create-or-retrain-an-audio-voice) in `professional` mode no longer needs `language`. Leave it out and training detects the language of each recording. The voice's `language` is `null` until it is `ACTIVE`. See [Professional Voice Clone](/docs/voices/professional-voice-clone).
</Update>

<Update label="HeyGen Voice previews" description="Added - October 2026">
  **Listen to a voice before you use it**

  [`GET /v3/models/audio/voices`](/reference/list-audio-voices) and [`GET /v3/models/audio/voices/{voice_id}`](/reference/get-an-audio-voice) now return `preview_audio_url` for every `ACTIVE` voice: instant, professional and public. It is a URL to a WAV of the voice reading a short preview script in its language. The URL can expire, so read the voice again rather than storing it. See [Instant Voice Clone](/docs/voices/heygen-voice-instant-clone#manage-voices).
</Update>

<Update label="Instant voices from an image" description="Added - October 2026">
  **Give an instant voice the sound of a setting**

  [`POST /v3/models/audio/voices`](/reference/create-or-retrain-an-audio-voice) in `instant` mode now accepts `image`: a picture of the speaker in their setting. The voice takes on the ambience of the image's background, so a quiet room keeps it clean and a busy street adds matching background sound. `image` cannot be combined with `gender` or `age`. See [Instant Voice Clone](/docs/voices/heygen-voice-instant-clone).
</Update>

<Update label="HeyGen Voice public voices and batch timestamps" description="Added - October 2026">
  **Public voices, and character timestamps on completed speech**

  * [`GET /v3/models/audio/voices`](/reference/list-audio-voices) takes `type`: `private` (default) lists your workspace's voices, and `public` lists HeyGen's public voices. Any workspace can read a public voice with [`GET /v3/models/audio/voices/{voice_id}`](/reference/get-an-audio-voice) and speak it on [`POST /v3/models/audio/tts`](/reference/generate-model-speech) and [`POST /v3/models/audio/tts/stream`](/reference/stream-speech). Public voices can't be deleted.
  * [`POST /v3/models/audio/tts`](/reference/generate-model-speech) now accepts `with_timestamps`. When `true`, the response adds `original_characters` with the start and end time of each character. See [Character timestamps](/docs/voices/heygen-voice-speech#character-timestamps).
</Update>

<Update label="Language-specific brand glossary rules" description="Added - October 2026">
  **Set pronunciations and forced translations per language**

  [`POST`](/reference/create-brand-glossary) and [`PATCH /v3/brand-glossaries`](/reference/update-brand-glossary) now accept `pronunciation_language` on `terms` entries and `target_language` on `forced_translations` entries, as `{ "scope": "specific", "code": "fr" }` or `{ "scope": "all" }`.

  * Omit the field for an all-languages rule. Existing requests and responses are unchanged.
  * A language-specific rule takes precedence over an all-languages rule for that language.
  * The same term can appear once per language in each list.
  * A term in both `do_not_translate_terms` and `forced_translations` stays untranslated.
  * See [Brand Glossary](/docs/brand-glossary#language-specific-rules).
</Update>

<Update label="HeyGen Voice 1 Turbo" description="Added - October 2026">
  **Faster, cheaper speech for instant voices**

  [`POST /v3/models/audio/tts`](/reference/generate-model-speech) and [`POST /v3/models/audio/tts/stream`](/reference/stream-speech) now accept `"model": "heygen-voice-1-turbo"`. Turbo speaks instant voices at lower latency; `heygen-voice-1` stays the default. Professional voices speak through `heygen-voice-1`. See [Text to Speech](/docs/voices/heygen-voice-speech).
</Update>

<Update label="HeyGen Voice Instant Clone and Text to Speech" description="Added - October 2026">
  **Instant voices on the HeyGen Voice model**

  [`POST /v3/models/audio/voices`](/reference/create-or-retrain-an-audio-voice) now takes `"mode": "instant"`: one recording in, a HeyGen Voice `voice_id` out, usually `ACTIVE` within seconds. No training and no voice clone slot. See [Instant Voice Clone](/docs/voices/heygen-voice-instant-clone).

  * `mode` is now required on every create and retrain call: `instant` or `professional`.
  * List, get, and delete on `/v3/models/audio/voices` cover both kinds; `mode` tells them apart.
  * [`POST /v3/models/audio/tts`](/reference/generate-model-speech) and [`POST /v3/models/audio/tts/stream`](/reference/stream-speech) speak instant voices too. `model` defaults to `heygen-voice-1`; `expressiveness_boost` (`0.0`–`1.0`) is instant-only; `seed`, `speed`, `pitch_shift`, `pitch_variance`, and `<break>` pauses stay professional-only. See [Text to Speech](/docs/voices/heygen-voice-speech).
  * Creating an instant voice is free during the preview.
</Update>

<Update label="HeyGen Video 1080p" description="Added - October 2026">
  **Render HeyGen Video at 1080p**

  [`POST /v3/models/videos`](/reference/create-heygen-video) now accepts `resolution: "1080p"` alongside `480p`, `768p` and `2k`. The default stays `768p`.

  * `1080p` bills at the `2k` rate: 3× the `768p` rate, for output seconds and reference-video seconds alike.
  * `16:9` returns 1890 × 1080 and `9:16` returns 1080 × 1890.
  * `text_to_video` and `reference_to_video` render `1080p` in `16:9` or `9:16`, the same as `2k`. Set `aspect_ratio` explicitly for `reference_to_video`, which otherwise defaults to `adaptive`.
  * `image_to_video` follows the first frame at every resolution.
  * See [HeyGen Video](/docs/models/heygen-video) for the full parameter reference.
</Update>

<Update label="Higher rate limits for Enterprise" description="Changed - October 2026">
  **Enterprise workspaces get higher request-rate limits**

  Request-rate limits now depend on your plan. Pay-As-You-Go and subscription limits are unchanged. Workspaces on an Enterprise API plan get higher limits per user and endpoint:

  * **Read:** 1,000 per minute (was 300).
  * **Write:** 30 per second (was 10).
  * **Heavy:** 120 per minute (was 30).
  * **Status polling:** 1,500 per minute (was 500), and 1,800 per minute per IP address (was 600).
  * Enterprise workspaces can ask their account team for custom limits on specific endpoints.
  * A rate-limit `429` now carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope` alongside `Retry-After`.
  * See [Usage Limits](/docs/usage-limits#rate-limiting) for which endpoints fall in each type and the endpoints with fixed limits.
</Update>

<Update label="HeyGen Video 2K" description="Added - October 2026">
  **Render HeyGen Video at 2K**

  [`POST /v3/models/videos`](/reference/create-heygen-video) now accepts `resolution: "2k"` alongside `480p` and `768p`. The default stays `768p`.

  * `2k` bills at 3× the `768p` rate, for output seconds and reference-video seconds alike.
  * `text_to_video` and `reference_to_video` render `2k` in `16:9` or `9:16`. Set `aspect_ratio` explicitly for `reference_to_video`, which otherwise defaults to `adaptive`.
  * `image_to_video` follows the first frame at every resolution.
  * See [HeyGen Video](/docs/models/heygen-video) for the full parameter reference.
</Update>

<Update label="Create Studio Templates via API" description="Added - October 2026">
  **Turn a video into a template and mark what changes, without opening the editor**

  New endpoints for creating Studio templates over the API. Make one video, promote it to a template, declare its variables, then generate a video per viewer with the existing [`POST /v3/templates/{template_id}`](/reference/generate-video-from-template).

  * [`POST /v3/templates`](/reference/create-template-from-video) creates a private template from a video you generated with `POST /v3/videos` or saved in the HeyGen editor.
  * [`GET /v3/templates/{template_id}`](/reference/get-template) now returns `composition`, every part of each scene with its `id` and `bindable_as`, plus an `edit_version`.
  * [`PUT /v3/templates/{template_id}/variables`](/reference/set-template-variables) sets the full variable list. Bind avatars, voices, images, video and audio to a part by `element_id`, and turn exact phrases into `{{name}}` placeholders with `match`. Send `expected_edit_version` to get `409` `stale_edit_version` instead of overwriting a concurrent change.
  * [`PATCH /v3/templates/{template_id}`](/reference/update-template) renames a template and [`DELETE /v3/templates/{template_id}`](/reference/delete-template) removes it.
  * Character variables take `avatar_id`. `avatar_look_id` and `character_id` are still accepted.
  * **Deprecations, removed on October 31, 2026:** the `avatar_look_id`, `character_id` and `character_type` names on character variables (send and read `avatar_id`), and the older `scenes` field on `GET /v3/templates/{template_id}` (read `composition.scenes`). `scene_ids` is unaffected. Until then both names are accepted and echoed, and `scenes` keeps its current shape.
  * See the new [Create Studio Template via API](/create-template) guide.
</Update>

<Update label="HeyGen Video API" description="Added - September 2026">
  **Generate a short video from a prompt, a first frame, or reference media**

  The public API reference now includes [`POST /v3/models/videos`](/reference/create-heygen-video) and [`GET /v3/models/videos/{video_id}`](/reference/get-heygen-video) for the `heygen-video-1` model.

  * Choose `text_to_video`, `image_to_video`, or `reference_to_video` with `mode`. Generate 5–15 second videos at 480p or 768p with a prompt of up to 5,000 characters.
  * Image-to-video follows the first frame's proportions. Reference-to-video requires at least one image or video and accepts up to nine images, three videos, and three audio recordings, with twelve references total.
  * Creation returns `202` with a `video_id`. Poll the status endpoint until `completed`, `failed`, or `cancelled`; completed results include a download URL, and unsuccessful results include failure details.
  * Send an `Idempotency-Key` header when submitting so a retry does not start a second generation. API keys need `videos:write` to create and `videos:read` to poll.
</Update>

<Update label="ElevenLabs Model Selection" description="Added - September 2026">
  **Choose an ElevenLabs model for one speech request**

  [`POST /v3/voices/speech`](/reference/generate-speech) now accepts `settings.model_id` with `engine: "elevenlabs"`. Supported models include `eleven_v4`, `eleven_v3`, `eleven_multilingual_v2`, `eleven_flash_v2`, `eleven_flash_v2_5`, and `eleven_turbo_v2_5`.

  * The setting overrides the voice's saved model preference for this request only. Omit `settings` to retain that preference.
  * The deprecated `elevenlabs_v3` engine retains its existing behavior while callers migrate. New integrations should select the model through `settings.model_id`.
</Update>

<Update label="Assets Library Folder Support" description="Changed - September 2026">
  **Recognize Assets library folders when reading and placing results**

  [`GET /v3/folders/{folder_id}`](/reference/get-folder) documents `asset` alongside `mixed`, `video`, and `video_translate` folder types. Existing Assets library folder IDs are also accepted by routes with a `folder_id` destination.

  * Assets library folders are created in the HeyGen app and are flat: [`POST /v3/folders`](/reference/create-folder) cannot create them or nest another folder inside them.
  * The HeyGen app displays only assets in Assets library folders, so a video or translation placed there may not appear in that view.
</Update>

<Update label="Folders on v3" description="Added - September 2026">
  **Create folders and file outputs into them over the API**

  New endpoints: [`POST /v3/folders`](/reference/create-folder) creates a folder, and [`GET /v3/folders/{folder_id}`](/reference/get-folder) returns one so a stored id can be checked before use. This is the v3 successor to `POST /v1/folders/create`.

  * Send `name` (1 to 256 characters) and an optional `parent_id` to nest the folder inside another one. Leave `parent_id` out to create it at the workspace root. Build a tree one level at a time, passing each new `folder_id` as the next `parent_id`.
  * `type` is `mixed` (the default, same as the web app's New folder action), `video`, or `video_translate`. Every type accepts videos and translations.
  * Pass the returned `folder_id` on [`POST /v3/videos`](/reference/create-video), [`POST /v3/video-translations`](/reference/create-video-translation), [`POST /v3/video-translations/proofreads`](/reference/create-proofread-session), [`POST /v3/lipsyncs`](/reference/create-lipsync), or [`POST /v3/templates/{template_id}`](/reference/generate-video-from-template) to place the output in that folder. A `folder_id` outside your workspace is rejected.
  * Send an `Idempotency-Key` header so a retried create does not leave a duplicate folder behind.
</Update>

<Update label="Professional Voice Pause Tags" description="Changed - September 2026">
  **Use explicit pauses with a professional HeyGen voice clone**

  The text input documentation for [`POST /v3/models/audio/tts`](/reference/generate-model-speech) and [`POST /v3/models/audio/tts/stream`](/reference/stream-speech) now clarifies support for `<break time="0.5s"/>` with professional voice clones. Pause values are in seconds, with a maximum of five seconds per pause; other SSML tags and break tags for instant voice clones are unsupported.
</Update>

<Update label="Scene-Scoped Edits for Video Agent" description="Added - September 2026">
  **Revise the scenes you name and keep the rest**

  [`POST /v3/video-agents/{session_id}`](/reference/send-message-or-request-revision) now accepts an `edit_plan`: one natural-language change per scene, applied together in a single turn. Untouched scenes keep their script and visuals, so a two-scene fix stays a two-scene fix.

  * Read scene ids and the document's `edit_version` from [`GET /v3/videos/{video_id}/scenes`](/reference/get-video-scenes), then send each item with its `scene_id`, `text`, `scene_snapshot_video_id`, and `edit_version`. `message` is optional when a plan is sent.
  * Works on sessions created in `generate` or `chat` mode. The response returns the new working draft in `video_id`; poll [`GET /v3/videos/{video_id}`](/reference/get-video) for status.
  * The whole plan is validated before submission: a scene outside the snapshot returns `400` `invalid_parameter`, and a snapshot that changed since it was read returns `409` `stale_edit_version`. Up to 50 items per request.
  * See the new [Edit Scenes](/docs/edit-scenes) guide, with a before/after example.
</Update>

<Update label="Look Packs over the API" description="Added - September 2026">
  **Dress an avatar you already own in a curated set of looks**

  New endpoint: [`POST /v3/avatars/looks`](/reference/create-avatar-looks) generates new looks for an existing avatar. Pass one look you own as `reference_look_id` and a curated `template_id`; the results join that look's character. Their ids are returned immediately, but video generation must wait for the looks to finish processing.

  * `type: "look_pack"` applies a Look Pack, a curated set built around one theme, and the pack decides how many looks it produces. Generation is 16:9, and `aspect_ratio: "9:16"` center-crops the delivered frames to portrait.
  * `type: "template"` restyles the reference look into a single look template, returning two looks in the template's aspect ratio.
  * Public templates work for every workspace; enterprise custom packs assigned to a workspace work the same way on this endpoint.
  * The response returns the character as `group_id` and one id per look. Poll [`GET /v3/avatars/looks/{look_id}`](/reference/get-avatar-look) until each reports `completed` or `failed`.
  * Send an `Idempotency-Key` header so a retry cannot start a second run: a retry while the original is in flight returns `409` `request_in_progress`, and one after it finishes replays the original response.
  * See the new [Look Packs and Templates](/docs/avatar-look-packs) guide.
</Update>

<Update label="Avatar Creation Guides" description="Changed - September 2026">
  **One guide per creation path**

  The Create Avatar guide is now a router into four focused guides: [Video to Avatar](/docs/avatar-from-video), [Photo to Avatar](/docs/avatar-from-photo), [Prompt to Avatar](/docs/avatar-from-prompt), and [Look Packs and Templates](/docs/avatar-look-packs). Each one carries the request, the polling loop, the failure codes, and the render step for that path. [Create Avatar](/docs/create-avatar) keeps the shared response shape and the avatars-versus-looks model.
</Update>

<Update label="API Key Introspection, Avatar Default Voice, Housekeeping Endpoints" description="Added - September 2026">
  **Inspect your key, set an avatar's default voice, and clean up glossaries and proofread sessions**

  * [`GET /v3/api_keys/self`](/reference/get-current-api-key) returns the name, `scope_mode`, `scopes`, and expiration of the key making the request. Works with any key. See [API Key](/docs/api-key#restricting-key-permissions).
  * [`PATCH /v3/avatars/{group_id}`](/reference/update-avatar-group) sets `default_voice_id` on an avatar you own. See [Avatars](/docs/avatars#get-a-single-avatar-group).
  * [`DELETE /v3/brand-glossaries/{brand_glossary_id}`](/reference/delete-brand-glossary) removes a glossary. See [Brand Glossary](/docs/brand-glossary#delete).
  * [`GET /v3/video-translations/proofreads`](/reference/list-proofread-sessions) lists proofread sessions and [`DELETE /v3/video-translations/proofreads/{proofread_id}`](/reference/delete-proofread-session) removes one. See [Video Translation Precision](/docs/video-translation-precision#list-and-delete-proofread-sessions).
</Update>

<Update label="Burst Concurrency" description="Added - September 2026">
  **Run above your included concurrency on demand**

  Enterprise workspaces can now turn on burst instead of buying a higher permanent concurrency cap. Set an extra cap of up to +50 under **Capacity → Concurrency** in [Usage](https://app.heygen.com/developers/usage). The cap applies to avatar renders and video translations separately, so [`POST /v3/videos`](/reference/create-video) and [`POST /v3/video-translations`](/reference/create-video-translation) each accept requests up to *included + extra* concurrent workflows of their type before returning `429`.

  * Workflows admitted while every included slot is busy bill at **1.5×** your contract rate; workflows that land in an included slot bill at the normal rate. You only pay the premium for workflows that actually burst.
  * Burst workflows are tagged **Burst** in the [Activity tab](https://app.heygen.com/developers/usage?tab=activity), and a Burst panel in the Usage sidebar totals the premium for the period.
  * Burst is shared across the web app and the API. It is enabled per workspace by your account team; see [Burst Concurrency](/docs/burst) and the updated [Usage Limits](/docs/usage-limits#concurrency-limits).
</Update>

<Update label="Translation Rules on Brand Glossaries" description="Added - September 2026">
  **Set do-not-translate terms and forced translations over the API**

  [`POST /v3/brand-glossaries`](/reference/create-brand-glossary) and [`PATCH /v3/brand-glossaries/{brand_glossary_id}`](/reference/update-brand-glossary) now accept two translation lists alongside `terms`:

  * `do_not_translate_terms`: `[{ "term": "HeyGen" }]` keeps each term untranslated in every target language.
  * `forced_translations`: `[{ "term": "CEO", "translation": "Geschäftsführer" }]` replaces each term with its exact translation, inserted verbatim.
  * Both lists behave like `terms` on `PATCH`: send a list to replace it, an empty list to clear it, omit it to leave it alone. [`GET /v3/brand-glossaries/{brand_glossary_id}`](/reference/get-brand-glossary) returns them whenever a glossary has rules, including glossaries set up in the HeyGen app.
  * The rules apply whenever the glossary is used by a translation feature: over the API on [video translation](/docs/video-translate), and in the HeyGen app when a Studio or Video Agent draft is translated. Plain video generation and text-to-speech use `terms` alone. Tone settings stay managed in the HeyGen app.
  * Migrating off `/v1/brand_voice` before the October 31, 2026 sunset: `vocabulary` maps to `terms`, `blacklist` to `do_not_translate_terms`, `whitelist` to `forced_translations`. See the [mapping table](/docs/brand-glossary#migrating-from-v1-brand-voice).
</Update>

<Update label="HeyGen Professional Voice Clone" description="Added - September 2026">
  **Train a studio-grade voice clone on the HeyGen Voice model**

  Professional voice cloning is now available on the [HeyGen Voice](/docs/models/heygen-voice) model, HeyGen's in-house voice model. Train a dedicated voice adapter from 1–10 recordings of the same speaker totaling 20+ minutes, then generate speech with it.

  * `POST /v3/models/audio/voices` creates a voice, or retrains an existing one when `voice_id` is supplied. Poll `GET /v3/models/audio/voices/{voice_id}` until `status` is `ACTIVE`. See [HeyGen Professional Clone](/docs/voices/professional-voice-clone).
  * `POST /v3/models/audio/tts` returns one completed 44.1 kHz WAV; `POST /v3/models/audio/tts/stream` streams ordered audio parts over Server-Sent Events with optional word timestamps. See [HeyGen Voice Speech](/docs/voices/heygen-voice-speech).
  * This is a paid feature: each voice occupies a purchased professional voice clone slot, bought on the [Usage page](https://platform.heygen.com/usage). Each slot includes five trainings per monthly billing period, and synthesis bills at 0.6 API credits per generated minute. A voice beyond the workspace's slot limit returns `voice_expired` until a slot is added.
  * For a clone from a single short recording, HeyGen Instant Clone remains available to all API plans.
</Update>

<Update label="Brand Glossaries for Video Agent" description="Added - August 2026">
  **Brand the look and the narration in one request**

  [`POST /v3/video-agents`](/reference/create-video-agent-session) now accepts `brand_glossary_id`, so the narration the agent writes and voices pronounces your terms your way — the same field already accepted by [Studio](/studio-videos), [Templates](/templates), and [Video Translate](/docs/video-translate) requests.

  * Combines with `brand_kit_id` on the same request, making Video Agent the one endpoint that takes both: the kit shapes what you see, the glossary shapes what you hear.
  * The glossary is set at session creation and covers the whole session; a follow-up message in an [interactive session](/docs/interactive-sessions) can swap the brand kit but not the glossary.
  * Pronunciation affects the synthesized audio only — captions and subtitles keep the original spelling. See [Brand Glossary](/docs/brand-glossary) and [On Brand](/docs/on-brand).
</Update>

<Update label="Read a Video's Scenes" description="Added - August 2026">
  **Inspect the full composition behind any video id**

  New endpoint: [`GET /v3/videos/{video_id}/scenes`](/reference/get-video-scenes) returns a video's scene-by-scene composition — what each scene shows and says — together with the video-level context needed to read it (title, aspect ratio, resolution, captions, brand glossary).

  * Works for any video in your workspace, whichever surface created it: a [studio request](/studio-videos), a [template render](/templates), an [avatar video](/generate-avatar-video), or a video composed by hand in the editor. It describes the video as it stands now, including editor changes made after creation.
  * Each scene splits by role: `background` fills the frame, `elements` are placed within it, `script` is the audio over it — synthesized speech (verbatim text, voice id, voice settings), uploaded audio, or a held silence. Walking `scenes[].script[].text` yields the full narration in playback order.
  * Element types are an open set: `avatar`, `image`, and `video` are described in full, containers carry their children, and other types arrive as placeholders to skip.
  * See the new [Video Details](/video-details) guide for how this pairs with [`GET /v3/videos/{video_id}`](/reference/get-video) — which now returns the full deliverable set: `gif_url`, `captioned_video_url`, `subtitle_url`, `completed_at`, `folder_id`, `video_page_url`, and failure details alongside the MP4 and thumbnail.
</Update>

<Update label="Update and Delete Brand Kits" description="Added - August 2026">
  **Correct a kit's role assignments, or remove the kit**

  * [`PATCH /v3/brand-kits/{brand_kit_id}`](/reference/update-brand-kit) sets `name`, `color_roles`, `logo_roles`, and `font_roles`. An omitted field is left unchanged; a role object you send replaces the stored one in full. Role edits need an assembled kit and return `409` while `status` is `loading`.
  * [`DELETE /v3/brand-kits/{brand_kit_id}`](/reference/delete-brand-kit) removes a kit and the colors, logos, and fonts it holds. Videos already generated keep their branding.
  * The colors, logos, and font files themselves stay curated in the HeyGen app, where a kit keeps its `brand_kit_id`. See [Brand Kits](/docs/brand-kits).
</Update>

<Update label="Create Brand Kits from a Website" description="Added - August 2026">
  **Import a brand's logos, colors, and fonts over the API**

  [`POST /v3/brand-kits`](/reference/create-brand-kit) builds a brand kit from a public website URL, so a workspace can go from a domain to on-brand [Video Agent](/docs/video-agent) output without opening the HeyGen app.

  * The response returns a `brand_kit_id` that is usable immediately with `status: "loading"`. Poll [`GET /v3/brand-kits/{brand_kit_id}`](/reference/get-brand-kit) every 2 to 5 seconds until `status` is `completed` before relying on the imported colors, logos, or fonts.
  * The detail response adds `color_roles`, `logo_roles`, and `font_roles`, naming which asset plays which part in the brand's visual system.
  * Send an `Idempotency-Key` header to make retries safe. See [Brand Kits](/docs/brand-kits).
</Update>

<Update label="Create and Update Brand Glossaries" description="Added - August 2026">
  **Manage custom pronunciations programmatically**

  Brand glossaries can now be created and edited over the API, so a per-tenant vocabulary can be provisioned and kept in sync from your own system.

  * [`POST /v3/brand-glossaries`](/reference/create-brand-glossary) creates a glossary from a `name` and an optional list of `terms`. Names are unique per workspace, compared without regard to case; a duplicate returns `409`.
  * [`PATCH /v3/brand-glossaries/{brand_glossary_id}`](/reference/update-brand-glossary) replaces `name` or `terms` in full — an omitted field is untouched, and an empty `terms` array clears the list.
  * Translation rules stay managed in the HeyGen web app and are never modified by an update made here. See [Brand Glossary](/docs/brand-glossary).
</Update>

<Update label="Consent Video Upload Available for All Enterprise Accounts" description="Changed - August 2026">
  **Level 2 consent is no longer gated behind a whitelist**

  Uploading a pre-recorded consent video (Level 2) is now available to every Enterprise account. Previously the flow required whitelisting; that gate has been removed.

  * Enterprise customers can send `consent_video` on [`POST /v3/avatars/{group_id}/consent`](/reference/create-avatar-consent) without requesting access first.
  * The webcam flow (Level 1) is unchanged and remains available to all customers. Skip-consent (Level 3) still requires an indemnity agreement — [contact sales](https://www.heygen.com/contact-us/sales).
  * See [Avatar Consent](/docs/avatar-consent) for the three levels and the required consent statement.
</Update>

<Update label="Brand Glossaries for Avatar and Image Videos" description="Added - August 2026">
  **Apply custom pronunciations to direct video-creation requests**

  [`POST /v3/videos`](/reference/create-video) and [`POST /v3/videos/batches`](/reference/create-video-batch) now accept `brand_glossary_id` for both `"type": "avatar"` and `"type": "image"` payloads.

  * The glossary applies when HeyGen synthesizes audio from a `script`; caller-supplied `audio_url` and `audio_asset_id` inputs are unchanged.
  * Custom pronunciations affect generated speech only. Captions and subtitle files retain the script's original spelling.
  * Discover available IDs with [`GET /v3/brand-glossaries`](/reference/list-brand-glossaries), then inspect individual term mappings with [`GET /v3/brand-glossaries/{brand_glossary_id}`](/reference/get-brand-glossary).
</Update>

<Update label="Captions Always Available for Translations and Lipsyncs" description="Changed - August 2026">
  **Caption sidecars are generated for every completed job**

  Caption-generation flags on video translation and lipsync requests are now deprecated and ignored. Captions are always generated; clients choose whether to display or download them.

  * `enable_caption` is deprecated on `POST /v3/video-translations`, `POST /v3/video-translations/batches`, `POST /v3/lipsyncs`, and `POST /v3/lipsyncs/batches`.
  * The `captions` flag is likewise deprecated when generating a video from a completed translation proofread.
  * Completed video-translation responses expose their SRT and VTT caption URLs regardless of the submitted flag. Existing requests remain compatible.
</Update>

<Update label="Avatar V Photo Fallback" description="Changed - August 2026">
  **Photo avatars can render without an animation-reference look**

  When an Avatar V photo avatar's group has no eligible digital-twin or curated reference look, video creation now renders directly from the photo instead of rejecting the request.

  * The fallback works when `reference_look_id` is omitted and no eligible look can be selected automatically.
  * `motion_prompt` still requires an animation reference for Avatar V photo avatars. Supply an eligible reference look when you need prompted body motion or hand gestures.
</Update>

<Update label="Brand Glossary on Studio Videos" description="Added - July 2026">
  **Control how custom terms are pronounced, and read a glossary's terms over the API**

  A brand glossary maps a term to how it should be spoken, such as `HeyGen` as `hey-jen`. Two additions and one rename cleanup:

  * **[HeyGen Studio](/studio-videos) accepts `brand_glossary_id`.** Pass it on a `"type": "studio"` request to apply the glossary to every scene whose audio is synthesized from a `script`. Scenes that supply their own `audio_url` or `audio_asset_id` are unaffected. Pronunciations change the generated audio only: captions and the `.srt` sidecar keep the original spelling.
  * **New endpoint: [`GET /v3/brand-glossaries/{brand_glossary_id}`](/reference/get-brand-glossary).** Returns a glossary with its full term list, so you can confirm exactly which terms are remapped and how. Previously [`GET /v3/brand-glossaries`](/reference/list-brand-glossaries) could tell you a glossary existed but not what was in it.
  * **`brand_voice_id` is now deprecated in favor of `brand_glossary_id`** across the v3 endpoints that accept it, including [`POST /v3/templates/{template_id}`](/reference/generate-video-from-template), which now accepts both names. Existing requests keep working, since `brand_voice_id` continues to resolve to the same glossary.
</Update>

<Update label="Video Agent Powered by Hyperframes" description="Changed - July 2026">
  **Every Video Agent scene is now composed and rendered with Hyperframes**

  The [Video Agent](/docs/video-agent) now authors every animated stat, chart, caption, and scene transition as a [Hyperframes](/hyperframes-overview) composition — scenes are built in code, not assembled from a fixed template set. In practice, that means the agent can produce any look you can describe: pass a `style_id` for a curated preset, or write a **style paragraph** in your prompt and the agent renders to it literally.

  * New guide: [Prompting Guide](/docs/prompting-guide) — how to write a prompt that lands on the first cut, including the anatomy of a style paragraph (name, palette, art direction, motion, transitions, vibe).
  * Updated [Prompt to Video](/docs/video-agent) to document the Hyperframes-powered rendering path.
  * No API changes required — existing [`POST /v3/video-agents`](/reference/create-video-agent-session) requests automatically benefit.
</Update>

<Update label="Studio Video-Scene Voiceover" description="Added - July 2026">
  **Narrate over an existing clip and control how it fills the scene**

  `video` scenes in a [HeyGen Studio](/studio-videos) request now accept an optional voiceover — the same audio inputs a narrated `image` scene takes (`script` + `voice_id`, `audio_url`, or `audio_asset_id`). When present, the voiceover drives the scene's duration instead of the clip's own length.

  * **Scene-duration alignment:** a new `playback.mode` chooses how the clip fills the voiceover-driven duration — `freeze` (hold the last frame, the default), `loop` (repeat the clip), or `fit_to_scene` (adjust playback speed to end exactly with the voiceover).
  * The voiceover and the clip's own audio compose: keep using `playback.volume` / `mute` to bring the clip down under narration.
  * See [Video Scenes](/studio-videos#video-scenes) in the HeyGen Studio guide.
</Update>

<Update label="HeyGen Studio Scene Composition" description="Added - July 2026">
  **Compose avatar clips, images, and video footage into one video with a single API call**

  [`POST /v3/videos`](/reference/create-video) accepts a new creation mode, `"type": "studio"` — send an ordered list of whole-frame scenes and get back one rendered MP4. HeyGen owns the layout: every scene is rendered onto one global output canvas, scene durations are derived server-side, and a single `video_id` tracks the all-or-nothing render.

  * New guide: [HeyGen Studio](/studio-videos) under Video Composition.
  * **Three scene types**, mixable in one request (1–50 scenes): `avatar_video` (an avatar or lip-synced image speaking a script or audio track, with engine selection, motion prompts, and solid-color backgrounds), `image` (a still held for a set `duration` or narrated), and `video` (an existing clip, with `playback` volume/mute control).
  * **Global output settings** set once per request: `aspect_ratio`, `resolution`, captions (sidecar `subtitle_url` plus optional burn-in), and webhooks.
  * **Not available in batches:** a studio request already composes many scenes into one video, so `"type": "studio"` is not accepted by [`POST /v3/videos/batches`](/reference/create-video-batch). Send studio videos one per request.
</Update>

<Update label="Batch APIs for Translations, Lipsyncs, and Assets" description="Added - July 2026">
  **Every high-volume workflow now has a native batch API**

  Batch creation, introduced for [videos](/batch-videos), now covers video translations, lipsyncs, and asset uploads. Each accepts up to 100 payloads per call, returns a single `batch_id`, processes items independently (one bad item does not fail the rest), and supports `Idempotency-Key` retries.

  * New guides under Batches: [Video Translations](/batch-video-translations), [Lipsyncs](/batch-lipsyncs), and [Assets](/batch-assets).
  * **Translations:** [`POST /v3/video-translations/batches`](/reference/create-video-translation-batch) — a payload targeting multiple `output_languages` expands to one item per language. Replaces the CSV-script workflow previously documented as Bulk Video Translation.
  * **Lipsyncs:** [`POST /v3/lipsyncs/batches`](/reference/create-lipsync-batch) — payloads identical in shape to `POST /v3/lipsyncs`.
  * **Assets:** [`POST /v3/assets/direct-uploads/batches`](/reference/create-asset-upload-batch) presigns up to 100 direct-to-S3 slots in one call; finalize with [`POST /v3/assets/complete/batches`](/reference/complete-asset-upload-batch).
  * **Bulk status checks:** [`GET /v3/video-translations/statuses`](/reference/bulk-video-translation-statuses), [`GET /v3/lipsyncs/statuses`](/reference/bulk-lipsync-statuses), [`GET /v3/assets/statuses`](/reference/bulk-asset-statuses), and [`GET /v3/videos/statuses`](/reference/bulk-video-statuses) — up to 100 ids per request, by id or by batch.
</Update>

<Update label="HeyGen Studio Template API" description="Added - July 2026">
  **Discover Studio templates and generate videos from them over the API**

  You can now drive [HeyGen Studio](https://app.heygen.com/avatar/studio) templates programmatically — list them, read each one's variable schema, and render a video by filling the variables.

  * New guide: [HeyGen Studio Template](/templates) under Video Composition.
  * **List & inspect:** [`GET /v3/templates`](/reference/list-templates) and [`GET /v3/templates/{template_id}`](/reference/get-template) return each template's variable schema (text, image, video, audio, character, voice) and scenes.
  * **Generate:** [`POST /v3/templates/{template_id}`](/reference/generate-video-from-template) renders a video from your variable values, with options for `scene_ids`, `dimension`, `fps`, captions/subtitles, sharing, and webhooks.
</Update>

<Update label="Batch Video Creation" description="Added - July 2026">
  **Submit up to 100 videos in a single request**

  Queue many videos at once instead of calling [`POST /v3/videos`](/reference/create-video) per video.

  * New guide: [Videos](/batch-videos) under Batches.
  * **Create:** [`POST /v3/videos/batches`](/reference/create-video-batch) accepts up to 100 payloads — each identical in shape to `POST /v3/videos` (`avatar`, `image`, or `cinematic_avatar`) — and returns a single `batch_id`.
  * **Track:** [`GET /v3/videos/batches/{batch_id}`](/reference/get-video-batch) returns aggregate status and per-item `video_id`s; a `callback_url` fires once when the whole batch finishes.
</Update>

<Update label="Upload a Consent Video via API" description="Added - July 2026">
  **Submit a pre-recorded consent video for a digital twin**

  [`POST /v3/avatars/{group_id}/consent`](/reference/create-avatar-consent) now accepts an optional `consent_video` field (as a `url`, `asset_id`, or `base64` asset). When supplied, the video is submitted directly for review — the avatar subject skips the hosted webcam page, and the response contains the avatar group without a consent `url`.

  * Available to Enterprise API accounts with your account whitelisted — please [reach out to sales](https://www.heygen.com/contact-us/sales) or your account team to request access. The same applies to skipping the consent flow entirely.
  * The webcam flow is unchanged and remains the default — see [Avatar Consent](/docs/avatar-consent) for the full breakdown of consent levels.
</Update>

<Update label="Hyperframes + HeyGen" description="Added - July 2026">
  **Compose your avatar videos into finished, produced videos**

  You can now combine a HeyGen avatar video with background music, sound effects, and Hyperframes graphics into a single composed render — Hyperframes acts as the compositor that lays an avatar clip into a designed scene, scores it, and renders it to one MP4.

  * New guide: [Hyperframes + HeyGen](/hyperframes-heygen) — an end-to-end pipeline wiring [`POST /v3/videos`](/reference/create-video), [`GET /v3/audio/sounds`](/background-music) (music and sound effects), and [`POST /v3/hyperframes/renders`](/hyperframes) together.
  * New page: [Introduction to Hyperframes](/hyperframes-overview) — what the framework is, its core concepts, and the ways to render.
  * Pass the avatar `video_url` and audio `audio_url`s into the render as `variables`, so one composition bundle produces many finished videos.
</Update>

<Update label="Avatar III Engine Support" description="Added - June 2026">
  **Support for the Avatar III engine**

  We have expanded the capabilities of `POST /v3/videos` to include support for the Avatar III engine.

  * **`POST /v3/videos`:**
    * Added support for the `avatar_iii` engine configuration.
    * Updated the `engine` property to include `AvatarIIIEngineConfig` in the `oneOf` schema definition, allowing for more flexible engine selection during video creation.
</Update>

<Update label="New Endpoints & Features" description="Added - June 2026">
  **Expanded API functionality and improved asset management**

  We have introduced several new endpoints and configuration options to enhance your workflow:

  * **Voice Management**: Added `DELETE /v3/voices/{voice_id}` for better voice library control.
  * **Avatar & Video Configuration**:
    * `POST /v3/avatars`: Added `avatar_id` as an optional property for more granular prompt-based avatar creation.
    * `POST /v3/videos`: Added `reference_look_id` support within the `AvatarVEngineConfig` to refine video generation.
</Update>

<Update label="Video Translation Improvements" description="Changed - June 2026">
  **Clarified Stock Voice configuration for Video Translation**

  Updated `POST /v2/video_translate` and `POST /v3/video-translations` to better reflect Enterprise capabilities.

  * The `stock_voice_config` documentation has been updated to clarify that this feature uses preset HeyGen voices instead of cloning the original speaker's voice.
  * `preferred_stock_voice_ids` is now explicitly defined as an optional pinning mechanism for stock voices.
  * Note: Stock voice usage is an Enterprise feature gated by account permissions; please contact your HeyGen account team for access.
</Update>

<Update label="Prompt Avatar Visual Reference" description="Changed - June 2026">
  **`avatar_id` is now the visual reference for prompt avatars**

  [`POST /v3/avatars`](/reference/create-avatar) with `type: "prompt"` now accepts an optional `avatar_id` — an existing look used as the visual reference for the generation. `avatar_group_id` no longer drives the reference image.

  * Added `avatar_id` (optional): the look whose image conditions the generation. The new look is saved to the referenced avatar's group; if `avatar_group_id` is also provided, the avatar must belong to that group and the result is saved there. Returns 404 `AVATAR_NOT_FOUND` if the avatar doesn't exist, 400 `INVALID_PARAMETER` if it has no usable image or doesn't belong to the given group.
  * Changed `avatar_group_id`: now only selects the group the generated avatar is saved to. It no longer conditions the generation on one of the group's looks.
  * Changed `reference_images`: no longer requires `avatar_group_id` — it can be used on its own.
  * **Migration Note:** if you passed `avatar_group_id` to keep a character's identity consistent across prompt-generated looks, pass the base look's ID as `avatar_id` instead. Requests with only `avatar_group_id` still succeed, but generate purely from the prompt.
  * `type: "digital_twin"` and `type: "photo"` are unchanged.

  See [Prompt to Avatar](/docs/avatar-from-prompt) for the full behavior matrix.
</Update>

<Update label="Sound Effects Support" description="Added - June 2026">
  **Expanded Audio Search with Sound Effects**

  The audio search functionality has been updated to include support for sound effects, allowing for more versatile audio retrieval beyond just background music.

  * Updated `GET /v3/audio/sounds` to include `sound_effects` as a searchable type.
  * The `type` query parameter now supports `sound_effects` in addition to the default `music`.
  * API responses for `GET /v3/audio/sounds` will now include items with the `sound_effects` type.
  * **Migration Note:** Clients that strictly validate the `type` field in the response against an enum list may need to update their schema definitions to include the new `sound_effects` value to prevent parsing errors.
</Update>

<Update label="Credit Usage Tracking" description="Added - June 2026">
  **Expanded usage insights for user accounts**

  We have updated the user profile endpoints to provide better visibility into your account's credit consumption. You can now track your allocation and remaining balance directly through the API.

  * Added `included_credits` and `remaining_credits` fields to the response objects for:
    * `GET /v1/user/me`
    * `GET /v3/users/me`
</Update>

<Update label="Motion Prompt Enhancements" description="Changed - June 2026">
  **Updated motion prompt capabilities for video generation**

  The `motion_prompt` parameter for video generation now supports additional configurations for hand gestures and broader engine compatibility.

  * Updated `motion_prompt` in `POST /v3/videos`:
    * Now supports natural-language control for both body motion and hand gestures.
    * Expanded support for photo avatars across both engines.
    * Added support for video avatars specifically when using `engine.type: 'avatar_v'`.
</Update>

<Update label="New Video Type: Cinematic Avatar" description="Added - June 2026">
  **Generate cinematic avatar video from a single prompt**

  [`POST /v3/videos`](/reference/create-video) now supports **Cinematic Avatar** — a prompt-driven video type that composes scene, motion, and framing from a natural-language prompt plus one to three avatar looks (with optional reference media). No script or voice required.

  * Added the `CreateVideoFromCinematicAvatar` schema to `POST /v3/videos` via an additive request discriminator (`cinematic_avatar`). Existing `CreateVideoFromAvatar` and `CreateVideoFromImage` requests are unaffected — this is a **non-breaking** change.
  * Billed per video, not by duration. Choose any length from **4 to 15 seconds** via the `duration` parameter.
  * Supports **720p** and **1080p** output.

  No migration required. See the [Cinematic Avatar guide](/avatar-shots) for the full parameter list.
</Update>

<Update label="New Asset and Audio Endpoints" description="Added - June 2026">
  **Expansion of Asset Management and Audio capabilities**

  We have introduced new endpoints to streamline asset handling and provide better access to audio resources.

  * `POST /v3/assets/direct-uploads`: Initialize a direct upload process for your custom assets.
  * `POST /v3/assets/{asset_id}/complete`: Finalize the upload process for a specific asset.
  * `GET /v3/audio/sounds`: Retrieve a list of available audio sounds for your projects.
</Update>

<Update label="HyperFrames Resolution Constraints" description="Changed - June 2026">
  **HyperFrames render resolution is now strictly typed**

  We have updated the `POST /v3/hyperframes/renders` endpoint to enforce strict resolution settings.

  * **Breaking Change:** The `resolution` property in `POST /v3/hyperframes/renders` is now strictly typed as a string enum (`1080p`, `4k`). Null values are no longer accepted.
  * The `resolution` property now defaults to `1080p`.
  * Added optional `aspect_ratio` support for `POST /v3/hyperframes/renders` and response schemas for `GET /v3/hyperframes/renders` and `GET /v3/hyperframes/renders/{render_id}`.

  **Migration Steps:**
  Ensure that any hardcoded `resolution` values sent to `POST /v3/hyperframes/renders` match the new `1080p` or `4k` enum strings. If you were previously sending `null` to indicate a default, you can now safely omit the property.
</Update>

<Update label="HyperFrames Render API — Decomposed Resolution + Aspect Ratio" description="Changed - May 31, 2026">
  **Breaking change: `resolution` is now a tier; `aspect_ratio` is a separate field**

  `POST /v3/hyperframes/renders` previously took a single `resolution` value that conflated aspect ratio and resolution tier into one of six presets (`landscape`, `landscape-4k`, `portrait`, `portrait-4k`, `square`, `square-4k`). The same flat shape lived on `GET /v3/hyperframes/renders/{render_id}`.

  Effective immediately, both endpoints decompose that single field into two:

  * `resolution` ∈ `1080p` | `4k` — output resolution tier. Defaults to `1080p`.
  * `aspect_ratio` ∈ `16:9` | `9:16` | `1:1` — output aspect ratio. Defaults to `16:9` (landscape). `9:16` is portrait; `1:1` is square.

  The new shape matches the existing `/v3/videos` endpoint's `resolution` + `aspect_ratio` fields.

  **Migration table**

  Map each legacy preset to the new pair:

  | OLD `resolution` | NEW |
  | - | - |
  | `landscape` | `{ "resolution": "1080p", "aspect_ratio": "16:9" }` |
  | `landscape-4k` | `{ "resolution": "4k",    "aspect_ratio": "16:9" }` |
  | `portrait` | `{ "resolution": "1080p", "aspect_ratio": "9:16" }` |
  | `portrait-4k` | `{ "resolution": "4k",    "aspect_ratio": "9:16" }` |
  | `square` | `{ "resolution": "1080p", "aspect_ratio": "1:1"  }` |
  | `square-4k` | `{ "resolution": "4k",    "aspect_ratio": "1:1"  }` |

  Requests using the legacy preset strings now return a 422 validation error — only the field shape moves.

  **Not yet supported in this enum surface**: `720p`, `4:5`, `5:4`, and `auto`. These will follow in a separate update once the render pipeline supports the additional values.

  **CLI**

  `npx hyperframes cloud render` is updated in lockstep: the `--resolution` flag now accepts `1080p` | `4k`, and a new `--aspect-ratio` flag accepts `16:9` | `9:16` | `1:1`. Legacy values are rejected at the CLI layer with the same migration mapping.
</Update>

<Update label="Brand Glossaries and Video Translation Enhancements" description="Added - May 2026">
  **Introducing Brand Glossaries for Video Translation**

  We have introduced Brand Glossaries to help maintain consistency in your video translations. You can now define custom term mappings to ensure specific terminology is translated accurately according to your brand guidelines.

  * Added `GET /v3/brand-glossaries` to list and discover your available brand glossaries.
  * Added `brand_glossary_id` as an optional request parameter to `POST /v2/video_translate` and `POST /v3/video-translations/proofreads`.
  * The `brand_voice_id` parameter in these endpoints now acts as a legacy alias for `brand_glossary_id`, ensuring backward compatibility for your existing integrations.
</Update>

<Update label="API Documentation and Default Parameter Updates" description="Changed - May 2026">
  **Refined API documentation and aspect ratio defaults**

  We have updated our API documentation across various endpoints to provide clearer guidance on usage and functionality. Additionally, we have updated the default behavior for aspect ratio selection.

  * Updated `POST /v2/videos` and `POST /v3/videos` to clarify that the `aspect_ratio` defaults to `'16:9'` if not specified.
  * Documentation descriptions for endpoints across Avatars, Lipsync, Video Agents, and Webhooks have been streamlined for improved clarity.
  * Updated API tags for `GET /v3/brand-kits`, moving them under the `Brand` category.
</Update>

<Update label="New Aspect Ratios for Social Formats" description="Added - May 25, 2026">
  **Generate videos in square, portrait, landscape, and source-matched ratios**

  `POST /v2/videos` and [`POST /v3/videos`](/reference/create-video) now accept four additional values for `aspect_ratio`:

  * `1:1` — square, great for feed posts
  * `4:5` — portrait, optimized for Instagram and LinkedIn feeds
  * `5:4` — landscape variant for feed placements
  * `auto` — detects the source's dimensions (avatar footage or uploaded image) and preserves the original ratio, falling back to `16:9` when the source can't be read

  Combine these with the existing `16:9` and `9:16` options to target multiple placements from a single integration.
</Update>

<Update label="New Endpoint: Get Asset" description="Added - May 25, 2026">
  **Retrieve metadata for an individual asset**

  [`GET /v3/assets/{asset_id}`](/reference/get-asset) returns metadata for an asset in your workspace — including owner, upload timestamp, file type, and a publicly accessible URL. Use it to look up uploads on demand instead of paginating through the full asset list.
</Update>

<Update label="Optional `consent_text` on Avatar Consent" description="Changed - May 25, 2026">
  **Record the exact consent language presented to the avatar subject**

  [`POST /v3/avatars/{group_id}/consent`](/reference/create-avatar-consent) now accepts an optional `consent_text` field. Pass the wording the subject agreed to so you have a clear audit trail alongside the recorded consent. The field is optional — existing integrations continue to work unchanged.
</Update>

<Update label="New `download_failed` Error Code" description="Added - May 18, 2026">
  **Clearer signal when a user-supplied URL can't be fetched**

  Requests that include a URL for video, image, audio, or any other resource can now return a dedicated `download_failed` error (HTTP `400`) when the URL can't be downloaded. The `message` field tells you which URL failed and why.

  Common causes:

  * URL isn't publicly accessible (auth required, private video, restricted sharing).
  * URL is malformed or points to a page rather than a direct file.
  * Remote server refused the connection or returned an error.
  * Google Drive links must be shared with **Anyone with the link**.
  * YouTube/Vimeo videos must be **public** — unlisted or private videos aren't supported.

  The `resource_limit_exceeded` error message also now covers instant-avatar redo attempts and verified avatar group slots, with guidance to wait for limits to reset where applicable.

  See the [error codes reference](/docs/error-codes) for the full list.
</Update>

<Update label="API Updates" description="Added - May 2026">
  **Added Idempotency support and expanded API capabilities**

  We have introduced support for the `Idempotency-Key` header across key endpoints to ensure safe retries for POST requests. Additionally, several endpoints now return a `409 Conflict` status to handle concurrent requests or state conflicts.

  * **Idempotency-Key Support:** Added to `POST /v3/assets`, `POST /v3/avatars`, `POST /v3/avatars/{group_id}/consent`, `POST /v3/lipsyncs`, `POST /v3/video-translations`, `POST /v3/video-translations/proofreads`, `POST /v3/video-translations/proofreads/{proofread_id}/generate`, `POST /v3/videos`, `POST /v3/webhooks/endpoints`, and `POST /v3/webhooks/endpoints/{endpoint_id}/rotate-secret`.
  * **New Endpoints:** Added `DELETE /v3/assets/{asset_id}`, `DELETE /v3/avatars/looks/{look_id}`, and `DELETE /v3/avatars/{group_id}`.
  * **Default Values:** The `aspect_ratio` parameter now defaults to `16:9` in `POST /v2/videos` and `POST /v3/videos`.
</Update>

<Update label="Video Translation Improvements" description="Changed - May 2026">
  **Strict schema validation for frame rate modes**

  The `fps_mode` property in `POST /v3/video-translations` has been updated to use a strict enum, ensuring more predictable behavior for video output.

  * **Breaking Change:** The `fps_mode` property is now restricted to an enum. Supported values are now explicitly defined as `vfr`, `cfr`, and `passthrough`.
  * **Migration:** Ensure your integration passes one of these three strings. Previously provided custom values may now be rejected.
</Update>

<Update label="Corrected `avatar_video.success` Webhook Payload Fields" description="Fixed - May 11, 2026">
  **Webhook payload field names now match what's actually delivered**

  The documented payload for the `avatar_video.success` webhook event has been corrected. If you wired up handlers from the previous documentation, double-check the field names you're reading — the live payload uses these keys:

  * `video_id`, `url`, `gif_download_url`, `video_page_url`, `video_share_page_url`, `folder_id`, `callback_id`

  No change to the webhook delivery itself — this aligns the [webhook events reference](/docs/webhook-events) with the payload the API has been sending.
</Update>

<Update label="Video Engine Updates & Brand Kit Support" description="Changed - May 2026">
  **Video engine updates and new brand kit integration**

  We have updated the video generation workflow and introduced support for Brand Kits across Video Agents. Note that the `engine` parameter structure for `POST /v3/videos` has changed, which is a breaking change for existing integrations.

  * **Breaking Change:** The `engine` property in `POST /v3/videos` now requires an object structure (e.g., `{"type": "avatar_v"}`) instead of a string. `ApiAvatarEngine` has been removed.
  * **Video Scaling:** Added a new optional `fit` parameter to `POST /v3/videos` for both `CreateVideoFromAvatar` and `CreateVideoFromImage` request types.
  * **Brand Kits:** Added `brand_kit_id` as an optional parameter to `POST /v3/video-agents` and `POST /v3/video-agents/{session_id}`.
  * **New Endpoint:** Added `GET /v3/brand-kits` to retrieve available brand kit resources.
  * **Parameter Constraints:** Note that `expressiveness` and `motion_prompt` in `POST /v3/videos` are now strictly for Avatar IV and are not supported when `engine.type` is set to `avatar_v`.
</Update>

<Update label="Support for Stock TTS and Engine Selection" description="Added - May 2026">
  **New configuration options for Video Translation and Video Generation**

  We have introduced support for Stock TTS in video translations and added explicit engine selection for avatar-based video generation.

  * **Video Translation:** Added `stock_voice_config` to `POST /v2/video_translate` and `POST /v3/video-translations`. This allows users to opt into Stock TTS instead of using Voice Cloning.
  * **Video Generation:** Added an optional `engine` field to `POST /v3/videos` (for `CreateVideoFromAvatar` requests). You can now explicitly select between Avatar IV and Avatar V engines. If omitted, the system defaults to Avatar IV.
</Update>

<Update label="Avatar Engine Metadata Updates" description="Changed - May 2026">
  **Updated schema definitions for Avatar engine support**

  Metadata for supported API engines has been updated across the avatar look endpoints to ensure consistency when retrieving avatar configurations.

  * Updated `supported_api_engines` fields in:
    * `POST /v3/avatars`
    * `GET /v3/avatars/looks`
    * `GET /v3/avatars/looks/{look_id}`
    * `PATCH /v3/avatars/looks/{look_id}`
</Update>

<Update label="Custom Watermark Controls" description="Added - April 30, 2026">
  **Fine-tune watermark size, transparency, and position**

  The `watermark` object on `POST /v3/videos` now accepts three new optional fields for finer control over how your watermark renders:

  * `scale` (number, `0`–`2`, default `1.0`) — adjust the watermark size relative to its native resolution.
  * `opacity` (number, `0`–`1`, default `1.0`) — control transparency.
  * `placement` — choose an anchor corner (`top_left`, `top_right`, `bottom_left`, `bottom_right`) and apply fractional `offset_x` / `offset_y` values for precise positioning.

  All fields are optional and backward-compatible. Omitting them preserves the existing bottom-right default behavior.
</Update>

<Update label="Voice Cloning API" description="Added - April 27, 2026">
  **Programmatic voice cloning is now available**

  You can now create and manage voice clones directly from the API, no dashboard step required.

  * `POST /v3/voices/clone` initiates a clone from a reference audio sample.
  * `GET /v3/voices/{voice_id}` returns clone status and details so you can poll until processing completes.
  * Use the resulting `voice_id` anywhere a voice is accepted (`POST /v3/videos`, `POST /v3/voices/speech`, etc.).

  See the [voices overview](/docs/voices/overview) for details.
</Update>

<Update label="Burned-in Captions" description="Added - April 27, 2026">
  **Render captions directly into your videos**

  `POST /v2/videos` and `POST /v3/videos` now accept a `caption.style` field. Set it to burn captions into the rendered video instead of (or in addition to) consuming the sidecar subtitle file at `subtitle_url`.

  Useful for social platforms where viewers watch with sound off and you want captions baked into the asset.
</Update>

<Update label="Custom Watermarks" description="Added - April 27, 2026">
  **Apply your own watermark to generated videos**

  `POST /v3/videos` accepts a new optional `watermark` property on both `CreateVideoFromAvatar` and `CreateVideoFromImage` requests. Pass a PNG or JPEG image to overlay it onto the rendered output — handy for branding, attribution, or moderation marks.

  Available as a premium option for select Enterprise customers — [contact support](https://help.heygen.com) to request access.
</Update>

<Update label="Watermark Schema Refactor" description="Changed - April 27, 2026">
  **`watermark` now uses the `WatermarkInput` schema**

  The inline schema previously used for the `watermark` field on video generation requests has been replaced with the dedicated `WatermarkInput` type. The shape of the property has changed — update existing payloads to match the new schema before upgrading.
</Update>

<Update label="Video Title Search Requires a Value" description="Changed - April 27, 2026">
  **Empty `title` queries are no longer accepted**

  `GET /v2/videos` and `GET /v3/videos` now require at least one character for the `title` query parameter (`minLength` increased from 0 to 1). Omit the parameter entirely if you don't want to filter by title — sending an empty string will return a validation error.
</Update>

<Update label="Clearer Voice Clone Quota Errors" description="Fixed - April 27, 2026">
  **Better error feedback when the voice clone limit is reached**

  `POST /v3/voices/clone` now returns the `resource_limit_reached` error code (HTTP 400) when your account has hit its voice clone quota, instead of a generic validation error. The response message tells you to delete unused clones or contact support to raise the limit. See the [error codes reference](/docs/error-codes#resource-limit-reached) for handling guidance.
</Update>

<Update label="MCP Server Updates" description="Added - April 2026">
  **Expanded tool coverage for the HeyGen MCP server**

  The HeyGen Remote MCP server now includes tools for managing avatars, videos, lipsync, and video translation — making more of the API accessible to AI agents like Claude, Cursor, Gemini CLI, and Manus.

  * Added avatar management tools: `create_digital_twin`, `create_photo_avatar`, `create_prompt_avatar`, `create_avatar_consent`, `list_avatar_looks`, `get_avatar_look`, `update_avatar_look`, and more.
  * Added full video CRUD: `create_video_from_avatar`, `create_video_from_image`, `list_videos`, `get_video`, `delete_video`.
  * Added lipsync and video translation management tools.
  * Added `design_voice` for finding voices from a natural-language description.
  * See the [MCP overview](/mcp/overview) for the full tool list.
</Update>

<Update label="HeyGen CLI v0.0.4" description="Added - April 2026">
  **CLI command surface synced with v3 API**

  The HeyGen CLI now covers all v3 endpoints, including Video Agent, Lipsync, Video Translation (with Proofreads), Webhooks, and Assets.

  * Added `--wait` flag for blocking until async operations complete, with configurable `--timeout`.
  * Added `--request-schema` and `--response-schema` flags to inspect API schemas without authentication.
  * Added `--force` flag for non-interactive destructive operations in CI.
  * See the [CLI commands](/commands) and [features](/features) pages for usage details.
</Update>

<Update label="v1/v2 API Deprecation Timeline" description="Changed - April 2026">
  **v1 and v2 endpoints sunset on October 31, 2026**

  A formal deprecation timeline is now in place for the v1 and v2 API. Both versions remain fully operational through October 31, 2026, after which they will be retired.

  * Studio API (multi-scene) and Template API will continue to be supported on v2 until a v3 equivalent is available.
  * See the [endpoint version comparison](/endpoint-version-comparison) for a full migration checklist and feature comparison.
</Update>

<Update label="New API Error Codes" description="Added - April 2026">
  **More granular error responses across the API**

  New error codes provide clearer feedback when requests fail, making it easier to handle edge cases in your integration.

  * `ai_vendor_access_restricted` — workspace AI vendor policy blocks the request.
  * `unlimited_mode_disabled` — avatar doesn't support unlimited mode.
  * `voice_unavailable` — cloned voice failed processing or expired.
  * `ephemeral_upload_disabled` — eager upload temporarily disabled for the account.
  * `gateway_timeout` — external resource could not be fetched in time.
  * See the full [error codes reference](/docs/error-codes) for details and troubleshooting.
</Update>

<Update label="Starfish Engine Integration" description="Changed - April 2026">
  **New requirement for Starfish engine compatibility**

  Text-to-speech generation endpoints now require the use of voices that support the Starfish engine.

  * Updated `POST /v1/audio/text_to_speech` and `POST /v3/voices/speech` documentation.
  * Developers should filter for compatible voices by passing `engine=starfish` when calling the voice listing endpoints.
</Update>

<Update label="Asset ID Documentation Update" description="Changed - April 2026">
  **Standardized Asset ID descriptions**

  Documentation across multiple endpoints has been clarified to consistently refer to asset IDs originating from the HeyGen asset upload endpoint. No functional changes were made to the API behavior.

  * Applies to request bodies for:
    * `POST /v3/avatars`
    * `POST /v3/lipsyncs`
    * `POST /v3/video-agents` and `POST /v3/video-agents/{session_id}`
    * `POST /v3/video-translations`, `POST /v3/video-translations/proofreads`, and `PUT /v3/video-translations/proofreads/{proofread_id}/srt`
    * `POST /v3/videos`
</Update>

<Update label="New Video Agents Endpoint" description="Added - April 2026">
  **New endpoint for listing Video Agents**

  We have introduced a new endpoint to allow developers to retrieve a list of all existing video agents associated with their account.

  * Added `GET /v3/video-agents`: Use this endpoint to fetch your video agents, enabling easier integration and management of your agent instances.
</Update>

<Update label="Avatar Error Code Update" description="Changed - April 2026">
  **Updated error codes for Avatar endpoints**

  We have updated the error response codes for avatar-related endpoints to provide more specific feedback when a group cannot be located.

  * `GET /v3/avatars/{group_id}`: The 404 response error code has been updated from `not_found` to `avatar_group_not_found`.
  * `POST /v3/avatars/{group_id}/consent`: The 404 response error code has been updated from `not_found` to `avatar_group_not_found`.
</Update>

<Update label="Enhanced Video Generation Controls" description="Added - April 2026">
  **Advanced voice customization and output formatting**

  We have introduced new parameters to provide finer control over generated audio and video output quality.

  * Added `volume` and `engine_settings` to `voice_settings` for `POST /v2/videos` and `POST /v3/videos`. These settings apply when using text-to-speech (`script` + `voice_id`).
  * Added `output_format` to `POST /v3/videos` for both `CreateVideoFromAvatar` and `CreateVideoFromImage` request schemas.
</Update>

<Update label="Webhook API Updates" description="Added - April 2026">
  **Improved error handling for webhook management**

  We have updated our webhook endpoints to provide more consistent and descriptive error responses.

  * Added a `409` conflict response to `POST /v3/webhooks/endpoints` to better handle registration errors.
  * Standardized error codes for `404` responses across `DELETE`, `PATCH`, and `POST /v3/webhooks/endpoints/{endpoint_id}/rotate-secret` by updating the error code to `webhook_not_found`.
</Update>

<Update label="New Output Format Support" description="Added - April 2026">
  **Support for custom output formats in video generation**

  You can now specify a preferred output format when creating videos. The API response now includes the `output_format` field to confirm the format used for your generated video.

  * Added optional `output_format` request property to `POST /v2/videos`.
  * Added `output_format` to the response body of `POST /v2/videos` (200 OK).
  * Added `output_format` to the response body of `POST /v3/videos` (200 OK).
</Update>

<Update label="API Documentation Overhaul" description="Changed - April 2026">
  **Comprehensive API Documentation Updates**

  We have updated the endpoint descriptions across our entire V3 API to provide clearer guidance, better parameter context, and more precise functionality definitions. While the underlying API logic remains consistent, the improved documentation clarifies how to integrate with our latest engine versions and features.

  * **Video Generation**: `POST /v3/videos` now officially documents support for the Avatar IV engine and upcoming Avatar V.
  * **Avatars**: Clarified workflows for `POST /v3/avatars` (asynchronous training) and added guidance on the mandatory consent flow for private avatars via `POST /v3/avatars/{group_id}/consent`.
  * **Video Agent**: Streamlined descriptions for session-based interactions, clearly distinguishing between `generate` (one-shot) and `chat` (multi-turn) modes.
  * **Lipsync & Translation**: Updated documentation for `POST /v3/lipsyncs` and `POST /v3/video-translations` to emphasize the `speed` vs. `precision` mode selection for output quality.
  * **Webhooks**: Clarified that `PATCH /v3/webhooks/endpoints/{endpoint_id}` performs a full replacement of the event types array.
  * **Assets**: Updated supported MIME types for `POST /v3/assets` to include refined file type lists.
</Update>

<Update label="Caption URL Support" description="Added - April 2026">
  **Added caption\_url to Lipsync and Video Translation responses**

  You can now retrieve the `caption_url` for generated lipsyncs and video translations, providing direct access to the generated caption files.

  * `GET /v3/lipsyncs` and `GET /v3/lipsyncs/{lipsync_id}`
  * `PATCH /v3/lipsyncs/{lipsync_id}`
  * `GET /v3/video-translations` and `GET /v3/video-translations/{video_translation_id}`
  * `PATCH /v3/video-translations/{video_translation_id}`
</Update>

<Update label="Consent Flow Clarification" description="Changed - April 2026">
  **Updated documentation for avatar consent**

  Clarified the implementation details for the avatar consent flow to ensure a smoother user experience.

  * `POST /v3/avatars/{group_id}/consent`: Updated documentation to clarify that the returned URL must be presented directly to the user in a browser to complete the consent process.
</Update>

<Update label="Default Avatar Voices" description="Changed - April 2026">
  **Support for avatar-default voices**

  You can now generate videos using an avatar's default voice without explicitly specifying a `voice_id`. When creating a video, if `voice_id` is omitted while `avatar_id` is present, the system will automatically use the avatar's default voice.

  * Updated `POST /v3/videos`: The `voice_id` requirement has been relaxed for both `CreateVideoFromAvatar` and `CreateVideoFromImage` schemas, allowing the system to fall back to the avatar's default voice.
</Update>

<Update label="Video Agent Interaction Updates" description="Changed - April 2026">
  **Enhanced capabilities for Video Agent interactions**

  We have updated the description and scope of the `POST /v3/video-agents/{session_id}` endpoint to better reflect its versatility in managing agent-led workflows.

  * Updated the endpoint description to clarify support for answering agent-posed questions and requesting specific edits or revisions.
  * The request body schema has been updated to better align with these extended conversational and editing capabilities.
</Update>

<Update label="Video Agent Status Update" description="Added - April 2026">
  **New 'thinking' status for Video Agents**

  We have introduced a new `thinking` state to the Video Agent response object to provide better visibility into agent processing workflows.

  * Updated `POST /v3/video-agents`
  * The `status` field in the response now includes the `thinking` enum value.
  * Integration note: Ensure your client-side parsers are prepared to handle this new status value in the response body.
</Update>

<Update label="Video Agent Enhancements" description="Changed - April 2026">
  **Updated Video Agent session retrieval and new video listing**

  We have refactored how resource data is handled in Video Agent sessions to improve performance. Additionally, we have introduced a new endpoint to fetch videos associated with a session.

  * **Breaking Change:** The `resources` property has been removed from the response body of `GET /v3/video-agents/{session_id}`.
  * **Migration:** To access resource details previously found in the session object, please use the new `GET /v3/video-agents/{session_id}/resources/{resource_id}` endpoint.
  * **New Endpoint:** Added `GET /v3/video-agents/{session_id}/videos` to retrieve a list of videos generated within a specific agent session.
</Update>

<Update label="Video Agent Session Refactor" description="Changed - April 2026">
  **Breaking change: Restructured Video Agent session management**

  We have updated the Video Agent API to simplify session handling. Please note that the previous `/v3/video-agents/sessions` path structure is deprecated and removed.

  * **Removed endpoints:** `POST /v3/video-agents/sessions`, `GET /v3/video-agents/sessions/{session_id}`, `POST /v3/video-agents/sessions/{session_id}/messages`, `GET /v3/video-agents/sessions/{session_id}/resources`, and `POST /v3/video-agents/sessions/{session_id}/stop` have been removed.
  * **Migration:** Replace existing calls with the new flattened endpoints under `/v3/video-agents/{session_id}`.
  * **New endpoints added:**
    * `GET /v3/video-agents/{session_id}`
    * `POST /v3/video-agents/{session_id}`
    * `GET /v3/video-agents/{session_id}/resources/{resource_id}`
    * `POST /v3/video-agents/{session_id}/stop`
</Update>

<Update label="Video Agent Enhancements" description="Added - April 2026">
  **New configuration options for Video Agent sessions**

  The `POST /v3/video-agents` endpoint now supports advanced control over session flow.

  * Added `mode`: Supports `generate` (default, one-shot) and `chat` (multi-turn, allows revisions and follow-ups).
  * Added `auto_proceed`: Enables automated progression through storyboards.
  * Added `skip_agentic_stop`: Provides granular control over agent stopping behavior.
</Update>

<Update label="Platform Updates" description="Changed - April 2026">
  **API Operation ID update**

  The operation ID for `GET /v3/users/me` has been updated from `getUserMeV3` to `getCurrentUserV3` to maintain consistency across our SDKs.
</Update>

<Update label="New Voice Creation Endpoint" description="Added - April 2026">
  **Added support for custom voice creation**

  We have introduced a new endpoint to allow developers to programmatically create and add new voices to their HeyGen account.

  * Added `POST /v3/voices` to the API.
</Update>

<Update label="New Video Creation Schema" description="Changed - April 2026">
  **Refactored POST /v3/videos request body**

  We have updated the `POST /v3/videos` endpoint to use a discriminated union for improved type safety and flexibility. This change replaces the legacy flat request structure with dedicated schemas for creating videos from avatars versus images.

  * **Breaking Change:** The request body structure has been completely overhauled. You must now specify a type discriminator: use `CreateVideoFromAvatar` for digital twins/avatars or `CreateVideoFromImage` for custom image animation.
  * **Migration:** All properties previously passed at the top level of the request (e.g., `avatar_id`, `image_url`, `voice_id`, `script`) must now be nested within the appropriate schema based on the video source.
  * The operation ID for this endpoint has been updated from `createAvatarVideoV3` to `createVideo`.
</Update>

<Update label="Improved API Error Handling" description="Changed - April 2026">
  **Enhanced error messaging across all endpoints**

  We have updated the error response schemas and examples across the entire API suite. Developers can now expect more consistent and detailed error responses for common issues, including:

  * Improved `400 Bad Request` messages with clearer parameter validation feedback.
  * Standardized `401 Unauthorized` responses when API keys are missing or expired.
  * Consistent `429 Rate Limited` responses that align with standard retry headers.
  * Better descriptive error messages for resource-specific failures (e.g., `404 Not Found` for specific IDs).

  These updates ensure that your integrations can better handle exceptions and debugging.
</Update>

<Update label="New v3 API endpoints" description="Added - April 2026">
  **HeyGen for Developers — New v3 API Surface**

  We've launched a new set of v3 endpoints across the HeyGen API, bringing a consistent interface, cursor-based pagination, and a unified asset input model to all major resources.

  What's new:

  * All v3 endpoints share a standard error format, cursor-based pagination (`has_more` / `next_token`), and consistent authentication via `X-Api-Key` or OAuth bearer token.
  * Asset inputs now use a type-discriminated union — pass files as `{ "type": "url", "url": "..." }`, `{ "type": "asset_id", "asset_id": "..." }`, or `{ "type": "base64", "media_type": "...", "data": "..." }` across all endpoints.
  * New and updated endpoints include: Video Agent (`POST /v3/video-agents`), Videos (`POST /v3/videos`), Voices (`GET /v3/voices`, `POST /v3/voices/speech`), Video Translations (`POST /v3/video-translations`), Overdub (`POST /v3/overdubs`), Avatars (`POST /v3/avatars`), Assets (`POST /v3/assets`), Webhooks (`/v3/webhooks/*`), and User (`GET /v3/users/me`).

  The v1/v2 endpoints continue to work, but we recommend migrating to v3 for all new integrations.
</Update>


# Cinematic Avatar
Source: https://heygen-1fa696a7.mintlify.app/cinematic-avatar

Generate cinematic avatar video from a single prompt with the HeyGen API. Combine up to three avatar looks with reference videos and images — no script or voice required.

<img alt="" />

Cinematic Avatar is a prompt-driven variant of [`POST /v3/videos`](/reference/create-video). Instead of a script and a voice, you describe the shot you want in natural language and hand HeyGen up to three avatar looks (plus optional reference media). The Seedance pipeline composes the scene, motion, and framing for you.

## Prerequisites

<Check>
  One to three avatar look IDs. Use `GET /v3/avatars/looks` to browse your looks and copy the `id` field for each one you want in the shot.
</Check>

<Check>
  A prompt describing the scene, action, and framing. This replaces the `script` + `voice_id` you'd use for a [Digital Twin video](/generate-avatar-video).
</Check>

## Step 1 — Write your prompt

The `prompt` (1–10,000 characters) is the creative brief for the shot. Describe what the avatar is doing, the setting, the camera, and the mood — e.g. *"A founder walks through a sunlit startup office, gesturing toward a whiteboard, shot handheld in a documentary style."* See [Writing Effective Video Prompts](/writing-effective-video-prompts) for guidance.

## Step 2 — Pick your avatar looks

Pass `avatar_id` as an **array** of 1–3 look IDs. Multiple looks let HeyGen feature more than one avatar in the same shot:

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/avatars/looks?ownership=private" \
  -H "x-api-key: YOUR_API_KEY"
```

Copy the `id` of each look you want into the array.

## Step 3 — Create the video

Send a `POST` to `/v3/videos` with `type: "cinematic_avatar"`:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cinematic_avatar",
    "prompt": "A founder walks through a sunlit startup office, gesturing toward a whiteboard, shot handheld in a documentary style.",
    "avatar_id": ["YOUR_LOOK_ID"],
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration": 10,
    "title": "Founder office walkthrough"
  }'
```

The response is the same shape as any other `/v3/videos` job:

```json theme={null}
{
  "data": {
    "video_id": "abc123",
    "status": "pending",
    "output_format": "mp4"
  }
}
```

### Adding reference media

Use `references` to steer style, motion, or composition with your own videos and images. Each reference is a `url`, `asset_id`, or `base64` asset input:

```json theme={null}
{
  "type": "cinematic_avatar",
  "prompt": "Match the lighting and camera movement of the reference clip.",
  "avatar_id": ["YOUR_LOOK_ID"],
  "references": [
    { "type": "url", "url": "https://your-cdn.com/reference-clip.mp4" },
    { "type": "asset_id", "asset_id": "YOUR_UPLOADED_ASSET_ID" }
  ]
}
```

<Note>
  Avatar looks and references share a combined media budget: **at most 3 videos and 9 images** total across `avatar_id` and `references`. Upload your own files first with [Assets](/assets) to get an `asset_id`.
</Note>

## Step 4 — Poll for completion

Generation is asynchronous. Poll [`GET /v3/videos/{video_id}`](/reference/create-video) until `status` is `completed`:

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/videos/YOUR_VIDEO_ID" \
  -H "x-api-key: YOUR_API_KEY"
```

| Status | Meaning |
| - | - |
| `pending` | Queued for processing |
| `processing` | Video is being generated |
| `completed` | Ready — `video_url` is available |
| `failed` | Something went wrong — check `failure_message` |

## Full example

```python theme={null}
import requests
import time

API_KEY = "YOUR_API_KEY"
BASE = "https://api.heygen.com"
HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}

# 1. Create the Cinematic Avatar video
resp = requests.post(f"{BASE}/v3/videos", headers=HEADERS, json={
    "type": "cinematic_avatar",
    "prompt": "A founder walks through a sunlit startup office, gesturing toward a whiteboard, shot handheld in a documentary style.",
    "avatar_id": ["YOUR_LOOK_ID"],
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration": 10,
})
video_id = resp.json()["data"]["video_id"]
print(f"Video created: {video_id}")

# 2. Poll until done
while True:
    status_resp = requests.get(f"{BASE}/v3/videos/{video_id}", headers=HEADERS)
    data = status_resp.json()["data"]
    print(f"Status: {data['status']}")
    if data["status"] == "completed":
        print(f"Download: {data['video_url']}")
        break
    elif data["status"] == "failed":
        print(f"Error: {data.get('failure_message')}")
        break
    time.sleep(10)
```

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `type` | string | Yes | Must be `"cinematic_avatar"` |
| `prompt` | string | Yes | 1–10,000 characters describing the shot |
| `avatar_id` | array | Yes | 1–3 avatar look IDs |
| `references` | array | No | Up to 3 videos / 9 images (shared with `avatar_id`) as `url`, `asset_id`, or `base64` inputs |
| `aspect_ratio` | string | No | `16:9` (default), `9:16`, or `1:1` |
| `resolution` | string | No | `720p` (default) or `1080p` |
| `duration` | integer | No | 4–15 seconds, default `10`. Omit when `auto_duration` is `true` |
| `auto_duration` | boolean | No | Let HeyGen pick the duration. Default `false` |
| `enhance_prompt` | boolean | No | Auto-expand a short prompt into a richer description. Default `false` |
| `title` | string | No | Display name in the HeyGen dashboard |

## Using webhooks instead of polling

Pass a `callback_url` when creating the video and HeyGen will POST to it when the job finishes — register an endpoint via `POST /v3/webhooks/endpoints` and subscribe to `avatar_video.success` and `avatar_video.fail` as covered in [Webhooks](/docs/webhooks).


# Overview
Source: https://heygen-1fa696a7.mintlify.app/cli

Generate AI avatar videos from your terminal with the HeyGen CLI. Authenticate once, then script video creation, translation, and lipsync into any local.

The HeyGen CLI gives developers and AI agents command-line access to HeyGen's video platform. It wraps the v3 API, outputs structured JSON by default, and works out of the box in scripts, CI pipelines, and agent workflows.

## 1. Install the CLI

```bash theme={null}
curl -fsSL https://static.heygen.ai/cli/install.sh | bash
```

This installs the latest stable release into `~/.local/bin`.

Verify the installation:

```bash theme={null}
heygen --version
```

<Info>
  The CLI ships as a single binary with no runtime prerequisites. macOS (Apple Silicon and Intel) and Linux (x64 and arm64) are supported. Windows support is coming soon — WSL is recommended in the meantime.
</Info>

## 2. Authenticate

Log in with your API key from [API keys page](https://platform.heygen.com/api-keys):

```bash theme={null}
heygen auth login
```

Paste your API key when prompted. The key is stored locally at `~/.heygen/credentials`.

For CI/Docker/agent environments, set the environment variable instead — it takes precedence over stored credentials:

```bash theme={null}
export HEYGEN_API_KEY=your-api-key
```

Verify your credentials:

```bash theme={null}
heygen auth status
```

### Log in with OAuth

As an alternative to an API key, log in with your HeyGen account via OAuth:

```bash theme={null}
heygen auth login --oauth
```

This opens your browser to sign in at HeyGen.com.

<Note>
  Logging in one way replaces the other stored credential. Non-interactive shells (piped input, `CI=true`, or `HEYGEN_NONINTERACTIVE=1`) default to the API-key flow — pass `--oauth` explicitly in automation. Set `BROWSER=none` or `HEYGEN_NO_BROWSER=1` to print the sign-in URL instead of opening a browser.
</Note>

## 3. Create a Video

Send a prompt to the Video Agent and let it handle avatar, voice, and layout:

```bash theme={null}
heygen video-agent create --prompt "A presenter explaining our product launch in 30 seconds"
```

```json Output theme={null}
{
  "data": {
    "session_id": "sess_abc123",
    "status": "generating",
    "video_id": "vid_xyz789",
    "created_at": 1711288320
  }
}
```

The CLI returns immediately with structured JSON. Your video is generating in the background.

For full control over every parameter, use `video create` with a JSON body:

```bash theme={null}
heygen video create -d '{
  "type": "avatar",
  "avatar_id": "avt_angela_01",
  "script": "Welcome to our Q4 earnings call.",
  "voice_id": "1bd001e7e50f421d891986aad5e3e5d2"
}'
```

Use `--request-schema` on any command to discover the expected JSON fields — no auth required:

```bash theme={null}
heygen video create --request-schema
heygen video-agent create --request-schema
```

## 4. Check Status

Poll for the result using the `video_id` returned from step 3:

```bash theme={null}
heygen video get vid_xyz789
```

```json Output theme={null}
{
  "data": {
    "id": "vid_xyz789",
    "title": "Product launch explainer",
    "status": "completed",
    "video_url": "https://files.heygen.com/video/vid_xyz789.mp4",
    "thumbnail_url": "https://files.heygen.com/thumb/vid_xyz789.jpg",
    "duration": 32.5,
    "created_at": 1711288320,
    "completed_at": 1711288452
  }
}
```

Status moves through `pending` → `processing` → `completed` or `failed`. If the video fails, the response includes `failure_code` and `failure_message` fields.

<Info>
  **Tip:** Add `--wait` to the create command to block until the video is ready instead of polling manually. The default timeout is 20 minutes — override with `--timeout 30m`. On timeout, the CLI exits with code `4` and prints the last known resource state along with a hint to resume polling manually.
</Info>

## 5. Download the Video

Once complete, download to a local file:

```bash theme={null}
heygen video download vid_xyz789 --output-path ./launch-video.mp4
```

```json Output theme={null}
{
  "asset": "video",
  "message": "Downloaded video to ./launch-video.mp4",
  "path": "./launch-video.mp4"
}
```

If the video was created with captions enabled, you can download the captioned version:

```bash theme={null}
heygen video download vid_xyz789 --asset captioned --output-path ./launch-captioned.mp4
```


# Commands
Source: https://heygen-1fa696a7.mintlify.app/commands

Reference every HeyGen CLI command with flags, examples, and expected output. Covers video, avatar, voice, translate, lipsync, and config commands in one place.

All commands follow the pattern `heygen <noun> <verb>`. The command surface is auto-generated from HeyGen's OpenAPI specification — when new v3 endpoints ship, the CLI picks them up automatically.

Run `heygen <command> --help` for detailed usage and examples on any command. Use `--request-schema` or `--response-schema` on any command to see the full JSON schema for its request or response — no auth required.

## Ai Clipping

Turn long-form videos into ready-to-share short clips with captions

| Command | API Endpoint | Description |
| - | - | - |
| `heygen ai-clipping create` | `POST /v3/ai-clipping` | Create AI Clipping |
| `heygen ai-clipping delete <job-id>` | `DELETE /v3/ai-clipping/{job_id}` | Delete AI Clipping |
| `heygen ai-clipping get <job-id>` | `GET /v3/ai-clipping/{job_id}` | Get AI Clipping |
| `heygen ai-clipping list` | `GET /v3/ai-clipping` | List AI Clipping |

### Flags for `ai-clipping create`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
| `--callback-id <value>` | Opaque client identifier echoed verbatim in webhook payloads. Mirrors /v3/video-translations callback\_id. |
| `--callback-url <value>` | HTTPS URL to receive per-job webhook callbacks. Mirrors /v3/video-translations callback\_url. Per-job callback\_url deliveries are NOT HMAC-signed: authenticate them by verifying TLS and matching the echoed callback\_id, and do not trust an unverified body. To receive a signed payload, register a webhook endpoint with a secret (the signature header is sent only to registered endpoints). |
| `--input-language <value>` | ISO-639-1 source language code (e.g. 'en', 'es'). Omit for auto-detect. |
| `--title <value>` | Title for the job. Defaults to the source video's title if omitted. |

### Flags for `ai-clipping list`

| Flag | Description |
| - | - |
| `--limit <n>` | Maximum number of items per page. Defaults to 10 (lower than other v3 lists) because each item embeds its full clips array. |
| `--token <value>` | Opaque cursor token for the next page. |

## Asset

Upload files for use in video creation

| Command | API Endpoint | Description |
| - | - | - |
| `heygen asset batches get <batch-id>` | `GET /v3/assets/batches/{batch_id}` | Get Asset Batch |
| `heygen asset complete batches create` | `POST /v3/assets/complete/batches` | Complete Asset Upload Batch |
| `heygen asset complete create <asset-id>` | `POST /v3/assets/{asset_id}/complete` | Complete Asset Upload |
| `heygen asset create` | `POST /v3/assets` | Upload Asset |
| `heygen asset delete <asset-id>` | `DELETE /v3/assets/{asset_id}` | Delete Asset |
| `heygen asset direct-uploads batches create` | `POST /v3/assets/direct-uploads/batches` | Create Asset Upload Batch |
| `heygen asset direct-uploads create` | `POST /v3/assets/direct-uploads` | Create Asset Upload |
| `heygen asset get <asset-id>` | `GET /v3/assets/{asset_id}` | Get Asset |
| `heygen asset list` | `GET /v3/assets` | List Assets |
| `heygen asset statuses list` | `GET /v3/assets/statuses` | Bulk Asset Statuses |

### Flags for `asset batches get`

| Flag | Description |
| - | - |
| `--limit <n>` | Items per page (1-100). |
| `--token <value>` | Opaque pagination cursor from a previous response. |

### Flags for `asset complete batches create`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
| `--batch-id <value>` | Identifier returned by POST /v3/assets/direct-uploads/batches. (required) |

### Flags for `asset complete create`

| Flag | Description |
| - | - |
| `--checksum-sha-256 <value>` | Optional SHA256 (hex) cross-check. |

### Flags for `asset create`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
| `--file <value>` | File to upload (image, video, audio, PDF, or SRT subtitle). Max 32 MB. (required) |

### Flags for `asset direct-uploads batches create`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
| `--callback-url <value>` | Reserved. Asset completion does not emit a webhook. |
| `--title <value>` | Display name for the batch, shown in the HeyGen app. |

### Flags for `asset direct-uploads create`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
| `--checksum-sha-256 <value>` | Optional SHA256 of the file as hex. When provided, S3 enforces it on upload. |
| `--content-type <value>` | Declared MIME type (e.g. 'video/mp4', 'image/png', 'audio/mpeg', 'application/pdf', 'application/zip'). Verified against the stored bytes at completion. (required) |
| `--filename <value>` | Original filename for reference/metadata. The stored object's extension is derived from content\_type. (required) |
| `--size-bytes <n>` | Exact byte size of the file. Signed into the upload URL so it cannot be exceeded. (required) |

### Flags for `asset list`

| Flag | Description |
| - | - |
| `--username <value>` | Username of the workspace member whose assets to list — the same value as asset items' 'owner' field. Required while this endpoint is in beta; it will become an optional filter in a future release. (required) |
| `--limit <n>` | Maximum number of assets to return per page (1-100). |
| `--token <value>` | Opaque cursor from a previous response's next\_token. Omit for the first page. |
| `--folder-id <value>` | Optional folder filter. Omit to list ALL workspace assets across folders. Pass a folder id to list that folder only, or an empty value (folder\_id=) for root-level assets (assets not filed into any folder). |

### Flags for `asset statuses list`

| Flag | Description |
| - | - |
| `--asset-ids <value>` | Comma-separated asset ids to look up. |
| `--batch-ids <value>` | Comma-separated batch ids; each expands to its member assets. |

## Audio

Search the background-music and sound-effects catalog

| Command | API Endpoint | Description |
| - | - | - |
| `heygen audio sounds list` | `GET /v3/audio/sounds` | Search audio (music or sound effects) |

### Flags for `audio sounds list`

| Flag | Description |
| - | - |
| `--query <value>` | Natural-language description of the audio you want, e.g. 'upbeat lofi hip-hop' or 'tense cinematic riser'. Results are ranked by semantic similarity to this text. (required) |
| `--type <value>` | Audio content type to search: 'music' (background-music catalog) or 'sound\_effects' (SFX catalog). Defaults to 'music'. |
| `--limit <n>` | Maximum number of results to return (1-50). |
| `--min-score <n>` | Minimum semantic similarity score (0-1). Tracks scoring below this are omitted. |
| `--token <value>` | Opaque cursor token for the next page, taken from 'next\_token' in a prior response. |

## Avatar

List and manage avatars and looks

| Command | API Endpoint | Description |
| - | - | - |
| `heygen avatar consent create <group-id>` | `POST /v3/avatars/{group_id}/consent` | Create Avatar Consent |
| `heygen avatar create` | `POST /v3/avatars` | Create Avatar |
| `heygen avatar delete <group-id>` | `DELETE /v3/avatars/{group_id}` | Delete Avatar Group |
| `heygen avatar get <group-id>` | `GET /v3/avatars/{group_id}` | Get Avatar Group |
| `heygen avatar list` | `GET /v3/avatars` | List Avatar Groups |
| `heygen avatar look-templates list` | `GET /v3/avatars/look-templates` | List Look Templates |
| `heygen avatar looks create` | `POST /v3/avatars/looks` | Create Avatar Looks |
| `heygen avatar looks delete <look-id>` | `DELETE /v3/avatars/looks/{look_id}` | Delete Avatar Look |
| `heygen avatar looks get <look-id>` | `GET /v3/avatars/looks/{look_id}` | Get Avatar Look |
| `heygen avatar looks list` | `GET /v3/avatars/looks` | List Avatar Looks |
| `heygen avatar looks update <look-id>` | `PATCH /v3/avatars/looks/{look_id}` | Update Avatar Look |
| `heygen avatar update <group-id>` | `PATCH /v3/avatars/{group_id}` | Update Avatar Group |

### Flags for `avatar consent create`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
| `--reroute-url <value>` | Callback URL where the user is redirected after completing consent. Defaults to HeyGen's consent completion page. |

### Flags for `avatar create`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |

### Flags for `avatar list`

| Flag | Description |
| - | - |
| `--ownership <value>` | Filter by ownership: 'public' for preset avatars, or 'private' for your own. Omit for all. |
| `--limit <n>` | Maximum number of items to return per page (1-50). |
| `--token <value>` | Opaque cursor token for the next page. |

### Flags for `avatar look-templates list`

| Flag | Description |
| - | - |
| `--type <value>` | Filter by generation method: 'look\_pack' for Look Packs, 'template' for single look templates. Omit for both. |
| `--gender <value>` | Filter to templates built for 'male' or 'female'. Templates with no gender of their own are returned for either value. Omit for all. |
| `--limit <n>` | Maximum number of items to return per page (1-50). |
| `--token <value>` | Opaque cursor token for the next page. |

### Flags for `avatar looks create`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |

### Flags for `avatar looks list`

| Flag | Description |
| - | - |
| `--group-id <value>` | Filter looks to a specific avatar group. Returns only looks belonging to this group. |
| `--avatar-type <value>` | Filter by avatar type: 'studio\_avatar', 'digital\_twin', or 'photo\_avatar'. |
| `--ownership <value>` | Filter by ownership: 'public' for preset avatars, or 'private' for your own. Omit for all. |
| `--limit <n>` | Maximum number of items to return per page (1-50). |
| `--token <value>` | Opaque cursor token for the next page. |

### Flags for `avatar looks update`

| Flag | Description |
| - | - |
| `--name <value>` | New display name for the look. |

### Flags for `avatar update`

| Flag | Description |
| - | - |
| `--default-voice-id <value>` | Voice ID to set as the avatar's default voice, replacing the current one. The voice is also linked to the avatar group if it was not already. Accepts any voice available to your workspace, including imported voice clones. Only supported for avatars you own. |

## Background Removal

| Command | API Endpoint | Description |
| - | - | - |
| `heygen background-removal create` | `POST /v3/background-removals` | Create Background Removal |
| `heygen background-removal delete <job-id>` | `DELETE /v3/background-removals/{job_id}` | Delete Background Removal |
| `heygen background-removal get <job-id>` | `GET /v3/background-removals/{job_id}` | Get Background Removal |
| `heygen background-removal list` | `GET /v3/background-removals` | List Background Removals |

### Flags for `background-removal create`

| Flag | Description |
| - | - |
| `--layers <values>` | Output layers to return. Any of: 'foreground' (subject on a transparent background), 'mask' (grayscale alpha matte), 'background' (the scene with the subject removed). Defaults to all three. |
| `--request-id <value>` | Client-provided idempotency key — *the* idempotency mechanism for this endpoint. Re-sending the same `request_id` returns the *original* job (same `id`, same `status`, same charge) instead of creating a new one — the dedup is over (`space_id`, `request_id`), not over the response body, so a duplicate `request_id` with different content still collides on the original job. The HTTP `Idempotency-Key` header is *not* honored here; pick a per-content `request_id` if you need per-content dedup. |
| `--title <value>` | Optional human-readable title for the job. |

### Flags for `background-removal list`

| Flag | Description |
| - | - |
| `--limit <n>` | Maximum number of jobs to return (1-100). |
| `--token <value>` | Opaque pagination cursor from a previous response's next\_token. |

## Brand

Brand-related resources — brand kits (colors, fonts, logos) and brand glossaries (custom term translations)

| Command | API Endpoint | Description |
| - | - | - |
| `heygen brand glossaries create` | `POST /v3/brand-glossaries` | Create Brand Glossary |
| `heygen brand glossaries delete <brand-glossary-id>` | `DELETE /v3/brand-glossaries/{brand_glossary_id}` | Delete Brand Glossary |
| `heygen brand glossaries get <brand-glossary-id>` | `GET /v3/brand-glossaries/{brand_glossary_id}` | Get Brand Glossary |
| `heygen brand glossaries list` | `GET /v3/brand-glossaries` | List Brand Glossaries |
| `heygen brand glossaries update <brand-glossary-id>` | `PATCH /v3/brand-glossaries/{brand_glossary_id}` | Update Brand Glossary |
| `heygen brand kits create` | `POST /v3/brand-kits` | Create Brand Kit |
| `heygen brand kits delete <brand-kit-id>` | `DELETE /v3/brand-kits/{brand_kit_id}` | Delete Brand Kit |
| `heygen brand kits get <brand-kit-id>` | `GET /v3/brand-kits/{brand_kit_id}` | Get Brand Kit |
| `heygen brand kits list` | `GET /v3/brand-kits` | List Brand Kits |
| `heygen brand kits update <brand-kit-id>` | `PATCH /v3/brand-kits/{brand_kit_id}` | Update Brand Kit |

### Flags for `brand glossaries create`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
| `--name <value>` | Display name for the glossary. Surrounding whitespace is removed, and the trimmed name must be 1-64 characters and unique within your workspace, compared without regard to case. (required) |

### Flags for `brand glossaries list`

| Flag | Description |
| - | - |
| `--limit <n>` | Maximum number of brand glossaries to return (1-100). Default 10. |
| `--token <value>` | Opaque pagination cursor from a previous response's `next_token`. Omit for the first page. |

### Flags for `brand glossaries update`

| Flag | Description |
| - | - |
| `--name <value>` | New display name. Surrounding whitespace is removed, and the trimmed name must be 1-64 characters and unique within your workspace, compared without regard to case. Omit to keep the current name. |

### Flags for `brand kits create`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
| `--name <value>` | Name for the brand kit, up to 256 characters. Defaults to the brand name detected on the site, or its domain. |
| `--url <value>` | Public website URL to build the brand kit from. HeyGen visits the site and imports the brand assets it finds there, including logos, colors and font files. By calling this endpoint you confirm you have the rights and licenses necessary to upload, store and use those assets in HeyGen. (required) |

### Flags for `brand kits list`

| Flag | Description |
| - | - |
| `--limit <n>` | Results per page (1-100). |
| `--token <value>` | Opaque cursor token for the next page. Obtained from next\_token in a previous response. |

### Flags for `brand kits update`

| Flag | Description |
| - | - |
| `--name <value>` | New display name for the brand kit, 1-256 characters. Leading and trailing whitespace is trimmed. |

## Filler Word Removal

| Command | API Endpoint | Description |
| - | - | - |
| `heygen filler-word-removal create` | `POST /v3/filler-word-removals` | Create Filler Word Removal |
| `heygen filler-word-removal get <filler-word-removal-id>` | `GET /v3/filler-word-removals/{filler_word_removal_id}` | Get Filler Word Removal |

### Flags for `filler-word-removal create`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
| `--callback-id <value>` | Opaque client identifier echoed verbatim in webhook payloads. |
| `--callback-url <value>` | HTTPS URL to receive per-job webhook callbacks (filler\_word\_removal.success / filler\_word\_removal.fail). Delivery is best-effort with limited retries — poll GET /v3/filler-word-removals/\{id} as the source of truth (a terminal GET may precede its webhook). Per-job callback\_url deliveries are NOT HMAC-signed: authenticate them by verifying TLS and matching the echoed callback\_id, and do not trust an unverified body. To receive a signed payload, register a webhook endpoint with a secret via /v3/webhooks/endpoints. |
| `--title <value>` | Display title for the job. Defaults to 'Filler Removal' if omitted. |

## Folder

Create folders to organize videos and translations in the workspace, and look up any folder, Assets library folders included, by id

| Command | API Endpoint | Description |
| - | - | - |
| `heygen folder create` | `POST /v3/folders` | Create Folder |
| `heygen folder get <folder-id>` | `GET /v3/folders/{folder_id}` | Get Folder |

### Flags for `folder create`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
| `--name <value>` | Folder name, 1-256 characters. Sibling folders may share a name. (required) |
| `--parent-id <value>` | ID of the folder to create this one in. Omit, pass null, or pass an empty string to create it at the workspace root. The parent must be a folder in the caller's workspace, of a kind this endpoint creates, that is not in the trash. Assets library folders are flat and cannot hold folders. |
| `--type <value>` | Kind of folder. 'mixed' is what the HeyGen web app's New folder action creates; 'video\_translate' is what the Video Translate page creates. Folders the Assets library creates have kind 'asset'; they cannot be created or nested under here. Every kind is accepted as a folder\_id destination on POST /v3/videos, POST /v3/video-translations and the other routes that take one, but the HeyGen app files only assets in an 'asset' folder, so a render placed in one may not appear in the Assets library view. |

## Lipsync

Dub or replace audio on existing videos

| Command | API Endpoint | Description |
| - | - | - |
| `heygen lipsync batches create` | `POST /v3/lipsyncs/batches` | Create Lipsync Batch |
| `heygen lipsync batches get <batch-id>` | `GET /v3/lipsyncs/batches/{batch_id}` | Get Lipsync Batch |
| `heygen lipsync create` | `POST /v3/lipsyncs` | Create Lipsync |
| `heygen lipsync delete <lipsync-id>` | `DELETE /v3/lipsyncs/{lipsync_id}` | Delete Lipsync |
| `heygen lipsync get <lipsync-id>` | `GET /v3/lipsyncs/{lipsync_id}` | Get Lipsync |
| `heygen lipsync list` | `GET /v3/lipsyncs` | List Lipsyncs |
| `heygen lipsync statuses list` | `GET /v3/lipsyncs/statuses` | Bulk Lipsync Statuses |
| `heygen lipsync update <lipsync-id>` | `PATCH /v3/lipsyncs/{lipsync_id}` | Update Lipsync |

### Flags for `lipsync batches create`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
| `--callback-url <value>` | Webhook URL invoked once when every item in the batch reaches a terminal state. |
| `--title <value>` | Display name for the batch, shown in the HeyGen app. |

### Flags for `lipsync batches get`

| Flag | Description |
| - | - |
| `--limit <n>` | Items per page (1-100). |
| `--token <value>` | Opaque pagination cursor from a previous response. |

### Flags for `lipsync create`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
| `--callback-id <value>` | ID included in webhook payload |
| `--callback-url <value>` | Webhook URL for completion notifications |
| `--disable-music-track` | Remove background music |
| `--enable-caption` | Deprecated and ignored: captions are always generated; whether to display them is a download-side choice. |
| `--enable-dynamic-duration` | Allow dynamic duration adjustment |
| `--enable-speech-enhancement` | Enhance speech quality |
| `--enable-watermark` | Add watermark to output |
| `--end-time <n>` | End time in seconds for partial lipsync |
| `--folder-id <value>` | Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. |
| `--fps-mode <value>` | Frame rate mode: 'vfr', 'cfr', or 'passthrough'. |
| `--keep-the-same-format` | Preserve the source video's encoding specs (resolution, bitrate). |
| `--mode <value>` | Quality mode: 'speed' (faster) or 'precision' (higher quality, uses avatar inference) |
| `--start-time <n>` | Start time in seconds for partial lipsync |
| `--title <value>` | Title for the lipsync job |

### Flags for `lipsync list`

| Flag | Description |
| - | - |
| `--limit <n>` | Maximum number of items per page |
| `--token <value>` | Opaque cursor token for the next page |

### Flags for `lipsync statuses list`

| Flag | Description |
| - | - |
| `--lipsync-ids <value>` | Comma-separated lipsync ids to look up. |
| `--batch-ids <value>` | Comma-separated batch ids; each expands to its member lipsyncs. |

### Flags for `lipsync update`

| Flag | Description |
| - | - |
| `--title <value>` | New title for the lipsync (required) |

## Model

| Command | API Endpoint | Description |
| - | - | - |
| `heygen model audio tts create` | `POST /v3/models/audio/tts` | Generate Speech |
| `heygen model audio voices create` | `POST /v3/models/audio/voices` | Create or Retrain an Audio Voice |
| `heygen model audio voices delete <voice-id>` | `DELETE /v3/models/audio/voices/{voice_id}` | Delete an Audio Voice |
| `heygen model audio voices get <voice-id>` | `GET /v3/models/audio/voices/{voice_id}` | Get an Audio Voice |
| `heygen model audio voices list` | `GET /v3/models/audio/voices` | List Audio Voices |
| `heygen model images create` | `POST /v3/models/images` | Create HeyGen Image |
| `heygen model images get <generation-id>` | `GET /v3/models/images/{generation_id}` | Get HeyGen Image |
| `heygen model videos create` | `POST /v3/models/videos` | Create HeyGen Video |
| `heygen model videos get <video-id>` | `GET /v3/models/videos/{video_id}` | Get HeyGen Video |

### Flags for `model audio tts create`

| Flag | Description |
| - | - |
| `--expressiveness-boost <n>` | Expressiveness boost for instant voices on HeyGen Voice 1.0, from 0.0 to 1.0. Omit for professional voices. |
| `--language <value>` | Language code of `text`. Regional tags normalize to their supported base language, such as `en-US` to `en`. Omit it to detect the language from `text`. A confident reading that matches the letters of `text` is used, and the request fails with `invalid_parameter` if HeyGen Voice does not speak that language. Otherwise the first of these that HeyGen Voice speaks is used: the language the voice was created in, if `text` is written in that language's script; a less certain reading that a second reading of `text` without its numbers and brand names agrees with; the usual language of the script `text` is mostly written in, such as English for Latin letters; and, only when that script has no usual language, the reading itself. If none of them applies, the request fails with `invalid_parameter`. The `Content-Language` response header names the language used. |
| `--model <value>` | heygen-voice-1: instant and professional voices. heygen-voice-1-turbo: heygen-voice-1 instant voices only, at lower latency. |
| `--pitch-shift <n>` | Pitch shift in semitones for professional clones. Ignored for instant clones. |
| `--pitch-variance <n>` | Pitch variation multiplier for professional clones; 1.0 preserves the voice default. Ignored for instant clones. |
| `--seed <n>` | Optional best-effort deterministic generation seed for professional clones. Ignored for instant clones. |
| `--speed <n>` | Speech speed multiplier for professional clones. Ignored for instant clones, including Turbo. |
| `--text <value>` | Plain text to synthesize. A professional voice clone takes \<break time="Xs"/> pauses (seconds, up to 5 per pause, e.g. \<break time="0.5s"/>); other SSML, and break tags for an instant voice clone, are not supported. (required) |
| `--voice-id <value>` | Identifier of the voice used for speech synthesis. (required) |
| `--with-timestamps` | Whether to include `original_characters` in the response: the start and end time of each character of `text`. |

### Flags for `model audio voices create`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |

### Flags for `model audio voices list`

| Flag | Description |
| - | - |
| `--type <value>` | `private` lists the voices your workspace created. `public` lists the voices HeyGen provides to every workspace. |
| `--limit <n>` | Maximum number of voices to return per page. |
| `--token <value>` | Opaque pagination token returned by a previous request. |

### Flags for `model images create`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
| `--aspect-ratio <value>` | Output aspect ratio. Omit to match the reference image after EXIF orientation. Explicit presets are exact; inferred ratios round to the nearest pixel. Output resolution follows the model's canvas policy; read width and height from each result. |
| `--mode <value>` | Generation operation. Only identity\_remix is supported. Defaults to identity\_remix when omitted. |
| `--model <value>` | Required identity-focused image model. Only heygen-image-1 is supported. (required) |
| `--num-images <n>` | Number of images to generate in this job. Supports one to five. |
| `--seed <n>` | Seed for the first image. Each subsequent image increments the seed by one. A random seed is chosen when omitted. |

### Flags for `model videos create`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |

## Template

Generate videos from reusable templates by replacing their variables

| Command | API Endpoint | Description |
| - | - | - |
| `heygen template create` | `POST /v3/templates` | Create Template from Video |
| `heygen template delete <template-id>` | `DELETE /v3/templates/{template_id}` | Delete Template |
| `heygen template generate <template-id>` | `POST /v3/templates/{template_id}` | Generate Video from Template |
| `heygen template get <template-id>` | `GET /v3/templates/{template_id}` | Get Template |
| `heygen template list` | `GET /v3/templates` | List Templates |
| `heygen template update <template-id>` | `PATCH /v3/templates/{template_id}` | Update Template |
| `heygen template variables update <template-id>` | `PUT /v3/templates/{template_id}/variables` | Set Template Variables |

### Flags for `template create`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
| `--name <value>` | Template name. Defaults to the source video's title. |
| `--video-id <value>` | ID of a video in your workspace to turn into a template. The video must have been generated with POST /v3/videos or saved in the HeyGen editor; its draft becomes the template's starting point. (required) |

### Flags for `template generate`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
| `--brand-glossary-id <value>` | Brand glossary controlling how custom terms are pronounced in generated speech. Discover IDs via GET /v3/brand-glossaries. |
| `--brand-voice-id <value>` | Legacy field name for `brand_glossary_id`. Both are accepted and resolve to the same workspace record. Prefer `brand_glossary_id`. |
| `--callback-id <value>` | Opaque ID echoed back in webhook events for this video |
| `--callback-url <value>` | URL called with the video result in addition to registered webhook endpoints |
| `--caption` | Whether to burn captions into the video |
| `--enable-sharing` | Whether the generated video's share page is publicly accessible |
| `--folder-id <value>` | Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. Supported only for single-video creation; batch video items cannot set their own destination folder. |
| `--fps <n>` | Output frame rate. One of 25, 30, or 60. |
| `--include-gif` | Whether to include a GIF preview in the webhook payload |
| `--keep-text-vertically-centered` | When true, replaced text elements are vertically re-centered based on their rendered height |
| `--reorder-music` | When true (default), background audio tracks move with their scenes. When false, tracks stay pinned to layout positions. |
| `--scene-ids <values>` | Scene IDs to render, in order (repeats allowed). Scenes must already exist in the template; the API can select, reorder, and repeat scenes but cannot create new ones. Omit to render all scenes in template order. |
| `--title <value>` | Title for the generated video |

### Flags for `template list`

| Flag | Description |
| - | - |
| `--limit <n>` | Maximum number of templates to return per page |
| `--token <value>` | Opaque pagination token from a previous response's next\_token |

### Flags for `template update`

| Flag | Description |
| - | - |
| `--name <value>` | New template name (required) |

### Flags for `template variables update`

| Flag | Description |
| - | - |
| `--expected-edit-version <value>` | The template's edit\_version from your last GET. When given, the update is rejected with 409 stale\_edit\_version if the template changed since. Omit to overwrite unconditionally. |

## User

Account information and billing

| Command | API Endpoint | Description |
| - | - | - |
| `heygen user me get` | `GET /v3/users/me` | Get Current User |

## Video

Create, list, retrieve, and delete videos

| Command | API Endpoint | Description |
| - | - | - |
| `heygen video batches create` | `POST /v3/videos/batches` | Create Video Batch |
| `heygen video batches get <batch-id>` | `GET /v3/videos/batches/{batch_id}` | Get Video Batch |
| `heygen video create` | `POST /v3/videos` | Create Video |
| `heygen video delete <video-id>` | `DELETE /v3/videos/{video_id}` | Delete Video |
| `heygen video get <video-id>` | `GET /v3/videos/{video_id}` | Get Video |
| `heygen video list` | `GET /v3/videos` | List Videos |
| `heygen video scenes get <video-id>` | `GET /v3/videos/{video_id}/scenes` | Get Video Scenes |
| `heygen video statuses list` | `GET /v3/videos/statuses` | Bulk Video Statuses |

### Flags for `video batches create`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
| `--callback-url <value>` | Webhook URL invoked once when every item in the batch reaches a terminal state. |
| `--folder-id <value>` | Destination folder ID for the batch container. The videos remain grouped inside the newly created batch; the batch itself is placed in this folder. Omit, pass null, or pass an empty string to place the batch at the workspace root. |
| `--title <value>` | Display name for the batch, shown in the HeyGen app. |

### Flags for `video batches get`

| Flag | Description |
| - | - |
| `--limit <n>` | Items per page (1-100). |
| `--token <value>` | Opaque pagination cursor from a previous response. |

### Flags for `video create`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |

### Flags for `video list`

| Flag | Description |
| - | - |
| `--limit <n>` | Maximum number of items to return per page |
| `--token <value>` | Opaque pagination cursor from a previous response |
| `--folder-id <value>` | Filter videos by folder ID |
| `--title <value>` | Filter videos by title substring |

### Flags for `video statuses list`

| Flag | Description |
| - | - |
| `--video-ids <value>` | Comma-separated video ids to look up. |
| `--batch-ids <value>` | Comma-separated batch ids; each expands to its member videos. |

## Video Agent

Create videos from text prompts using AI

| Command | API Endpoint | Description |
| - | - | - |
| `heygen video-agent create` | `POST /v3/video-agents` | Create Video Agent Session |
| `heygen video-agent get <session-id>` | `GET /v3/video-agents/{session_id}` | Get Video Agent Session |
| `heygen video-agent list` | `GET /v3/video-agents` | List Video Agent Sessions |
| `heygen video-agent resources get <session-id> <resource-id>` | `GET /v3/video-agents/{session_id}/resources/{resource_id}` | Get Session Resource |
| `heygen video-agent send <session-id>` | `POST /v3/video-agents/{session_id}` | Send Video Agent Message |
| `heygen video-agent stop <session-id>` | `POST /v3/video-agents/{session_id}/stop` | Stop Video Agent Session |
| `heygen video-agent styles list` | `GET /v3/video-agents/styles` | List Video Agent Styles |
| `heygen video-agent videos list <session-id>` | `GET /v3/video-agents/{session_id}/videos` | List Session Videos |

### Flags for `video-agent create`

| Flag | Description |
| - | - |
| `--avatar-id <value>` | Specific avatar ID to use |
| `--brand-glossary-id <value>` | Brand glossary ID controlling how custom terms are pronounced in the generated video's narration (for example, saying 'HeyGen' as 'hey-jen'). Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries. |
| `--brand-kit-id <value>` | Brand kit ID to apply brand colors, fonts, and logos to the generated video. In enterprise workspaces with a locked brand policy, only the workspace default brand kit is accepted; omit this field to apply the workspace default automatically. |
| `--callback-id <value>` | Optional callback ID included in webhook payload |
| `--callback-url <value>` | Webhook URL for completion/failure notifications |
| `--incognito-mode` | When enabled, disables memory injection and extraction for this session |
| `--members <values>` | Email addresses to grant access to. Valid only with `visibility: selected`, and every address must belong to a member of the caller's workspace (max 100). May be omitted or empty, leaving the session owner-only until members are added. |
| `--mode <value>` | Session mode. 'generate' produces one video (fire-and-forget). 'chat' enables multi-turn interaction — the agent may pause for decisions and accept follow-up messages. |
| `--orientation <value>` | Video orientation. If not provided, auto-detected from content. |
| `--prompt <value>` | The message/prompt for video generation (1-10000 characters) (required) |
| `--style-id <value>` | Style ID from GET /v3/video-agents/styles. Applies a curated visual template to the generated video. |
| `--visibility <value>` | Who can open the session. `private`: the owner only. `space`: everyone in the workspace can open and drive the session. `selected`: the owner plus the workspace members listed in `members`. Defaults to `space`. Applies to the session and its conversation; does not change existing sessions. |
| `--voice-id <value>` | Specific voice ID to use for narration |

### Flags for `video-agent list`

| Flag | Description |
| - | - |
| `--limit <n>` | Results per page (1-100). |
| `--token <value>` | Opaque cursor token for the next page. Obtained from next\_token in a previous response. |

### Flags for `video-agent send`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
| `--avatar-id <value>` | Override avatar for this message |
| `--brand-kit-id <value>` | Brand kit ID to apply for this message. In enterprise workspaces with a locked brand policy, only the workspace default brand kit is accepted. |
| `--message <value>` | Text message to the agent. Required when edit\_plan is omitted; may be omitted or empty when edit\_plan is provided. |
| `--voice-id <value>` | Override voice for this message |

### Flags for `video-agent stop`

This command takes a structured request body. Pass it with `-d` and run the command with `--request-schema` to see all fields.

### Flags for `video-agent styles list`

| Flag | Description |
| - | - |
| `--tag <value>` | Filter by tag (e.g., 'cinematic', 'retro-tech', 'iconic-artist', 'pop-culture', 'handmade', 'print'). |
| `--limit <n>` | Results per page (1-100). |
| `--token <value>` | Opaque cursor token for the next page. Obtained from next\_token in a previous response. |

## Video Translate

Translate videos into other languages

| Command | API Endpoint | Description |
| - | - | - |
| `heygen video-translate batches create` | `POST /v3/video-translations/batches` | Create Video Translation Batch |
| `heygen video-translate batches get <batch-id>` | `GET /v3/video-translations/batches/{batch_id}` | Get Video Translation Batch |
| `heygen video-translate create` | `POST /v3/video-translations` | Create Video Translation |
| `heygen video-translate delete <video-translation-id>` | `DELETE /v3/video-translations/{video_translation_id}` | Delete Video Translation |
| `heygen video-translate get <video-translation-id>` | `GET /v3/video-translations/{video_translation_id}` | Get Video Translation |
| `heygen video-translate languages list` | `GET /v3/video-translations/languages` | List Supported Translation Languages |
| `heygen video-translate list` | `GET /v3/video-translations` | List Video Translations |
| `heygen video-translate proofreads create` | `POST /v3/video-translations/proofreads` | Create Proofread Session |
| `heygen video-translate proofreads delete <proofread-id>` | `DELETE /v3/video-translations/proofreads/{proofread_id}` | Delete Proofread Session |
| `heygen video-translate proofreads generate <proofread-id>` | `POST /v3/video-translations/proofreads/{proofread_id}/generate` | Generate Video from Proofread |
| `heygen video-translate proofreads get <proofread-id>` | `GET /v3/video-translations/proofreads/{proofread_id}` | Get Proofread Session |
| `heygen video-translate proofreads list` | `GET /v3/video-translations/proofreads` | List Proofread Sessions |
| `heygen video-translate proofreads srt get <proofread-id>` | `GET /v3/video-translations/proofreads/{proofread_id}/srt` | Download Proofread SRT |
| `heygen video-translate proofreads srt update <proofread-id>` | `PUT /v3/video-translations/proofreads/{proofread_id}/srt` | Upload Proofread SRT |
| `heygen video-translate statuses list` | `GET /v3/video-translations/statuses` | Bulk Video Translation Statuses |
| `heygen video-translate update <video-translation-id>` | `PATCH /v3/video-translations/{video_translation_id}` | Update Video Translation |

### Flags for `video-translate batches create`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
| `--callback-url <value>` | Webhook URL invoked once when every item in the batch reaches a terminal state. |
| `--title <value>` | Display name for the batch, shown in the HeyGen app. |

### Flags for `video-translate batches get`

| Flag | Description |
| - | - |
| `--limit <n>` | Items per page (1-100). |
| `--token <value>` | Opaque pagination cursor from a previous response. |

### Flags for `video-translate create`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
| `--brand-glossary-id <value>` | Brand glossary ID for custom term translations (e.g. translate 'Reformer' as the Pilates equipment, not 'political activist'). Alias for the legacy `brand_voice_id` field. Discover IDs via GET /v3/brand-glossaries. |
| `--brand-voice-id <value>` | Brand glossary ID for custom term translations. Legacy field name for `brand_glossary_id` — both are accepted and resolve to the same workspace record. Discover IDs via GET /v3/brand-glossaries. |
| `--callback-id <value>` | ID included in webhook payload |
| `--callback-url <value>` | Webhook URL for completion notifications |
| `--disable-music-track` | Remove background music |
| `--enable-caption` | Deprecated and ignored: captions are always generated; whether to display them is a download-side choice. |
| `--enable-dynamic-duration` | Allow dynamic duration adjustment |
| `--enable-speech-enhancement` | Enhance speech quality |
| `--enable-watermark` | Add watermark to output |
| `--end-time <n>` | End time in seconds for partial translation |
| `--folder-id <value>` | Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. |
| `--fps-mode <value>` | Frame rate mode for the output video. 'vfr' = variable frame rate, 'cfr' = constant frame rate, 'passthrough' = match the source. Only takes effect when a custom 'audio' track is provided. |
| `--input-language <value>` | Source language code (auto-detected if omitted) |
| `--keep-the-same-format` | Preserve the source video's encoding specs (resolution, bitrate). |
| `--mode <value>` | Translation quality mode: 'speed' (faster) or 'precision' (higher quality, uses avatar inference) |
| `--output-languages <values>` | Target language names (e.g. 'Chinese (Cantonese, Traditional)', 'Spanish (Spain)', 'English'). Use GET /v3/video-translations/languages for valid values. Use one for single translation, multiple for batch. (required) |
| `--speaker-num <n>` | Number of speakers (improves speaker separation) |
| `--srt-role <value>` | Which video the subtitle applies to: 'input' (source) or 'output' (translated). |
| `--start-time <n>` | Start time in seconds for partial translation |
| `--title <value>` | Title for the translation job |
| `--translate-audio-only` | Only translate audio, keep original video |

### Flags for `video-translate list`

| Flag | Description |
| - | - |
| `--limit <n>` | Maximum number of items per page |
| `--token <value>` | Opaque cursor token for the next page |

### Flags for `video-translate proofreads create`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
| `--brand-glossary-id <value>` | Brand glossary ID for custom term translations (e.g. translate 'Reformer' as 'Pilates equipment', not 'political activist'). Alias for the legacy `brand_voice_id` field. Discover IDs via GET /v3/brand-glossaries. |
| `--brand-voice-id <value>` | Brand glossary ID for custom term translations. Legacy field name for `brand_glossary_id` — both are accepted and resolve to the same workspace record. Discover IDs via GET /v3/brand-glossaries. |
| `--disable-music-track` | Remove background music |
| `--enable-speech-enhancement` | Enhance speech quality |
| `--enable-video-stretching` | Allow dynamic duration adjustment |
| `--folder-id <value>` | Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. |
| `--keep-the-same-format` | Preserve the source video's encoding specs (resolution, bitrate) |
| `--mode <value>` | Translation quality mode: 'speed' (faster) or 'precision' (higher quality) |
| `--output-languages <values>` | Target language codes. Use one for single proofread, multiple for batch. (required) |
| `--speaker-num <n>` | Number of speakers (improves speaker separation) |
| `--title <value>` | Title for the proofread job (required) |

### Flags for `video-translate proofreads generate`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
| `--callback-id <value>` | ID included in webhook payload |
| `--callback-url <value>` | Webhook URL for completion notifications |
| `--captions` | Deprecated and ignored: captions are always generated; whether to display them is a download-side choice. |
| `--translate-audio-only` | Only translate audio, keep original video |

### Flags for `video-translate proofreads list`

| Flag | Description |
| - | - |
| `--limit <n>` | Maximum number of items per page |
| `--token <value>` | Opaque cursor token for the next page |

### Flags for `video-translate proofreads srt update`

This command takes a structured request body. Pass it with `-d` and run the command with `--request-schema` to see all fields.

### Flags for `video-translate statuses list`

| Flag | Description |
| - | - |
| `--video-translation-ids <value>` | Comma-separated video translation ids to look up. |
| `--batch-ids <value>` | Comma-separated batch ids; each expands to its member video translations. |

### Flags for `video-translate update`

| Flag | Description |
| - | - |
| `--title <value>` | New title for the video translation (required) |

## Voice

Create speech audio and manage voices

| Command | API Endpoint | Description |
| - | - | - |
| `heygen voice clone create` | `POST /v3/voices/clone` | Clone a Voice |
| `heygen voice create` | `POST /v3/voices` | Design a Voice |
| `heygen voice delete <voice-id>` | `DELETE /v3/voices/{voice_id}` | Delete a Voice |
| `heygen voice get <voice-id>` | `GET /v3/voices/{voice_id}` | Get Voice |
| `heygen voice list` | `GET /v3/voices` | List Voices |
| `heygen voice speech create` | `POST /v3/voices/speech` | Generate Speech |

### Flags for `voice clone create`

| Flag | Description |
| - | - |
| `--language <value>` | Language hint for the voice (e.g., 'en', 'es'). Auto-detected if omitted. |
| `--remove-background-noise` | Remove background noise from the audio before cloning. |
| `--voice-name <value>` | Display name for the cloned voice. Up to 100 characters; names longer than 64 characters are stored truncated to 64. (required) |

### Flags for `voice create`

| Flag | Description |
| - | - |
| `--gender <value>` | Filter by gender: 'male' or 'female'. |
| `--locale <value>` | BCP-47 locale tag to filter by (e.g., 'en-US', 'pt-BR'). |
| `--prompt <value>` | Natural language description of the desired voice (e.g., 'warm, confident female narrator'). (required) |
| `--seed <n>` | Controls which batch of results to return. seed=0 returns the top matches, seed=1 the next batch, etc. Same prompt + seed always returns the same voices. |

### Flags for `voice list`

| Flag | Description |
| - | - |
| `--type <value>` | Voice type: 'public' for the shared library or 'private' for your cloned voices. |
| `--engine <value>` | Filter by stored engine mapping. Use 'heygen\_voice' for HeyGen Voice; 'orca' remains accepted as its legacy alias. Also accepts 'starfish', 'elevenlabs' or internal engine names. Response engine values retain 'orca' for compatibility. The deprecated elevenlabs\_v3 input alias is also accepted. Available engines may also include engines prepared on first use. |
| `--language <value>` | Filter by language (e.g. 'English'). |
| `--gender <value>` | Filter by gender ('male' or 'female'). |
| `--limit <n>` | Results per page (1-100). |
| `--token <value>` | Opaque cursor token for the next page. |

### Flags for `voice speech create`

| Flag | Description |
| - | - |
| `--engine <value>` | Speech engine override for this request only. Omit to use the voice's saved default, including your saved preference. Voices without a concrete saved default retain Starfish. Unsupported defaults or overrides return an error; engines are never silently substituted. Use 'heygen\_voice' for HeyGen Voice; 'orca' remains accepted as its legacy alias. Responses retain 'orca' for compatibility. ElevenLabs model variants are selected through settings.model\_id. The deprecated elevenlabs\_v3 engine retains its existing behavior while callers and saved defaults migrate. |
| `--force-regenerate` | Bypass HeyGen's speech cache and request fresh synthesis. Normal speech quota applies. Defaults to false. |
| `--input-type <value>` | Type of the input: 'text' for plain text, 'ssml' for SSML markup. Defaults to 'text'. |
| `--language <value>` | Base language code (e.g. 'en', 'pt', 'zh'). Optional — auto-detected from text when omitted. |
| `--locale <value>` | Locale tag for Starfish (e.g. 'zh-HK'). ElevenLabs does not support locale selection; use language instead. |
| `--speed <n>` | Speed multiplier (0.5-2.0). |
| `--text <value>` | Text to synthesize (1-5000 characters). Break tags must express time in seconds (for example, \<break time="0.35s"/>); millisecond values are not supported. (required) |
| `--voice-id <value>` | Voice ID from the voice catalog. Professional voice clones use model speech generation instead. (required) |

## Webhook

Create, list, and manage webhook endpoints and events

| Command | API Endpoint | Description |
| - | - | - |
| `heygen webhook endpoints create` | `POST /v3/webhooks/endpoints` | Create Webhook Endpoint |
| `heygen webhook endpoints delete <endpoint-id>` | `DELETE /v3/webhooks/endpoints/{endpoint_id}` | Delete Webhook Endpoint |
| `heygen webhook endpoints list` | `GET /v3/webhooks/endpoints` | List Webhook Endpoints |
| `heygen webhook endpoints rotate-secret <endpoint-id>` | `POST /v3/webhooks/endpoints/{endpoint_id}/rotate-secret` | Rotate Webhook Signing Secret |
| `heygen webhook endpoints update <endpoint-id>` | `PATCH /v3/webhooks/endpoints/{endpoint_id}` | Update Webhook Endpoint |
| `heygen webhook event-types list` | `GET /v3/webhooks/event-types` | List Webhook Event Types |
| `heygen webhook events list` | `GET /v3/webhooks/events` | List Webhook Events |

### Flags for `webhook endpoints create`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
| `--entity-id <value>` | Optional entity ID to scope this endpoint to a specific resource (e.g. a personalized video project). |
| `--events <values>` | Event types to subscribe to. Omit or set to null to receive all events. |
| `--url <value>` | Publicly accessible HTTPS URL that will receive webhook POST requests. (required) |

### Flags for `webhook endpoints list`

| Flag | Description |
| - | - |
| `--limit <n>` | Maximum number of endpoints to return (1-100). Default: 10. |
| `--token <value>` | Opaque pagination cursor from a previous response's next\_token. |

### Flags for `webhook endpoints rotate-secret`

| Flag | Description |
| - | - |
| `--idempotency-key <value>` | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |

### Flags for `webhook endpoints update`

| Flag | Description |
| - | - |
| `--events <values>` | New list of event types to subscribe to. Replaces the existing list. |
| `--url <value>` | New URL for the endpoint. Must be publicly accessible HTTPS. |

### Flags for `webhook events list`

| Flag | Description |
| - | - |
| `--event-type <value>` | Filter events by type, e.g. 'avatar\_video.success'. |
| `--entity-id <value>` | Filter events by entity ID. |
| `--limit <n>` | Maximum number of events to return (1-100). Default: 10. |
| `--token <value>` | Opaque pagination cursor from a previous response's next\_token. |

## Authentication

| Command | Description |
| - | - |
| `heygen auth login` | Authenticate interactively (prompts for API key) |
| `heygen auth login --oauth` | Log in via browser OAuth — uses subscription credits ([free usage](/docs/for-ai-agents#free-usage)) |
| `heygen auth status` | Verify stored credentials and show account info |

For CI/Docker, use the `HEYGEN_API_KEY` environment variable instead. It takes precedence over stored credentials.

## Utility Commands

| Command | Description |
| - | - |
| `heygen config set <key> <value>` | Set a persistent config value |
| `heygen config get <key>` | Read a config value |
| `heygen config list` | Show all config values and their sources |
| `heygen update` | Self-update to the latest version |
| `heygen update --version <tag>` | Update to a specific version (e.g. `v0.1.0`) |

### Config keys

| Key | Values | Description |
| - | - | - |
| `output` | `json`, `human` | Default output format (default: `json`) |
| `analytics` | `true`, `false` | Enable or disable anonymous usage analytics |


# Create Studio Template via API
Source: https://heygen-1fa696a7.mintlify.app/create-template

Create a template from a video you generated with the API or saved in the HeyGen editor, then mark which parts change. The API version of "Create template" and the editor's variable panel, so the whole template loop runs from code.

<div>
  <Frame>
    <video>
      <source type="video/mp4" />
    </video>
  </Frame>
</div>

<div>
  <Frame>
    <video>
      <source type="video/mp4" />
    </video>
  </Frame>

  <Frame>
    <video>
      <source type="video/mp4" />
    </video>
  </Frame>

  <Frame>
    <video>
      <source type="video/mp4" />
    </video>
  </Frame>
</div>

Create Studio templates **via the API**: turn a video into a reusable template and mark which parts change, without opening the HeyGen editor. Make one good video, promote it to a template, declare its variables, then generate a personalized version per agent, listing or customer.

## What this adds

You could already **use** templates over the API: list them, read them, and generate videos from them. Creating a template and marking its variables needed the HeyGen editor. The authoring endpoints add that first half, so the whole loop runs from code.

| Step | Before | Via the API |
| - | - | - |
| Turn a video into a template | **Create template** on the Videos page | `POST /v3/templates` |
| Mark the parts that change | The editor's **API variable** menu, or typing `{{name}}` | `PUT /v3/templates/{template_id}/variables` |
| Rename or delete it | The template library | `PATCH` / `DELETE /v3/templates/{template_id}` |
| Generate videos | `POST /v3/templates/{template_id}` | Same endpoint, unchanged |

It works with videos you generate through the API, so the whole pipeline runs without a manual step.

Authoring is about **what changes**, not layout. Positions, timing and scenes come from the source video. To change those, edit the template in the HeyGen editor.

<Tip>
  Built your template in the HeyGen editor instead? See [Building a Studio Template](/templates-guide).
</Tip>

## The endpoints

| Endpoint | What it does | Scopes |
| - | - | - |
| [`POST /v3/templates`](/reference/create-template-from-video) | Create a template from a video | `templates:write`, `videos:read` |
| [`GET /v3/templates/{template_id}`](/reference/get-template) | Read a template and its composition | `templates:read` |
| [`PUT /v3/templates/{template_id}/variables`](/reference/set-template-variables) | Declare the template's variables | `templates:write` |
| [`POST /v3/templates/{template_id}`](/reference/generate-video-from-template) | Generate a video from the template | `templates:read`, `videos:write` |
| [`PATCH /v3/templates/{template_id}`](/reference/update-template) | Rename a template | `templates:write` |
| [`DELETE /v3/templates/{template_id}`](/reference/delete-template) | Delete a template | `templates:write` |

The rest of this page builds one real-estate listing template end to end. The agent introduces a property over a photo of the house, and four things become swappable: **the agent** (avatar), **their voice**, **the listing photo**, and **four phrases** in the script.

## Before you start

* An **API key**, sent as the `x-api-key` header.
* A **Creator role or higher** in the workspace, with template creation allowed in the workspace settings. Otherwise the authoring endpoints return `403` `resource_access_denied`.
* A **source video**. It must be one you generated with `POST /v3/videos`, or one you created or saved in the HeyGen editor. URL-to-Video and older editor videos can't be used (`template_source_unsupported`).
* Your own **IDs**. The video, template and element IDs in the examples won't exist in your workspace. Use the ones your responses return. Brandon and Caroline are public avatars and voices, so those IDs work anywhere.

<Tip>
  Want something you can run as-is? [The whole flow in one script](#the-whole-flow-in-one-script) passes each ID to the next step for you.
</Tip>

## Step 1: Make the source video

Write the script with real values, not placeholders. Anything you later want to swap should appear as plain text you can point at, like `42 Maple Lane`. Here the listing photo is the background, and the avatar's own background is removed so the photo shows behind them.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.heygen.com/v3/videos" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d @- <<'JSON'
  {
    "type": "avatar",
    "title": "Listing - 42 Maple Lane (template source)",
    "avatar_id": "Brandon_Business_Standing_Front_public",
    "voice_id": "513b14b431b64a578c467c480dd0a9c3",
    "script": "Hi, I'm Brandon with Bayview Realty. Take a look at 42 Maple Lane: three bedrooms, a sunny kitchen, and a backyard made for summer. It's listed at $749,000. Book your private tour today.",
    "remove_background": true,
    "background": {
      "type": "image",
      "url": "https://images.unsplash.com/photo-1568605114967-8130f3a36994?w=1920&q=80"
    },
    "aspect_ratio": "16:9",
    "resolution": "1080p"
  }
  JSON
  ```

  ```python Python theme={null}
  import requests

  API = "https://api.heygen.com"
  HEADERS = {"x-api-key": "YOUR_API_KEY"}

  video = requests.post(f"{API}/v3/videos", headers=HEADERS, json={
      "type": "avatar",
      "title": "Listing - 42 Maple Lane (template source)",
      "avatar_id": "Brandon_Business_Standing_Front_public",
      "voice_id": "513b14b431b64a578c467c480dd0a9c3",
      "script": (
          "Hi, I'm Brandon with Bayview Realty. Take a look at 42 Maple Lane: three bedrooms, "
          "a sunny kitchen, and a backyard made for summer. It's listed at $749,000. "
          "Book your private tour today."
      ),
      "remove_background": True,
      "background": {"type": "image", "url": "https://images.unsplash.com/photo-1568605114967-8130f3a36994?w=1920&q=80"},
      "aspect_ratio": "16:9",
      "resolution": "1080p",
  }).json()["data"]

  video_id = video["video_id"]
  ```

  ```javascript JavaScript theme={null}
  const API = "https://api.heygen.com";
  const HEADERS = { "x-api-key": "YOUR_API_KEY", "Content-Type": "application/json" };

  const { data: video } = await (await fetch(`${API}/v3/videos`, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify({
      type: "avatar",
      title: "Listing - 42 Maple Lane (template source)",
      avatar_id: "Brandon_Business_Standing_Front_public",
      voice_id: "513b14b431b64a578c467c480dd0a9c3",
      script: "Hi, I'm Brandon with Bayview Realty. Take a look at 42 Maple Lane: three bedrooms, a sunny kitchen, and a backyard made for summer. It's listed at $749,000. Book your private tour today.",
      remove_background: true,
      background: { type: "image", url: "https://images.unsplash.com/photo-1568605114967-8130f3a36994?w=1920&q=80" },
      aspect_ratio: "16:9",
      resolution: "1080p",
    }),
  })).json();

  const videoId = video.video_id;
  ```
</CodeGroup>

```json Example response theme={null}
{
  "data": {
    "output_format": "mp4",
    "status": "waiting",
    "video_id": "3c8e1f6a9b2d4c7e8a5f0b1d6e9c2a47"
  }
}
```

<Tip>
  You don't have to wait for the render. A template copies the video's draft, not its rendered file, so you can create it as soon as you have the `video_id`.
</Tip>

## Step 2: Promote it to a template

Pass the video ID and, optionally, a name (it defaults to the video's title). The template is private to your workspace and starts with **no variables**.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.heygen.com/v3/templates" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"video_id": "3c8e1f6a9b2d4c7e8a5f0b1d6e9c2a47", "name": "Listing video - agent intro"}'
  ```

  ```python Python theme={null}
  template = requests.post(f"{API}/v3/templates", headers=HEADERS, json={
      "video_id": video_id,
      "name": "Listing video - agent intro",
  }).json()["data"]

  template_id = template["id"]
  ```

  ```javascript JavaScript theme={null}
  const { data: template } = await (await fetch(`${API}/v3/templates`, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify({ video_id: videoId, name: "Listing video - agent intro" }),
  })).json();

  const templateId = template.id;
  ```
</CodeGroup>

```jsonc Example response (201 Created, abbreviated) theme={null}
{
  "data": {
    "id": "6f2a9c4e1b7d4f3a8e5c2b9d0a1f7e64",
    "name": "Listing video - agent intro",
    "source_video_id": "3c8e1f6a9b2d4c7e8a5f0b1d6e9c2a47",
    "edit_version": "0",
    "variables": {},
    "composition": {
      "scenes": [
        {
          "id": "scene_0_1790737769242_zrnu3qfqm",
          "background": {
            "id": "bg_image_0_1790737769242_8e1hrymj6",
            "type": "image",
            "url": "https://static.heygen.ai/example-listing-photo.jpg",
            "bindable_as": ["image"]
          },
          "elements": [
            {
              "id": "avatar_0_1790737769242_ltg7rc9hp",
              "type": "avatar",
              "avatar_id": "Brandon_Business_Standing_Front_public",
              "bindable_as": ["character"]
            }
          ],
          "script": [
            {
              "id": "script_0_1790737769242_2bae1yu2m",
              "type": "text",
              "text": "Hi, I'm Brandon with Bayview Realty. Take a look at 42 Maple Lane: three bedrooms, a sunny kitchen, and a backyard made for summer. It's listed at $749,000. Book your private tour today.",
              "voice_id": "513b14b431b64a578c467c480dd0a9c3",
              "bindable_as": ["voice", "text"]
            }
          ]
        }
      ],
      "background_audio": []
    },
    // also returned: aspect_ratio, created_at, updated_at, thumbnail_url when one exists, and the older scenes and scene_ids
  }
}
```

The response is the full template. Note its `id`: every call after this one uses it. Two other fields matter for the next steps: `composition`, which lists every part of the video, and `edit_version`, which starts at `"0"`.

## Step 3: Find the parts you can swap

`composition.scenes` describes each scene. Every part that can take a variable has an `id` and a `bindable_as` list, which says what kind of variable it accepts.

<Frame>
  <img alt="The source frame with the background outlined and labeled image, and the avatar outlined and labeled character" />
</Frame>

In this template there are three parts:

| Part | Where it is in the response | `id` | `bindable_as` |
| - | - | - | - |
| The listing photo | `composition.scenes[0].background` | `bg_image_0_1790737769242_8e1hrymj6` | `image` |
| The agent on screen | `composition.scenes[0].elements[0]` | `avatar_0_1790737769242_ltg7rc9hp` | `character` |
| The spoken line | `composition.scenes[0].script[0]` | `script_0_1790737769242_2bae1yu2m` | `voice`, `text` |

Your template will have different IDs. Take them from the `composition` in your own response.

A template can also contain on-screen text, image and video elements, and `composition.background_audio` tracks for music and sound effects that bind as `audio`. Call `GET /v3/templates/{template_id}` at any time to read the same structure again.

<Note>
  The response also still includes the older `scenes` and `scene_ids` fields. They are kept for existing integrations. Use `composition` for anything new.
</Note>

## Step 4: Declare the variables

A variable is a name plus the part it controls. There are two ways to create one, and most templates use both.

<CardGroup>
  <Card title="Bind a part by element_id" icon="link">
    For `character`, `voice`, `image`, `video` and `audio` variables. Point at a part from Step 3. Each part takes at most one of these.
  </Card>

  <Card title="Match text" icon="text">
    For `text` variables. Give the exact, case-sensitive text. Every occurrence in the script and on-screen text becomes `{{name}}`, and the matched text becomes the default. Add `element_ids` to limit it to specific parts.
  </Card>
</CardGroup>

<Warning>
  `PUT` replaces the template's complete list of variables. On a template that already has variables, read it first and send the full list with its current `edit_version`. [More on this below](#the-put-replaces-the-whole-list).
</Warning>

We bind the agent, their voice and the listing photo, and turn four phrases into text variables:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.heygen.com/v3/templates/6f2a9c4e1b7d4f3a8e5c2b9d0a1f7e64/variables" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d @- <<'JSON'
  {
    "expected_edit_version": "0",
    "variables": {
      "agent": {
        "type": "character",
        "element_id": "avatar_0_1790737769242_ltg7rc9hp"
      },
      "agent_voice": {
        "type": "voice",
        "element_id": "script_0_1790737769242_2bae1yu2m"
      },
      "listing_photo": {
        "type": "image",
        "element_id": "bg_image_0_1790737769242_8e1hrymj6"
      },
      "agent_name": {
        "type": "text",
        "match": "Brandon"
      },
      "brokerage": {
        "type": "text",
        "match": "Bayview Realty"
      },
      "address": {
        "type": "text",
        "match": "42 Maple Lane"
      },
      "price": {
        "type": "text",
        "match": "$749,000"
      }
    }
  }
  JSON
  ```

  ```python Python theme={null}
  scene = template["composition"]["scenes"][0]
  avatar = next(e for e in scene["elements"] if "character" in e["bindable_as"])

  template = requests.put(f"{API}/v3/templates/{template_id}/variables", headers=HEADERS, json={
      "expected_edit_version": template["edit_version"],
      "variables": {
          "agent":         {"type": "character", "element_id": avatar["id"]},
          "agent_voice":   {"type": "voice",     "element_id": scene["script"][0]["id"]},
          "listing_photo": {"type": "image",     "element_id": scene["background"]["id"]},
          "agent_name":    {"type": "text", "match": "Brandon"},
          "brokerage":     {"type": "text", "match": "Bayview Realty"},
          "address":       {"type": "text", "match": "42 Maple Lane"},
          "price":         {"type": "text", "match": "$749,000"},
      },
  }).json()["data"]
  ```

  ```javascript JavaScript theme={null}
  const scene = template.composition.scenes[0];
  const avatar = scene.elements.find((e) => e.bindable_as.includes("character"));

  const { data: updated } = await (await fetch(`${API}/v3/templates/${templateId}/variables`, {
    method: "PUT",
    headers: HEADERS,
    body: JSON.stringify({
      expected_edit_version: template.edit_version,
      variables: {
        agent:         { type: "character", element_id: avatar.id },
        agent_voice:   { type: "voice",     element_id: scene.script[0].id },
        listing_photo: { type: "image",     element_id: scene.background.id },
        agent_name:    { type: "text", match: "Brandon" },
        brokerage:     { type: "text", match: "Bayview Realty" },
        address:       { type: "text", match: "42 Maple Lane" },
        price:         { type: "text", match: "$749,000" },
      },
    }),
  })).json();
  ```
</CodeGroup>

```jsonc Example response (200 OK, abbreviated) theme={null}
{
  "data": {
    "id": "6f2a9c4e1b7d4f3a8e5c2b9d0a1f7e64",
    "edit_version": "1",
    "composition": {
      "scenes": [
        {
          "background": { "id": "bg_image_0_1790737769242_8e1hrymj6", "variable": "listing_photo" },
          "elements": [{ "id": "avatar_0_1790737769242_ltg7rc9hp", "variable": "agent" }],
          "script": [
            {
              "id": "script_0_1790737769242_2bae1yu2m",
              "text": "Hi, I'm {{agent_name}} with {{brokerage}}. Take a look at {{address}}: three bedrooms, a sunny kitchen, and a backyard made for summer. It's listed at {{price}}. Book your private tour today.",
              "text_variables": ["agent_name", "brokerage", "address", "price"],
              "variable": "agent_voice"
            }
          ]
        }
      ]
    },
    "variables": {
      "address": { "content": "42 Maple Lane", "type": "text" },
      "agent": { "type": "character", "avatar_id": "Brandon_Business_Standing_Front_public" },
      "agent_name": { "content": "Brandon", "type": "text" },
      "agent_voice": { "type": "voice", "voice_id": "513b14b431b64a578c467c480dd0a9c3" },
      "brokerage": { "content": "Bayview Realty", "type": "text" },
      "listing_photo": {
        "asset": {
          "type": "url",
          "url": "https://images.unsplash.com/photo-1568605114967-8130f3a36994?w=1920&q=80"
        },
        "fit": "contain",
        "type": "image"
      },
      "price": { "content": "$749,000", "type": "text" }
    },
    // also returned: the rest of the template, as in Step 2
  }
}
```

Look at `composition.scenes[0].script[0].text` in the response. The four phrases are now placeholders:

```text theme={null}
Before: Hi, I'm Brandon with Bayview Realty. Take a look at 42 Maple Lane: ... It's listed at $749,000. ...
After:  Hi, I'm {{agent_name}} with {{brokerage}}. Take a look at {{address}}: ... It's listed at {{price}}. ...
```

Each bound part now carries a `variable` field with its variable's name, `edit_version` went from `"0"` to `"1"`, and `variables` lists each variable with its default value.

### The PUT replaces the whole list

**The body you send becomes the complete list of variables.** Anything you leave out is deleted, and its text goes back to the default.

To add a variable, send the same list again plus the new one. Re-sending a `match` that is already a placeholder is fine.

<CodeGroup>
  ```jsonc Wrong: only the new variable theme={null}
  {
    "variables": {
      "bedrooms": { "type": "text", "match": "three bedrooms" }
    }
  }
  // Result: 1 variable. The other 7 are deleted and the script is back to
  // "Hi, I'm Brandon with Bayview Realty. Take a look at 42 Maple Lane: {{bedrooms}}, ..."
  ```

  ```jsonc Right: the full list plus the new one theme={null}
  {
    "expected_edit_version": "1",
    "variables": {
      "agent":         { "type": "character", "element_id": "avatar_0_1790737769242_ltg7rc9hp" },
      "agent_voice":   { "type": "voice",     "element_id": "script_0_1790737769242_2bae1yu2m" },
      "listing_photo": { "type": "image",     "element_id": "bg_image_0_1790737769242_8e1hrymj6" },
      "agent_name":    { "type": "text", "match": "Brandon" },
      "brokerage":     { "type": "text", "match": "Bayview Realty" },
      "address":       { "type": "text", "match": "42 Maple Lane" },
      "price":         { "type": "text", "match": "$749,000" },
      "bedrooms":      { "type": "text", "match": "three bedrooms" }
    }
  }
  // Result: 8 variables, edit_version "2", and the script reads
  // "Hi, I'm {{agent_name}} with {{brokerage}}. Take a look at {{address}}: {{bedrooms}}, ..."
  ```
</CodeGroup>

### Protect against overwrites with `expected_edit_version`

Every change to the variables increases `edit_version`. Send the version you read as `expected_edit_version`, and the API applies your change only if nobody changed the template since. It prevents this:

<Steps>
  <Step title="You read the template">
    It is at `edit_version` `"1"` with seven variables.
  </Step>

  <Step title="A teammate adds a variable">
    They add `bedrooms`. The template is now at `edit_version` `"2"`.
  </Step>

  <Step title="You send your change">
    Your PUT carries the seven variables you read. Because the PUT replaces the whole list, it would silently delete your teammate's `bedrooms`. With `"expected_edit_version": "1"`, the API sees the template is at `"2"`, **rejects the request, and changes nothing**.
  </Step>

  <Step title="You read again and retry">
    Read the template, which now includes `bedrooms`, add your change, and send it with `"expected_edit_version": "2"`.
  </Step>
</Steps>

This is the rejection, from sending `"0"` after the template had moved to `"1"`:

```json Example response (409 Conflict) theme={null}
{
  "error": {
    "code": "stale_edit_version",
    "doc_url": "https://developers.heygen.com/docs/error-codes#stale-edit-version",
    "message": "Template 6f2a9c4e1b7d4f3a8e5c2b9d0a1f7e64 is at edit_version 1, not 0. Re-read it with GET /v3/templates/6f2a9c4e1b7d4f3a8e5c2b9d0a1f7e64 and send the change again with the current edit_version.",
    "param": "expected_edit_version"
  }
}
```

## Step 5: Generate a video per agent, per listing

Send the values for this video, keyed by variable name. Character, voice and image variables you leave out keep the template's value.

This call swaps in a different agent, Caroline, with her own voice, and a new listing:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.heygen.com/v3/templates/6f2a9c4e1b7d4f3a8e5c2b9d0a1f7e64" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d @- <<'JSON'
  {
    "title": "Listing - 7 Birch Court (Caroline)",
    "variables": {
      "agent": {
        "type": "character",
        "avatar_id": "Caroline_Business_Standing_Front_public"
      },
      "agent_voice": {
        "type": "voice",
        "voice_id": "f8a2cbd411e84454afc4aba8895d0a3b"
      },
      "agent_name": {
        "type": "text",
        "content": "Caroline"
      },
      "brokerage": {
        "type": "text",
        "content": "Summit Homes"
      },
      "address": {
        "type": "text",
        "content": "7 Birch Court"
      },
      "price": {
        "type": "text",
        "content": "$615,000"
      },
      "listing_photo": {
        "type": "image",
        "asset": {
          "type": "url",
          "url": "https://images.unsplash.com/photo-1600596542815-ffad4c1539a9?w=1920&q=80"
        }
      }
    }
  }
  JSON
  ```

  ```python Python theme={null}
  listing = {
      "agent_name": "Caroline", "brokerage": "Summit Homes",
      "address": "7 Birch Court", "price": "$615,000",
      "photo": "https://images.unsplash.com/photo-1600596542815-ffad4c1539a9?w=1920&q=80",
  }

  variables = {k: {"type": "text", "content": listing[k]} for k in ("agent_name", "brokerage", "address", "price")}
  variables["agent"] = {"type": "character", "avatar_id": "Caroline_Business_Standing_Front_public"}
  variables["agent_voice"] = {"type": "voice", "voice_id": "f8a2cbd411e84454afc4aba8895d0a3b"}
  variables["listing_photo"] = {"type": "image", "asset": {"type": "url", "url": listing["photo"]}}

  job = requests.post(f"{API}/v3/templates/{template_id}", headers=HEADERS, json={
      "title": "Listing - 7 Birch Court (Caroline)",
      "variables": variables,
  }).json()["data"]

  new_video_id = job["id"]
  ```

  ```javascript JavaScript theme={null}
  const listing = {
    agent_name: "Caroline", brokerage: "Summit Homes",
    address: "7 Birch Court", price: "$615,000",
    photo: "https://images.unsplash.com/photo-1600596542815-ffad4c1539a9?w=1920&q=80",
  };

  const variables = Object.fromEntries(
    ["agent_name", "brokerage", "address", "price"].map((k) => [k, { type: "text", content: listing[k] }]),
  );
  variables.agent = { type: "character", avatar_id: "Caroline_Business_Standing_Front_public" };
  variables.agent_voice = { type: "voice", voice_id: "f8a2cbd411e84454afc4aba8895d0a3b" };
  variables.listing_photo = { type: "image", asset: { type: "url", url: listing.photo } };

  const { data: job } = await (await fetch(`${API}/v3/templates/${templateId}`, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify({ title: "Listing - 7 Birch Court (Caroline)", variables }),
  })).json();

  const newVideoId = job.id;
  ```
</CodeGroup>

```json Example response (200 OK) theme={null}
{
  "data": {
    "created_at": 1790737782,
    "id": "9d4b7e2a5c1f4a8e9b3d6c0f2e7a1b58",
    "status": "pending",
    "title": "Listing - 7 Birch Court (Caroline)"
  }
}
```

The response comes back right away with the new video's `id`. Both videos below came from the same template:

<CardGroup>
  <Card title="Same agent, new listing">
    Only the text and photo were sent. Brandon and his voice came from the template.

    <video>
      <source type="video/mp4" />
    </video>
  </Card>

  <Card title="New agent, new listing">
    The request above: Caroline, her own voice, and new text and photo.

    <video>
      <source type="video/mp4" />
    </video>
  </Card>
</CardGroup>

<Warning>
  **Always send every text variable.** A text variable you leave out is not filled with its default. HeyGen reads the placeholder name out loud instead. This video was generated with only `address` sent, and it says *"Hi, I'm Agent Name with Brokerage... It's listed at price."*

  <video>
    <source type="video/mp4" />
  </video>

  Read the list of variables from `GET /v3/templates/{template_id}` and fill all the text ones, so a variable added to the template later never slips through.
</Warning>

### Swapped media keeps the source video's framing

When you omit `fit`, a template created with `POST /v3/templates` places the new image or video the way the source video placed the original: a background that filled the frame still fills it, and a photo placed inside a box still fits inside that box. Send `fit` only to change that, for example `"fit": "contain"` to show the whole photo with bars, or `"fit": "cover"` to fill a box that used to show a whole image.

The variable list from `GET /v3/templates/{template_id}` echoes `"fit": "contain"` for image and video variables. That is the default for templates built in the HeyGen editor. On a template created from a video, omitting `fit` keeps the source framing, shown on the left.

<CardGroup>
  <Card title="Default (source framing kept)">
    <img alt="Swapped listing photo filling the whole frame" />
  </Card>

  <Card title="fit: &#x22;contain&#x22;">
    <img alt="Swapped listing photo with white bars on both sides" />
  </Card>
</CardGroup>

## Step 6: Wait for the video

Poll [`GET /v3/videos/{video_id}`](/reference/get-video) until `status` is `completed` (or `failed`), or pass `callback_url` on the generate call to get a webhook instead. When you generate many videos, use webhooks: polling each one adds up against your rate limit.

```bash cURL theme={null}
curl "https://api.heygen.com/v3/videos/9d4b7e2a5c1f4a8e9b3d6c0f2e7a1b58" \
  -H "x-api-key: YOUR_API_KEY"
```

```json Example response (200 OK, completed) theme={null}
{
  "data": {
    "completed_at": 1790738122,
    "created_at": 1790737782,
    "duration": 13.5576,
    "gif_url": "https://resource2.heygen.ai/example-preview.gif",
    "id": "9d4b7e2a5c1f4a8e9b3d6c0f2e7a1b58",
    "status": "completed",
    "thumbnail_url": "https://files2.heygen.ai/example-thumbnail.jpg?Expires=...&Signature=...",
    "title": "Listing - 7 Birch Court (Caroline)",
    "video_page_url": "https://app.heygen.com/videos/9d4b7e2a5c1f4a8e9b3d6c0f2e7a1b58",
    "video_url": "https://files2.heygen.ai/example-video.mp4?Expires=...&Signature=..."
  }
}
```

`video_url` and `thumbnail_url` are signed links that expire. Call this endpoint again whenever you need fresh ones.

## The whole flow in one script

Creates the source video, promotes it, declares variables from the composition, generates one video per listing, and waits for each.

```python Python theme={null}
import time
import requests

API = "https://api.heygen.com"
HEADERS = {"x-api-key": "YOUR_API_KEY"}


def call(method, path, **kwargs):
    response = requests.request(method, API + path, headers=HEADERS, **kwargs)
    response.raise_for_status()
    return response.json()["data"]


# 1. Source video, written with real values
video = call("POST", "/v3/videos", json={
    "type": "avatar",
    "title": "Listing - 42 Maple Lane (template source)",
    "avatar_id": "Brandon_Business_Standing_Front_public",
    "voice_id": "513b14b431b64a578c467c480dd0a9c3",
    "script": (
        "Hi, I'm Brandon with Bayview Realty. Take a look at 42 Maple Lane: three bedrooms, "
        "a sunny kitchen, and a backyard made for summer. It's listed at $749,000. "
        "Book your private tour today."
    ),
    "remove_background": True,
    "background": {"type": "image", "url": "https://images.unsplash.com/photo-1568605114967-8130f3a36994?w=1920&q=80"},
    "aspect_ratio": "16:9",
    "resolution": "1080p",
})

# 2. Promote it (no need to wait for the render)
template = call("POST", "/v3/templates", json={"video_id": video["video_id"], "name": "Listing video - agent intro"})

# 3. Find the parts to bind
scene = template["composition"]["scenes"][0]
avatar = next(e for e in scene["elements"] if "character" in e["bindable_as"])

# 4. Declare the full variable list
template = call("PUT", f"/v3/templates/{template['id']}/variables", json={
    "expected_edit_version": template["edit_version"],
    "variables": {
        "agent":         {"type": "character", "element_id": avatar["id"]},
        "agent_voice":   {"type": "voice",     "element_id": scene["script"][0]["id"]},
        "listing_photo": {"type": "image",     "element_id": scene["background"]["id"]},
        "agent_name":    {"type": "text", "match": "Brandon"},
        "brokerage":     {"type": "text", "match": "Bayview Realty"},
        "address":       {"type": "text", "match": "42 Maple Lane"},
        "price":         {"type": "text", "match": "$749,000"},
    },
})
text_variables = [name for name, v in template["variables"].items() if v["type"] == "text"]

# 5. One video per listing
listings = [
    {"agent_name": "Brandon", "brokerage": "Bayview Realty", "address": "18 Harbor View Drive",
     "price": "$1,125,000", "photo": "https://images.unsplash.com/photo-1570129477492-45c003edd2be?w=1920&q=80"},
    {"agent_name": "Caroline", "brokerage": "Summit Homes", "address": "7 Birch Court",
     "price": "$615,000", "photo": "https://images.unsplash.com/photo-1600596542815-ffad4c1539a9?w=1920&q=80",
     "avatar_id": "Caroline_Business_Standing_Front_public", "voice_id": "f8a2cbd411e84454afc4aba8895d0a3b"},
]

video_ids = []
for listing in listings:
    variables = {name: {"type": "text", "content": listing[name]} for name in text_variables}  # every text variable
    variables["listing_photo"] = {"type": "image", "asset": {"type": "url", "url": listing["photo"]}}
    if "avatar_id" in listing:  # otherwise the template's agent and voice are used
        variables["agent"] = {"type": "character", "avatar_id": listing["avatar_id"]}
        variables["agent_voice"] = {"type": "voice", "voice_id": listing["voice_id"]}
    job = call("POST", f"/v3/templates/{template['id']}", json={"title": listing["address"], "variables": variables})
    video_ids.append(job["id"])

# 6. Wait for each (at scale, pass callback_url instead of polling)
for video_id in video_ids:
    while (status := call("GET", f"/v3/videos/{video_id}"))["status"] not in ("completed", "failed"):
        time.sleep(15)
    print(video_id, status["status"], status.get("video_url"))
```

## Rename and delete

### Rename

`PATCH` renames the template and returns the full template. Renaming does not change `edit_version`. Other changes go through `PUT /v3/templates/{template_id}/variables` or the HeyGen editor.

```bash cURL theme={null}
curl -X PATCH "https://api.heygen.com/v3/templates/6f2a9c4e1b7d4f3a8e5c2b9d0a1f7e64" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Listing video - agent intro (v2)"}'
```

```jsonc Example response (200 OK, abbreviated) theme={null}
{
  "data": {
    "id": "6f2a9c4e1b7d4f3a8e5c2b9d0a1f7e64",
    "name": "Listing video - agent intro (v2)",
    "edit_version": "1",
    "updated_at": 1790737790,
    // also returned: the rest of the template, unchanged
  }
}
```

### Delete

`DELETE` removes the template from your list so it can no longer generate videos. Videos you already generated from it are not affected. There is no request body.

```bash cURL theme={null}
curl -X DELETE "https://api.heygen.com/v3/templates/6f2a9c4e1b7d4f3a8e5c2b9d0a1f7e64" \
  -H "x-api-key: YOUR_API_KEY"
```

```json Example response (200 OK) theme={null}
{
  "data": {
    "deleted": true,
    "id": "6f2a9c4e1b7d4f3a8e5c2b9d0a1f7e64"
  }
}
```

Reading a deleted template afterwards returns a 404:

```json Example response (404 Not Found) theme={null}
{
  "error": {
    "code": "template_not_found",
    "doc_url": "https://developers.heygen.com/docs/error-codes#template-not-found",
    "message": "Template not found"
  }
}
```

## Errors

| Status and code | When it happens | What to do |
| - | - | - |
| `400` `template_source_unsupported` | The source video has no current-format draft (URL-to-Video, older editor videos). | Recreate it with `POST /v3/videos`, or save it in the HeyGen editor. |
| `400` `variable_match_not_found` | A `match` text doesn't occur in the template's script or on-screen text. Matching is exact and case-sensitive. | Check the current text in `composition`. If it's already a `{{name}}` placeholder, declare the variable without `match`. |
| `400` `variable_match_spans_styles` | The `match` text runs across differently styled parts of rich text, such as half bold and half regular. | Match a shorter piece inside one style, or make the styling uniform in the editor. |
| `400` `template_limit_reached` | The workspace already has the maximum number of templates (2000). | Delete templates you no longer need, then retry. |
| `403` `insufficient_api_key_scope` | The API key is missing a scope the endpoint needs. | Check the key's permissions against the endpoints table above. |
| `403` `resource_access_denied` | Your role is below Creator, or template creation is turned off in the workspace settings. | Ask a workspace admin. |
| `403` `forbidden` | The template authoring endpoints aren't enabled for your workspace yet. | Contact support. |
| `404` `video_not_found` | The `video_id` isn't in this workspace. | Check the ID, and that the API key belongs to the same workspace. |
| `404` `template_not_found` | The template ID is wrong, in another workspace, or deleted. | List your templates with [`GET /v3/templates`](/reference/list-templates). |
| `409` `stale_edit_version` | The template changed after you read it. | Read it again, apply your change to the new list, and send it with the new `edit_version`. |

## FAQ

<AccordionGroup>
  <Accordion title="Which avatars can I swap in?">
    Any avatar look you can use, from [`GET /v3/avatars/looks`](/reference/list-avatar-looks), including your own digital twin or photo avatar. Pair a `character` variable with a `voice` variable so the voice matches the person.
  </Accordion>

  <Accordion title="My template already has {{placeholders}} from the editor. How do I keep them?">
    Declare the text variable without `match`, for example `"first_name": { "type": "text" }`. Placeholders that already exist are kept.
  </Accordion>

  <Accordion title="Can I render only some scenes?">
    Yes. Pass `scene_ids` on the generate call to pick, reorder or repeat scenes that exist in the template.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup>
  <Card title="Studio Template reference" icon="book" href="/templates">
    Every variable type, asset input and generate option.
  </Card>

  <Card title="Building a Studio Template" icon="wand-magic-sparkles" href="/templates-guide">
    The same flow, with the template built in the HeyGen editor.
  </Card>
</CardGroup>


# API Key
Source: https://heygen-1fa696a7.mintlify.app/docs/api-key

Generate your HeyGen API key in under a minute. Authenticate requests for avatar video generation, translation, and streaming.

<img alt="" />

## Getting Your API Key

1. Go to the [API keys page](https://platform.heygen.com/api-keys).
2. Click to generate your API key.

## Configuring Your API Key

### Environment variable (recommended)

<CodeGroup>
  ```bash bash theme={null}
  export HEYGEN_API_KEY="your-api-key-here"
  ```
</CodeGroup>

### `.env` file

If your project uses a `.env` file (common with Node.js, Python, or frameworks like Next.js):

```text theme={null}
HEYGEN_API_KEY=your-api-key-here
```

### Claude Code

If you're using Claude Code or any terminal-based workflow, set the key in your shell before starting:

<CodeGroup>
  ```bash bash theme={null}
  export HEYGEN_API_KEY="your-api-key-here"
  claude  # or whatever command starts your session
  ```
</CodeGroup>

Alternatively, add it to your shell profile (`~/.bashrc`, `~/.zshrc`) so it persists across sessions:

<CodeGroup>
  ```bash bash theme={null}
  echo 'export HEYGEN_API_KEY="your-api-key-here"' >> ~/.zshrc
  source ~/.zshrc
  ```
</CodeGroup>

### HeyGen Skills (in Claude)

When using HeyGen through the Skills integration in Claude's computer environment, the API key is read from the environment. Make sure `HEYGEN_API_KEY` is set before the skill executes any API calls.

## Using the Key in Requests

All HeyGen API requests authenticate via the `X-Api-Key` header. The base URL for all endpoints is `https://api.heygen.com`. When auth fails, the API returns [`unauthorized` (401)](/docs/error-codes#unauthorized).

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.heygen.com/v3/avatars" \
    -H "X-Api-Key: $HEYGEN_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.heygen.com/v3/avatars", {
    headers: { "X-Api-Key": process.env.HEYGEN_API_KEY },
  });
  ```

  ```python Python theme={null}
  import os, requests

  response = requests.get(
      "https://api.heygen.com/v3/avatars",
      headers={"X-Api-Key": os.environ["HEYGEN_API_KEY"]}
  )
  ```
</CodeGroup>

### Quick verification

You can verify your key is working by fetching your account info. Full schema: [`GET /v3/users/me`](/reference/get-current-user).

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.heygen.com/v3/users/me" \
    -H "X-Api-Key: $HEYGEN_API_KEY"
  ```

  ```json Response theme={null}
  {
    "data": {
      "username": "jane_doe",
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "billing_type": "wallet",
      "wallet": {
        "currency": "usd",
        "remaining_balance": 42.50,
        "auto_reload": { "enabled": false }
      }
    }
  }
  ```
</CodeGroup>

A `200` response with your account details confirms your key is valid. The `billing_type` and corresponding billing field (`wallet`, `subscription`, or `usage_based`) show your current balance and billing model.

## Restricting Key Permissions

Use permission scopes to limit a key to only the resources and actions it needs. See [API Key Permission Scopes](/docs/api-key-permissions) for the complete, automatically updated mapping of scopes to endpoints.

To check which scopes a key holds, call [`GET /v3/api_keys/self`](/reference/get-current-api-key) with that key. It returns the key's name, `scope_mode` (`full`, `read_only`, or `custom`), `scopes`, and expiration, and works with any key regardless of its scopes.

## Security Best Practices

* **Never commit your API key to version control.** Add `.env` to your `.gitignore`.
* **Never expose the key in client-side / browser code.** Always call the API from a backend or server environment.
* **Rotate your key periodically** via the API dashboard.
* **Monitor usage** on the [Usage page](https://platform.heygen.com/usage).


# API Key Permission Scopes
Source: https://heygen-1fa696a7.mintlify.app/docs/api-key-permissions

Find the API key permission scopes required by each public HeyGen API endpoint.

Permission scopes let you restrict an API key to the HeyGen resources and actions it needs. Each scope uses the form `resource:read` or `resource:write`.

## How permissions work

* An endpoint can require one scope or several scopes. When several are listed, the key must satisfy all of them.
* A `resource:write` grant also satisfies `resource:read` for the same resource. A read grant never satisfies a write requirement.
* Full-access keys use `*:*`. Read-only keys use `*:read`, which satisfies every current and future read requirement.
* A key without the required permissions receives a `403` [`insufficient_api_key_scope`](/docs/error-codes#insufficient-api-key-scope) response.

Create and manage keys in the [HeyGen API dashboard](https://app.heygen.com/developers/api).

## Scope-to-endpoint mapping

This reference is generated from the permission metadata in the published OpenAPI specification. Only public, documented endpoints are included. An endpoint with multiple requirements appears under every required scope.

### `account:read`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`GET /v3/users/me`](/reference/get-current-user) | Get Current User | `account:read` |

### `ai_clipping:read`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`GET /v3/ai-clipping`](/reference/list-ai-clipping) | List AI Clipping | `ai_clipping:read` |
| [`GET /v3/ai-clipping/{job_id}`](/reference/get-ai-clipping) | Get AI Clipping | `ai_clipping:read` |

### `ai_clipping:write`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`POST /v3/ai-clipping`](/reference/create-ai-clipping) | Create AI Clipping | `ai_clipping:write` |
| [`DELETE /v3/ai-clipping/{job_id}`](/reference/delete-ai-clipping) | Delete AI Clipping | `ai_clipping:write` |

### `assets:read`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`GET /v3/assets/batches/{batch_id}`](/reference/get-asset-batch) | Get Asset Batch | `assets:read` |
| [`GET /v3/assets/statuses`](/reference/bulk-asset-statuses) | Bulk Asset Statuses | `assets:read` |
| [`GET /v3/assets/{asset_id}`](/reference/get-asset) | Get Asset | `assets:read` |
| [`GET /v3/audio/sounds`](/reference/search-audio-music-or-sound-effects) | Search audio (music or sound effects) | `assets:read` |

### `assets:write`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`POST /v3/assets`](/reference/upload-asset) | Upload Asset | `assets:write` |
| [`POST /v3/assets/complete/batches`](/reference/complete-asset-upload-batch) | Complete Asset Upload Batch | `assets:write` |
| [`POST /v3/assets/direct-uploads`](/reference/create-asset-upload) | Create Asset Upload | `assets:write` |
| [`POST /v3/assets/direct-uploads/batches`](/reference/create-asset-upload-batch) | Create Asset Upload Batch | `assets:write` |
| [`DELETE /v3/assets/{asset_id}`](/reference/delete-asset) | Delete Asset | `assets:write` |
| [`POST /v3/assets/{asset_id}/complete`](/reference/complete-asset-upload) | Complete Asset Upload | `assets:write` |

### `avatars:read`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`GET /v3/avatars`](/reference/list-avatar-groups) | List Avatar Groups | `avatars:read` |
| [`GET /v3/avatars/look-templates`](/reference/list-look-templates) | List Look Templates | `avatars:read` |
| [`GET /v3/avatars/looks`](/reference/list-avatar-looks) | List Avatar Looks | `avatars:read` |
| [`GET /v3/avatars/looks/{look_id}`](/reference/get-avatar-look) | Get Avatar Look | `avatars:read` |
| [`GET /v3/avatars/{group_id}`](/reference/get-avatar-group) | Get Avatar Group | `avatars:read` |

### `avatars:write`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`POST /v3/avatars`](/reference/create-avatar) | Create Avatar | `avatars:write` |
| [`POST /v3/avatars/looks`](/reference/create-avatar-looks) | Create Avatar Looks | `avatars:write` |
| [`PATCH /v3/avatars/looks/{look_id}`](/reference/update-avatar-look) | Update Avatar Look | `avatars:write` |
| [`DELETE /v3/avatars/looks/{look_id}`](/reference/delete-avatar-look) | Delete Avatar Look | `avatars:write` |
| [`PATCH /v3/avatars/{group_id}`](/reference/update-avatar-group) | Update Avatar Group | `avatars:write` |
| [`DELETE /v3/avatars/{group_id}`](/reference/delete-avatar-group) | Delete Avatar Group | `avatars:write` |
| [`POST /v3/avatars/{group_id}/consent`](/reference/create-avatar-consent) | Create Avatar Consent | `avatars:write` |

### `brand:read`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`GET /v3/brand-glossaries`](/reference/list-brand-glossaries) | List Brand Glossaries | `brand:read` |
| [`GET /v3/brand-glossaries/{brand_glossary_id}`](/reference/get-brand-glossary) | Get Brand Glossary | `brand:read` |
| [`GET /v3/brand-kits`](/reference/list-brand-kits) | List Brand Kits | `brand:read` |
| [`GET /v3/brand-kits/{brand_kit_id}`](/reference/get-brand-kit) | Get Brand Kit | `brand:read` |

### `brand:write`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`POST /v3/brand-glossaries`](/reference/create-brand-glossary) | Create Brand Glossary | `brand:write` |
| [`PATCH /v3/brand-glossaries/{brand_glossary_id}`](/reference/update-brand-glossary) | Update Brand Glossary | `brand:write` |
| [`DELETE /v3/brand-glossaries/{brand_glossary_id}`](/reference/delete-brand-glossary) | Delete Brand Glossary | `brand:write` |
| [`POST /v3/brand-kits`](/reference/create-brand-kit) | Create Brand Kit | `brand:write` |
| [`PATCH /v3/brand-kits/{brand_kit_id}`](/reference/update-brand-kit) | Update Brand Kit | `brand:write` |
| [`DELETE /v3/brand-kits/{brand_kit_id}`](/reference/delete-brand-kit) | Delete Brand Kit | `brand:write` |

### `filler_removal:read`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`GET /v3/filler-word-removals/{filler_word_removal_id}`](/reference/get-filler-word-removal) | Get Filler Word Removal | `filler_removal:read` |

### `filler_removal:write`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`POST /v3/filler-word-removals`](/reference/create-filler-word-removal) | Create Filler Word Removal | `filler_removal:write` |

### `hyperframes:read`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`GET /v3/hyperframes/renders`](/reference/list-hyperframes-renders) | List HyperFrames Renders | `hyperframes:read` |
| [`GET /v3/hyperframes/renders/{render_id}`](/reference/get-hyperframes-render) | Get HyperFrames Render | `hyperframes:read` |

### `hyperframes:write`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`POST /v3/hyperframes/renders`](/reference/create-hyperframes-render) | Create HyperFrames Render | `hyperframes:write` |
| [`DELETE /v3/hyperframes/renders/{render_id}`](/reference/delete-hyperframes-render) | Delete HyperFrames Render | `hyperframes:write` |

### `images:read`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`GET /v3/models/images/{generation_id}`](/reference/get-heygen-image) | Get HeyGen Image | `images:read` |

### `images:write`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`POST /v3/models/images`](/reference/create-heygen-image) | Create HeyGen Image | `images:write` |

### `lipsync:read`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`GET /v3/lipsyncs`](/reference/list-lipsyncs) | List Lipsyncs | `lipsync:read` |
| [`GET /v3/lipsyncs/batches/{batch_id}`](/reference/get-lipsync-batch) | Get Lipsync Batch | `lipsync:read` |
| [`GET /v3/lipsyncs/statuses`](/reference/bulk-lipsync-statuses) | Bulk Lipsync Statuses | `lipsync:read` |
| [`GET /v3/lipsyncs/{lipsync_id}`](/reference/get-lipsync) | Get Lipsync | `lipsync:read` |

### `lipsync:write`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`POST /v3/lipsyncs`](/reference/create-lipsync) | Create Lipsync | `lipsync:write` |
| [`POST /v3/lipsyncs/batches`](/reference/create-lipsync-batch) | Create Lipsync Batch | `lipsync:write` |
| [`PATCH /v3/lipsyncs/{lipsync_id}`](/reference/update-lipsync) | Update Lipsync | `lipsync:write` |
| [`DELETE /v3/lipsyncs/{lipsync_id}`](/reference/delete-lipsync) | Delete Lipsync | `lipsync:write` |

### `templates:read`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`GET /v3/templates`](/reference/list-templates) | List Templates | `templates:read` |
| [`GET /v3/templates/{template_id}`](/reference/get-template) | Get Template | `templates:read` |
| [`POST /v3/templates/{template_id}`](/reference/generate-video-from-template) | Generate Video from Template | `templates:read`, `videos:write` |

### `templates:write`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`POST /v3/templates`](/reference/create-template-from-video) | Create Template from Video | `templates:write`, `videos:read` |
| [`PATCH /v3/templates/{template_id}`](/reference/update-template) | Update Template | `templates:write` |
| [`DELETE /v3/templates/{template_id}`](/reference/delete-template) | Delete Template | `templates:write` |
| [`PUT /v3/templates/{template_id}/variables`](/reference/set-template-variables) | Set Template Variables | `templates:write` |

### `translations:read`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`GET /v3/video-translations`](/reference/list-video-translations) | List Video Translations | `translations:read` |
| [`GET /v3/video-translations/batches/{batch_id}`](/reference/get-video-translation-batch) | Get Video Translation Batch | `translations:read` |
| [`GET /v3/video-translations/languages`](/reference/list-supported-translation-languages) | List Supported Translation Languages | `translations:read` |
| [`GET /v3/video-translations/proofreads`](/reference/list-proofread-sessions) | List Proofread Sessions | `translations:read` |
| [`GET /v3/video-translations/proofreads/{proofread_id}`](/reference/get-proofread-session) | Get Proofread Session | `translations:read` |
| [`GET /v3/video-translations/proofreads/{proofread_id}/srt`](/reference/download-proofread-srt) | Download Proofread SRT | `translations:read` |
| [`GET /v3/video-translations/statuses`](/reference/bulk-video-translation-statuses) | Bulk Video Translation Statuses | `translations:read` |
| [`GET /v3/video-translations/{video_translation_id}`](/reference/get-video-translation) | Get Video Translation | `translations:read` |

### `translations:write`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`POST /v3/video-translations`](/reference/create-video-translation) | Create Video Translation | `translations:write` |
| [`POST /v3/video-translations/batches`](/reference/create-video-translation-batch) | Create Video Translation Batch | `translations:write` |
| [`POST /v3/video-translations/proofreads`](/reference/create-proofread-session) | Create Proofread Session | `translations:write` |
| [`DELETE /v3/video-translations/proofreads/{proofread_id}`](/reference/delete-proofread-session) | Delete Proofread Session | `translations:write` |
| [`POST /v3/video-translations/proofreads/{proofread_id}/generate`](/reference/generate-video-from-proofread) | Generate Video from Proofread | `translations:write` |
| [`PUT /v3/video-translations/proofreads/{proofread_id}/srt`](/reference/upload-proofread-srt) | Upload Proofread SRT | `translations:write` |
| [`PATCH /v3/video-translations/{video_translation_id}`](/reference/update-video-translation) | Update Video Translation | `translations:write` |
| [`DELETE /v3/video-translations/{video_translation_id}`](/reference/delete-video-translation) | Delete Video Translation | `translations:write` |

### `video_agent:read`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`GET /v3/video-agents`](/reference/list-video-agent-sessions) | List Video Agent Sessions | `video_agent:read` |
| [`GET /v3/video-agents/styles`](/reference/list-video-agent-styles) | List Video Agent Styles | `video_agent:read` |
| [`GET /v3/video-agents/{session_id}`](/reference/get-video-agent-session) | Get Video Agent Session | `video_agent:read` |
| [`GET /v3/video-agents/{session_id}/resources/{resource_id}`](/reference/get-session-resource) | Get Session Resource | `video_agent:read` |
| [`GET /v3/video-agents/{session_id}/videos`](/reference/list-session-videos) | List Session Videos | `video_agent:read` |

### `video_agent:write`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`POST /v3/video-agents`](/reference/create-video-agent-session) | Create Video Agent Session | `video_agent:write` |
| [`POST /v3/video-agents/{session_id}`](/reference/send-message-or-request-revision) | Send Video Agent Message | `video_agent:write` |
| [`POST /v3/video-agents/{session_id}/stop`](/reference/stop-video-agent-session) | Stop Video Agent Session | `video_agent:write` |

### `videos:read`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`GET /v3/folders/{folder_id}`](/reference/get-folder) | Get Folder | `videos:read` |
| [`GET /v3/models/videos/{video_id}`](/reference/get-heygen-video) | Get HeyGen Video | `videos:read` |
| [`POST /v3/templates`](/reference/create-template-from-video) | Create Template from Video | `templates:write`, `videos:read` |
| [`GET /v3/videos`](/reference/list-videos) | List Videos | `videos:read` |
| [`GET /v3/videos/batches/{batch_id}`](/reference/get-video-batch) | Get Video Batch | `videos:read` |
| [`GET /v3/videos/statuses`](/reference/bulk-video-statuses) | Bulk Video Statuses | `videos:read` |
| [`GET /v3/videos/{video_id}`](/reference/get-video) | Get Video | `videos:read` |
| [`GET /v3/videos/{video_id}/scenes`](/reference/get-video-scenes) | Get Video Scenes | `videos:read` |

### `videos:write`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`POST /v3/folders`](/reference/create-folder) | Create Folder | `videos:write` |
| [`POST /v3/models/videos`](/reference/create-heygen-video) | Create HeyGen Video | `videos:write` |
| [`POST /v3/templates/{template_id}`](/reference/generate-video-from-template) | Generate Video from Template | `templates:read`, `videos:write` |
| [`POST /v3/videos`](/reference/create-video) | Create Video | `videos:write` |
| [`POST /v3/videos/batches`](/reference/create-video-batch) | Create Video Batch | `videos:write` |
| [`DELETE /v3/videos/{video_id}`](/reference/delete-video) | Delete Video | `videos:write` |

### `voices:read`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`GET /v3/models/audio/voices`](/reference/list-audio-voices) | List Audio Voices | `voices:read` |
| [`GET /v3/models/audio/voices/{voice_id}`](/reference/get-an-audio-voice) | Get an Audio Voice | `voices:read` |
| [`GET /v3/voices`](/reference/list-voices) | List Voices | `voices:read` |
| [`GET /v3/voices/{voice_id}`](/reference/get-voice) | Get Voice | `voices:read` |

### `voices:write`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`POST /v3/models/audio/tts`](/reference/generate-model-speech) | Generate Speech | `voices:write` |
| [`POST /v3/models/audio/tts/stream`](/reference/stream-speech) | Stream Speech | `voices:write` |
| [`POST /v3/models/audio/voices`](/reference/create-or-retrain-an-audio-voice) | Create or Retrain an Audio Voice | `voices:write` |
| [`DELETE /v3/models/audio/voices/{voice_id}`](/reference/delete-an-audio-voice) | Delete an Audio Voice | `voices:write` |
| [`POST /v3/voices`](/reference/design-a-voice) | Design a Voice | `voices:write` |
| [`POST /v3/voices/clone`](/reference/clone-a-voice) | Clone a Voice | `voices:write` |
| [`POST /v3/voices/speech`](/reference/generate-speech) | Generate Speech | `voices:write` |
| [`DELETE /v3/voices/{voice_id}`](/reference/delete-a-voice) | Delete a Voice | `voices:write` |

### `webhooks:read`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`GET /v3/webhooks/endpoints`](/reference/list-webhook-endpoints) | List Webhook Endpoints | `webhooks:read` |
| [`GET /v3/webhooks/event-types`](/reference/list-webhook-event-types) | List Webhook Event Types | `webhooks:read` |
| [`GET /v3/webhooks/events`](/reference/list-webhook-events) | List Webhook Events | `webhooks:read` |

### `webhooks:write`

| Endpoint | Description | Required scopes |
| - | - | - |
| [`POST /v3/webhooks/endpoints`](/reference/create-webhook-endpoint) | Create Webhook Endpoint | `webhooks:write` |
| [`PATCH /v3/webhooks/endpoints/{endpoint_id}`](/reference/update-webhook-endpoint) | Update Webhook Endpoint | `webhooks:write` |
| [`DELETE /v3/webhooks/endpoints/{endpoint_id}`](/reference/delete-webhook-endpoint) | Delete Webhook Endpoint | `webhooks:write` |
| [`POST /v3/webhooks/endpoints/{endpoint_id}/rotate-secret`](/reference/rotate-webhook-signing-secret) | Rotate Webhook Signing Secret | `webhooks:write` |


# Avatar Consent
Source: https://heygen-1fa696a7.mintlify.app/docs/avatar-consent

How HeyGen verifies that the person in a digital twin agreed to be cloned — the three levels of consent access, and the API flow for collecting it.

<img alt="" />

Before you can generate video with a **digital twin** ([`type: "digital_twin"`](/docs/avatar-from-video)), HeyGen needs proof that the person depicted agreed to be cloned. This protects the avatar subject, your account, and HeyGen — and it's what lets you use a real person's likeness responsibly at scale.

<Note>
  The consent API step applies only to **digital twin** avatars. A group created from a photo (`type: "photo"`) or prompt (`type: "prompt"`) has no consent request to make and reports `consent_status` of `null`. If you add a photo or prompt look to an existing group, it retains that group's consent status.

  A photo avatar is still built from a real person's image. Having no API step to complete is not permission to use someone's likeness. HeyGen runs no consent check and keeps no consent record for a photo avatar, so getting the subject's agreement before you create one, and keeping your own record of it, is your responsibility. Your account team can answer questions about your contract terms.
</Note>

## The three levels of access

Consent is offered as **three increasing levels of access**. Each level removes friction from the flow, and each is unlocked for a progressively narrower set of accounts. Higher levels are more powerful and correspondingly more restricted.

| Level | Flow | Who it's for | Availability |
| - | - | - | - |
| **1. Record via webcam** | The avatar subject records a short consent statement on camera through HeyGen's hosted consent page. | All customers | Available today |
| **2. Upload a consent video** | You supply a pre-recorded consent video instead of recording live — more flexible, but consent is still explicitly captured. | Enterprise only | Available today — [contact sales](https://www.heygen.com/contact-us/sales) |
| **3. Skip the consent flow** | Consent collection is waived entirely for accounts that have signed an indemnity agreement. | Enterprise only | [Contact sales](https://www.heygen.com/contact-us/sales) |

## Collect consent via API

One endpoint drives both **Level 1** and **Level 2**: [`POST /v3/avatars/{group_id}/consent`](/reference/create-avatar-consent). By default it starts the webcam flow and returns a URL for the avatar subject — the link is valid for **24 hours**; enterprise accounts can pass a pre-recorded [`consent_video`](#upload-a-consent-video-level-2) instead.

### Record via webcam (Level 1)

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/avatars/group_xyz789/consent" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reroute_url": "https://heygen.com/consent-done"
  }'
```

| Parameter | Type | Required | Description |
| - | - | - | - |
| `reroute_url` | string | No | Redirect URL after the subject completes consent. Defaults to HeyGen's own completion page. Applies to the webcam flow only. |

#### Response

```json theme={null}
{
  "data": {
    "avatar_group": {
      "id": "group_xyz789",
      "name": "My Digital Twin",
      "consent_status": "pending",
      "looks_count": 1,
      "created_at": 1717000000
    },
    "url": "https://heygen.com/consent/abc123..."
  }
}
```

| Field | Type | Description |
| - | - | - |
| `url` | string | Consent page URL. Send this to the avatar subject to complete approval. The link expires after **24 hours** — call the endpoint again to issue a fresh one. Returned for the webcam flow; when you upload a `consent_video`, the group is all you need, so the field is omitted. |
| `avatar_group.consent_status` | string | Current consent status of the group: `pending` (awaiting the subject or under review), `accepted` (consent cleared), or `rejected` (resubmit). `null` for photo and prompt groups. |

### Upload a consent video (Level 2)

Enterprise accounts can submit a pre-recorded consent statement directly — same endpoint, with `consent_video` in place of the flow parameters:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/avatars/group_xyz789/consent" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "consent_video": { "type": "url", "url": "https://example.com/consent.mp4" }
  }'
```

| Parameter | Type | Required | Description |
| - | - | - | - |
| `consent_video` | object | Yes, for this flow | The pre-recorded consent video, as `{"type": "url", "url": "https://..."}` or `{"type": "asset_id", "asset_id": "..."}` (see [Upload Assets](/docs/upload-assets) for uploading). |

The video is submitted immediately for review — the subject never visits a consent page, so the response contains the `avatar_group` alone and no `url`. Because there is no hosted page in this flow, send `consent_video` on its own, without the webcam-flow parameters. This flow is enterprise-only — please [reach out to sales](https://www.heygen.com/contact-us/sales) or your account team to request access.

#### What the consent video must contain

Because the upload flow has no hosted page prompting the subject, you provide the statement yourself. Consent is validated **semantically**, so minor wording differences are fine, and **the statement can be in any language**. Translate it however fits your subject. The current recommended statement:

> "Hey there! I'm speaking with LOTS of energy, while staying natural and confident. This helps HeyGen capture my voice, my expressions, and my motion, so my avatar can behave JUST like me in ANY video!"

| Requirement | Detail |
| - | - |
| Consent statement | The subject clearly reads the statement above, in any language (translate as needed). |
| Same person | Must be the same person as the training footage (identity-matched). |
| One visible face | A single, clearly visible face on camera. |
| Audio | Clearly audible. |
| Length | Under 35 seconds. A short clip is enough, and longer clips are rejected. |
| Format | A standard video file (for example MP4), supplied as a public HTTPS URL or an uploaded `asset_id`. |

<Note>
  Record the consent clip separately from the training footage. Training footage works best at about 2 minutes of natural talking (see [Footage that trains well](/docs/avatar-from-video#footage-that-trains-well)), while the consent clip must be under 35 seconds.
</Note>

No passcode is required for the upload path — a spoken code applies only to the interactive webcam flow (Level 1).

<Tip>
  Check `consent_status` on the avatar group via [`GET /v3/avatars/{group_id}`](/reference/get-avatar-group) to know when consent is complete. It is `null` for a group created from a photo or a prompt, which has no consent step. The status belongs to the group, not the individual look.
</Tip>

## Track the result

There is no webhook for consent. Poll [`GET /v3/avatars/{group_id}`](/reference/get-avatar-group) after submitting; review usually completes within a few minutes. The [`instant_avatar.success` and `instant_avatar.fail`](/docs/webhook-events) webhook events report twin training, not consent.

When `consent_status` is `rejected`, the group's `status` is `failed` and `error.message` explains why in plain language you can show the subject:

```json theme={null}
{
  "data": {
    "id": "group_xyz789",
    "name": "My Digital Twin",
    "consent_status": "rejected",
    "status": "failed",
    "error": {
      "code": "moderation_failed",
      "message": "Please make sure your consent video is under 35s."
    },
    "looks_count": 1,
    "created_at": 1717000000
  }
}
```

Fix the issue and call the consent endpoint again.

### Resubmit after a rejection

You can call [`POST /v3/avatars/{group_id}/consent`](/reference/create-avatar-consent) again for a group whose `consent_status` is `rejected`, with a new webcam link or a new `consent_video`. While a submitted consent video is still under review, the endpoint returns a `400` asking you to wait, and once consent is `accepted` it returns a `400` because consent is already complete. Send the `Idempotency-Key` header so a network retry does not create a second submission.

## Where consent fits

Consent is one step in the digital twin flow. To create the avatar itself, see [Create Avatar](/docs/create-avatar); to browse the resulting characters and looks, see [Avatars](/docs/avatars) and [Avatar Looks](/docs/avatar-looks).


# Photo to Avatar
Source: https://heygen-1fa696a7.mintlify.app/docs/avatar-from-photo

Turn one still image into a HeyGen avatar with POST /v3/avatars. The fastest creation path: no footage, no consent step, and the photo becomes the reference for every later look.

<img alt="" />

A **photo avatar** is built from a single still image. It is the fastest way into the API: no recording session, and no consent step, since a group created from a photo reports `consent_status` of `null`. The image is still of a real person. HeyGen does not collect a consent record for photo avatars, so getting the subject's permission and keeping your own record of it is your responsibility, as [Avatar Consent](/docs/avatar-consent) explains. Questions about your contract terms go to your account team.

<Steps>
  <Step title="Create the avatar">
    ```bash theme={null}
    curl -X POST "https://api.heygen.com/v3/avatars" \
      -H "X-Api-Key: $HEYGEN_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "photo",
        "name": "Sarah",
        "file": { "type": "url", "url": "https://example.com/sarah-headshot.png" }
      }'
    ```

    `file` also takes `{ "type": "asset_id", "asset_id": "..." }` from [`POST /v3/assets`](/docs/upload-assets), or base64 content. Add `avatar_group_id` to add this photo as another look on a character you already have; `consent_status` is a property of the group, so the response reports whatever that group already carries.

    Save `avatar_item.id` from the response. That is the `avatar_id` for video creation.
  </Step>

  <Step title="Wait for processing">
    Poll [`GET /v3/avatars/looks/{look_id}`](/reference/get-avatar-look) until `status` leaves `processing`.

    ```bash theme={null}
    curl -X GET "https://api.heygen.com/v3/avatars/looks/$LOOK_ID" \
      -H "X-Api-Key: $HEYGEN_API_KEY"
    ```

    A `completed` look returns `preview_image_url` and the `supported_api_engines` it renders on. A `failed` one carries `error.code` of `training_failed` or `moderation_failed`, with the reason in `error.message`.
  </Step>

  <Step title="Render">
    Photo avatars accept `motion_prompt` and `expressiveness` on [`POST /v3/videos`](/reference/create-video), which direct how much the subject moves while speaking.

    ```bash theme={null}
    curl -X POST "https://api.heygen.com/v3/videos" \
      -H "X-Api-Key: $HEYGEN_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "avatar",
        "avatar_id": "look_abc123",
        "voice_id": "voice_xyz789",
        "script": "Here is what changed in this release."
      }'
    ```

    Pick a voice with [`GET /v3/voices`](/docs/voices/search-voices), or set one as the character default through [`PATCH /v3/avatars/{group_id}`](/reference/update-avatar-group) and leave `voice_id` out. The [Photo Avatar](/photo-avatar) recipe covers the render end to end.
  </Step>
</Steps>

<Tip>
  A clear, front-facing portrait in even lighting works best: whole head in frame, one person, as much resolution as you have. The image becomes the visual reference the character is remembered by, so choose the shot you want every later look to resemble.
</Tip>

## Give the character more looks

The photo is the identity reference for everything that follows. Pass its look id as `avatar_id` to [Prompt to Avatar](/docs/avatar-from-prompt) to put the same person in a new outfit or setting, or apply a [Look Pack](/docs/avatar-look-packs) for a coordinated set in one call.

New looks join the same character, and [`GET /v3/avatars/looks?group_id=...`](/reference/list-avatar-looks) lists them all.


# Prompt to Avatar
Source: https://heygen-1fa696a7.mintlify.app/docs/avatar-from-prompt

Generate a synthetic avatar from a text description with POST /v3/avatars, or put an avatar you already have into a new outfit and setting by passing it as the visual reference.

<img alt="" />

Describe a character and [`POST /v3/avatars`](/reference/create-avatar) with `type: "prompt"` generates it. The same call does double duty: pass an existing look as `avatar_id` and the prompt becomes a new outfit, setting, or style for that character instead of a new person.

<Tabs>
  <Tab title="A new character">
    ```bash theme={null}
    curl -X POST "https://api.heygen.com/v3/avatars" \
      -H "X-Api-Key: $HEYGEN_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "prompt",
        "name": "Space Commander",
        "prompt": "Woman in her early 30s, confident expression, short silver hair, dark blue flight suit with mission patches, spacecraft bridge with holographic displays, cinematic lighting",
        "aspect_ratio": "16:9"
      }'
    ```

    `prompt` holds up to 1000 characters. `aspect_ratio` takes `16:9`, `9:16`, `1:1`, `4:5`, `5:4`, or `auto`, which lets the model choose and matches a reference image's ratio when one is given. Omitting it is the same as `auto`.

    The character is fully synthetic, so no real person is depicted and no consent step applies.
  </Tab>

  <Tab title="A new look for your avatar">
    ```bash theme={null}
    curl -X POST "https://api.heygen.com/v3/avatars" \
      -H "X-Api-Key: $HEYGEN_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "prompt",
        "name": "Sarah, navy blazer",
        "prompt": "Wearing a navy blazer, modern office with plants behind her, warm natural light",
        "avatar_id": "look_abc123"
      }'
    ```

    The referenced look's image conditions the generation, so the person stays recognisable while the prompt changes everything around them. The result saves to that character automatically.

    This works from any starting point: a [digital twin](/docs/avatar-from-video), a [photo avatar](/docs/avatar-from-photo), or an earlier prompt avatar. Any of the resulting looks can be the reference for the next one.
  </Tab>

  <Tab title="With reference images">
    ```bash theme={null}
    curl -X POST "https://api.heygen.com/v3/avatars" \
      -H "X-Api-Key: $HEYGEN_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "prompt",
        "name": "Sarah, studio portrait",
        "prompt": "Wearing the coat from the reference, plain studio backdrop, soft key light",
        "avatar_id": "look_abc123",
        "reference_images": [
          { "type": "url", "url": "https://example.com/coat-reference.png" }
        ]
      }'
    ```

    Up to three `reference_images` add wardrobe, style, or setting guidance, each given as a url, an `asset_id` from [`POST /v3/assets`](/docs/upload-assets), or base64 content. Use them alone to steer a brand-new character, or layer them on an `avatar_id` reference.

    A crop showing only the garment keeps the reference about wardrobe and fabric, leaving the face to the `avatar_id` reference.
  </Tab>
</Tabs>

## Reference and destination

Two fields decide where the look comes from and where it lands:

| `avatar_id` | `avatar_group_id` | Visual reference | Saved to |
| - | - | - | - |
| absent | absent | the prompt alone | a new character |
| absent | set | the prompt alone | that character |
| set | absent | the referenced look's image | the referenced look's character |
| set | set | the referenced look's image | `avatar_group_id`, which the look must belong to |

<Warning>
  **Changed behavior (June 2026):** `avatar_group_id` used to condition the generation on one of the group's looks. It now only controls where the result is saved. Pass the base look's id as `avatar_id` for character consistency. See the [changelog](/changelog).
</Warning>

## Writing the prompt

<Tip>
  Name the age, expression, wardrobe, setting, and light. Camera direction is obeyed when it is explicit, as in "turned three-quarters toward camera left, with clean space on the left of the frame". Texture words such as "natural matte skin, visible pores, no retouching" pull toward realism, and naming a lens or aperture pushes further.
</Tip>

Details you leave out get invented plausibly, including text on badges and props, so read the generated image before writing a script around it. [Writing Effective Video Prompts](/writing-effective-video-prompts) goes deeper.

## Wait for it, then render

Poll [`GET /v3/avatars/looks/{look_id}`](/reference/get-avatar-look) until `status` leaves `processing`. A `completed` look returns `preview_image_url` and its `supported_api_engines`. Then pass the look id as `avatar_id` to [`POST /v3/videos`](/reference/create-video) with a `voice_id` from [`GET /v3/voices`](/docs/voices/search-voices).

Prompt avatars render on [Avatar V, IV, and III](/models). Check `supported_api_engines` before requesting a specific engine.

A referenced `avatar_id` that does not exist returns `404` with `error.code` of `avatar_not_found`. One that has no usable image, or that is not in the `avatar_group_id` you gave, returns `400` with `invalid_parameter`.


# Video to Avatar
Source: https://heygen-1fa696a7.mintlify.app/docs/avatar-from-video

Train a digital twin from video footage of a person with POST /v3/avatars. Covers footage that trains well, the voice cloned alongside it, consent, and polling to completed.

<img alt="" />

A **digital twin** is trained from footage of a real person, and clones a voice from the same recording so the twin speaks in the subject's own voice.

<Steps>
  <Step title="Create the twin">
    ```bash theme={null}
    curl -X POST "https://api.heygen.com/v3/avatars" \
      -H "X-Api-Key: $HEYGEN_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "digital_twin",
        "name": "Sarah",
        "file": { "type": "url", "url": "https://example.com/sarah-footage.mp4" }
      }'
    ```

    `file` also takes `{ "type": "asset_id", "asset_id": "..." }` from [`POST /v3/assets`](/docs/upload-assets), or base64 content.

    `avatar_group_id` decides which character the twin belongs to:

    * **Pass an existing `avatar_group_id`** to add the twin as another look of a character you already have. Only do this for the same person, since consent is tracked per group.
    * **Leave it out** to create a new avatar group (a new character) for this person. The new group id is returned as `avatar_group.id`.

    <Info>
      A `url` input is fetched when you call the endpoint and is capped at 32 MB, the same as [`POST /v3/assets`](/docs/upload-assets). Signed or presigned HTTPS URLs work as long as they are reachable at that moment, but they do not raise the cap. Base64 input is capped at 16 MB after decoding. For recommended footage (about 2 minutes at 1080p), use [direct upload](/docs/upload-assets#upload-large-files-direct-upload), then pass `{ "type": "asset_id", "asset_id": "asset_abc123" }`. An `asset_id` stays usable until you delete it, so reuse the same one if you retry creation.
    </Info>

    Keep two values from the response: `avatar_item.id` is the `avatar_id` you render with, and `avatar_group.id` is what the consent flow acts on. Store the group id per person, since it is also the `avatar_group_id` you pass to add more looks of them later.
  </Step>

  <Step title="Wait for training">
    Poll [`GET /v3/avatars/looks/{look_id}`](/reference/get-avatar-look) until `status` leaves `processing`; training usually completes within a few minutes.

    ```bash theme={null}
    curl -X GET "https://api.heygen.com/v3/avatars/looks/$LOOK_ID" \
      -H "X-Api-Key: $HEYGEN_API_KEY"
    ```

    To be notified instead of polling, subscribe a [webhook endpoint](/docs/webhooks) to the `instant_avatar.success` and `instant_avatar.fail` [events](/docs/webhook-events).

    A `failed` look carries an `error` object: `training_failed` when the footage could not be trained, `moderation_failed` when it did not pass content review. The reason is in `error.message`.
  </Step>

  <Step title="Collect consent">
    [`POST /v3/avatars/{group_id}/consent`](/reference/create-avatar-consent) returns a link, valid for 24 hours, that the subject opens to record a short statement on camera. Enterprise workspaces can upload a pre-recorded consent video or have the step waived.

    An uploaded consent video must be under 35 seconds and show the same person as the footage. Record it as its own short clip, separate from the training footage. See [Avatar Consent](/docs/avatar-consent#what-the-consent-video-must-contain) for what it must contain.

    [Avatar Consent](/docs/avatar-consent) has the three levels of access and the full flow.
  </Step>

  <Step title="Render">
    Render once the look reports `status: "completed"` and the group has cleared consent. No other publish step is needed.

    Pass the look id as `avatar_id`. Omitting `voice_id` falls back to the character's default voice, which is the group's linked voice when the twin joined an existing group. Pass `avatar_item.default_voice_id` from the create response to speak in the voice cloned from this footage.

    ```bash theme={null}
    curl -X POST "https://api.heygen.com/v3/videos" \
      -H "X-Api-Key: $HEYGEN_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "avatar",
        "avatar_id": "look_abc123",
        "voice_id": "voice_cloned123",
        "script": "Thanks for joining today. Here is what shipped this week."
      }'
    ```

    The [Digital Twin](/generate-avatar-video) recipe walks the render end to end, and [Models](/models) compares the engines a twin supports.
  </Step>
</Steps>

## Footage that trains well

| Attribute | Requirement | Recommended |
| - | - | - |
| Duration | 15 to 600 seconds | About 2 minutes of natural talking |
| Resolution | Long edge at least 640 px, at most 4096 px (4K) | 1080p |
| Format | mp4 or webm | mp4 |
| People in frame | One, facing camera for the whole recording | |
| Audio | Clear, audible speech throughout | Quiet room, no background music |
| Framing | The face stays in frame from first frame to last | |

Longer footage with varied natural speech gives the model more to learn from. About 2 minutes at 1080p gives the best twin quality.

A clip like that is usually larger than 32 MB, so upload it with [direct upload](/docs/upload-assets#upload-large-files-direct-upload), which accepts video files up to 200 MB, and pass the `asset_id`. If your recording is over 200 MB, export it at a lower bitrate before uploading.

## The cloned voice

<Info>
  Creating a digital twin clones one voice from the training footage automatically. There is no separate voice request and no opt-in step. The id is returned immediately as `avatar_item.default_voice_id`, while the avatar and the voice finish processing.

  The cloned voice is its own resource. Deleting the twin's look or group does not delete it; remove it with [`DELETE /v3/voices/{voice_id}`](/reference/delete-a-voice).
</Info>

Two voice ids travel with a twin and they can differ. `avatar_item.default_voice_id` is the voice cloned from this request's footage. `avatar_group.default_voice_id` is the effective voice for the character: a linked group voice takes precedence, falling back to the new look's clone.

Set the character's voice deliberately by sending `default_voice_id` to [`PATCH /v3/avatars/{group_id}`](/reference/update-avatar-group). Any voice in your workspace works, including [cloned voices](/docs/voices/heygen-voice-instant-clone).

To give the same person more outfits and settings, generate looks from [a prompt](/docs/avatar-from-prompt) or a [Look Pack](/docs/avatar-look-packs).


# Look Packs and Templates
Source: https://heygen-1fa696a7.mintlify.app/docs/avatar-look-packs

Generate a coordinated set of looks for an avatar you already own with POST /v3/avatars/looks. Apply a Look Pack for a full set, or a single look template to restyle one look.

<img alt="" />

[`POST /v3/avatars/looks`](/reference/create-avatar-looks) dresses an avatar you already own in curated looks. Give it one existing look as the identity reference and a curated `template_id`, and the new looks join that look's character.

Where prompting gives you [one look at a time in your own words](/docs/avatar-from-prompt), a pack gives you a whole coordinated set in one call.

<Steps>
  <Step title="Pick a method">
    | `type` | What it applies | How many looks |
    | - | - | - |
    | `look_pack` | A Look Pack: a curated set built around one theme. | The pack decides. Every pack in the gallery today produces five. |
    | `template` | A single look template, restyling the reference look into it. | Two, in the template's aspect ratio. |
  </Step>

  <Step title="Pick a template id">
    Eight packs from the gallery. **Style packs**, the first four, keep the setting neutral and move the wardrobe and palette. **Role packs**, the last four, put your avatar into a job with the wardrobe and setting that go with it.

    <CardGroup>
      <Card title="Modern Corporate" />

      <Card title="Stylish Business-Casual" />

      <Card title="Scandinavian Minimal" />

      <Card title="Cool Tech / Slate" />

      <Card title="Healthcare" />

      <Card title="Keynote Power Presenter" />

      <Card title="Fitness" />

      <Card title="Automotive Dealership" />
    </CardGroup>

    Template ids are 32-character hex strings, and every pack ships as a female and a male variant, so pick the one matching your avatar.

    | Look Pack | Female | Male |
    | - | - | - |
    | Modern Corporate | `5a8e6be843ee4321a014946bf62aa322` | `5e659e76755d47fd9160a2d7dedce124` |
    | Stylish Business-Casual | `e1650a9029d04ea1a350421c163295fd` | `a5f8e0c0cb654c1a83c695629b173af5` |
    | Scandinavian Minimal | `e7b000e2cb0d44f1a2d2f291a38b395a` | `9600f78f27bb49d792e1c56ce624b929` |
    | Cool Tech / Slate | `d7ad40ec97d4459a92b33398b57caf4e` | `fbd03fc3603a4e3caff594f5743a1733` |
    | Healthcare | `14f4070bd5a04eb6b1f82ae087cd0f30` | `ce706bfa8556401e8c4401765102a455` |
    | Keynote Power Presenter | `b0cae4fbae384ab9ab9a8e73ba504be8` | `71e84769162d4f4186563ad9e0fc45b8` |
    | Fitness | `935ea0b7cdde4e6eb5a198a3d666f677` | `daeb8b15c92a4acf9ffb437ba5534458` |
    | Automotive Dealership | `6f183d726933457c9035fc0aa4e9c0c3` | `8595c78b466c4e51802731229c59b6e7` |

    The full gallery is browsable in the [HeyGen app](https://app.heygen.com), covering real estate, legal, teaching, construction and more. Enterprise workspaces can have custom packs built and assigned to them, which then work here exactly like the rest. To have one assigned, [contact sales](https://www.heygen.com/contact-us/sales).
  </Step>

  <Step title="Send the request">
    <Tabs>
      <Tab title="Look Pack">
        ```bash theme={null}
        # Reuse this key when retrying this exact request in the same shell.
        # For a different Look Pack request, unset LOOK_PACK_KEY first.
        LOOK_PACK_KEY="${LOOK_PACK_KEY:-$(uuidgen)}"

        curl -X POST "https://api.heygen.com/v3/avatars/looks" \
          -H "X-Api-Key: $HEYGEN_API_KEY" \
          -H "Content-Type: application/json" \
          -H "Idempotency-Key: $LOOK_PACK_KEY" \
          -d '{
            "type": "look_pack",
            "reference_look_id": "look_abc123",
            "template_id": "5a8e6be843ee4321a014946bf62aa322",
            "aspect_ratio": "16:9"
          }'
        ```

        Packs generate at `16:9`. Pass `aspect_ratio: "9:16"` and the delivered frames are center-cropped to portrait as the final step, which is worth knowing when you plan the framing of the reference look.
      </Tab>

      <Tab title="Single template">
        ```bash theme={null}
        # Reuse this key when retrying this exact request in the same shell.
        # For a different single-template request, unset SINGLE_TEMPLATE_KEY first.
        SINGLE_TEMPLATE_KEY="${SINGLE_TEMPLATE_KEY:-$(uuidgen)}"

        curl -X POST "https://api.heygen.com/v3/avatars/looks" \
          -H "X-Api-Key: $HEYGEN_API_KEY" \
          -H "Content-Type: application/json" \
          -H "Idempotency-Key: $SINGLE_TEMPLATE_KEY" \
          -d '{
            "type": "template",
            "reference_look_id": "look_abc123",
            "template_id": "b30c83d99cec48e09c8f5b07ed8aa38c"
          }'
        ```

        A single template returns two looks in the template's own aspect ratio, so `aspect_ratio` does not apply here.

        Single templates are one card each rather than a themed set. The id above is Business Casual for a female avatar. The male one is `2dc326030e2e4471babcc9eda56131b6`, and Podcast is `00c49daa4eb94386a0c12508043bab17` for female and `0e52ceafe4d5456fb83c1e39899ff76a` for male.
      </Tab>
    </Tabs>

    `reference_look_id` is any look you own, from [a digital twin](/docs/avatar-from-video), [a photo](/docs/avatar-from-photo), or [a prompt](/docs/avatar-from-prompt). Its character is where the results land, so there is no group field to set.
  </Step>

  <Step title="Poll the new looks">
    The response names the character the looks joined and gives one id per look being generated:

    ```json theme={null}
    {
      "data": {
        "group_id": "group_xyz789",
        "looks": [
          { "id": "look_def456" },
          { "id": "look_ghi789" },
          { "id": "look_jkl012" },
          { "id": "look_mno345" },
          { "id": "look_pqr678" }
        ]
      }
    }
    ```

    Each id starts at `processing`. Poll [`GET /v3/avatars/looks/{look_id}`](/reference/get-avatar-look) until it reports `completed`, at which point the preview is available and the id is usable as `avatar_id` for [`POST /v3/videos`](/reference/create-video), or `failed`, where `error.message` gives the reason.

    To see every look on the character at once, including the originals, call [`GET /v3/avatars/looks?group_id=group_xyz789`](/reference/list-avatar-looks).
  </Step>
</Steps>

<Tip>
  Send an `Idempotency-Key` header so a retry after a network timeout cannot start a second generation. The examples preserve their keys when rerun in the same shell; in an application, persist the key with the request so a restart can retry with the same key and body. Use a new key for each different request. While the original request is still in flight, a retry returns `409` with `error.code` of `request_in_progress`: wait, then retry. Once the original finishes, a retry within 24 hours replays its response.
</Tip>

## Template access

A template id your workspace has access to resolves normally. One that belongs to another workspace returns `403`, and an id that matches no template returns `400`. Sending a pack id with `type: "template"`, or a single template id with `type: "look_pack"`, returns a `400` naming the method that would have taken it.


# Avatar Looks
Source: https://heygen-1fa696a7.mintlify.app/docs/avatar-looks

Browse and select avatar looks (outfits, poses, hair styles) for any HeyGen avatar group via the Avatar Looks API.

<img alt="" />

A **look** is one outfit/pose/style for a character ([avatar group](/docs/avatars)). It's the value you pass as `avatar_id` to video creation. List via [`GET /v3/avatars/looks`](/reference/list-avatar-looks), fetch one via [`GET /v3/avatars/looks/{look_id}`](/reference/get-avatar-look), or [Update](/reference/update-avatar-look) / [Delete](/reference/delete-avatar-look) your own. To create a new look, see [Create Avatar](/docs/create-avatar).

## Quick Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.heygen.com/v3/avatars/looks?avatar_type=photo_avatar&ownership=public&limit=5" \
    -H "X-Api-Key: $HEYGEN_API_KEY"
  ```

  ```json Response theme={null}
  {
    "data": [
      {
        "id": "look_def456",
        "name": "Monica - Business Casual",
        "avatar_type": "photo_avatar",
        "group_id": "group_abc123",
        "gender": "female",
        "preview_image_url": "https://files.heygen.ai/look/preview_def456.jpg",
        "preview_video_url": "https://files.heygen.ai/look/preview_def456.mp4",
        "default_voice_id": "voice_xyz789",
        "tags": ["business", "casual", "female"],
        "supported_api_engines": ["avatar_iv", "avatar_v"],
        "status": "completed"
      }
    ],
    "has_more": true,
    "next_token": "eyJsYXN0X2lkIjoiNDU2In0"
  }
  ```
</CodeGroup>

## Query Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `group_id` | string | No | — | Filter looks to a specific avatar group. Returns only looks belonging to this character. |
| `avatar_type` | string | No | all | `"studio_avatar"`, `"digital_twin"`, or `"photo_avatar"`. |
| `ownership` | string | No | all | `"public"` for HeyGen presets or `"private"` for your own. Omit for both. |
| `limit` | integer | No | `20` | Results per page (1–50). |
| `token` | string | No | — | Opaque cursor token for the next page. |

## Response Fields

Each look in the `data` array contains:

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique look identifier. **This is the value to pass as `avatar_id`** to [`POST /v3/videos`](/reference/create-video) or [`POST /v3/video-agents`](/reference/create-video-agent-session). |
| `name` | string | Display name of the look. |
| `avatar_type` | string | One of `"studio_avatar"`, `"digital_twin"`, or `"photo_avatar"`. Determines engine and parameter compatibility. |
| `group_id` | string or null | ID of the avatar group (character) this look belongs to. |
| `gender` | string or null | Gender of the avatar. |
| `preview_image_url` | string or null | URL to a preview image. |
| `preview_video_url` | string or null | URL to a preview video. |
| `default_voice_id` | string or null | Default voice ID for this look — see [Browse Voices](/docs/voices/search-voices). |
| `tags` | array | Tags associated with the look (e.g. `["business", "casual"]`). |
| `supported_api_engines` | array | Engine values this look accepts for [`POST /v3/videos`](/reference/create-video): `"avatar_iii"`, `"avatar_iv"`, and/or `"avatar_v"`. Check this array before requesting a specific `engine` — requesting an engine that isn't listed returns `invalid_parameter`. |
| `status` | string or null | Training status: `"processing"`, `"completed"`, or `"failed"`. Only present for private avatars. |

## Avatar Types

The `avatar_type` field determines what features and parameters are available when creating a video:

| Type | Description |
| - | - |
| `studio_avatar` | Pre-built HeyGen studio avatars with fixed poses and backgrounds. |
| `digital_twin` | Avatars created from video footage. Support background removal by default on new twins. |
| `photo_avatar` | Avatars generated from a single photo. Support `motion_prompt` and `expressiveness` in video creation. |

## Get a Single Look

Full schema: [`GET /v3/avatars/looks/{look_id}`](/reference/get-avatar-look). To rename or retag, use [`PATCH /v3/avatars/looks/{look_id}`](/reference/update-avatar-look); to remove, [`DELETE`](/reference/delete-avatar-look).

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.heygen.com/v3/avatars/looks/look_def456" \
    -H "X-Api-Key: $HEYGEN_API_KEY"
  ```

  ```json Response theme={null}
  {
    "data": {
      "id": "look_def456",
      "name": "Monica - Business Casual",
      "avatar_type": "photo_avatar",
      "group_id": "group_abc123",
      "gender": "female",
      "preview_image_url": "https://files.heygen.ai/look/preview_def456.jpg",
      "preview_video_url": "https://files.heygen.ai/look/preview_def456.mp4",
      "default_voice_id": "voice_xyz789",
      "tags": ["business", "casual", "female"],
      "supported_api_engines": ["avatar_iv", "avatar_v"],
      "status": "completed"
    }
  }
  ```
</CodeGroup>

## Filtering by Group

To see all outfits and styles for a specific character, pass its `group_id`:

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.heygen.com/v3/avatars/looks?group_id=group_abc123" \
    -H "X-Api-Key: $HEYGEN_API_KEY"
  ```
</CodeGroup>

## Pagination

If `has_more` is `true`, pass the `next_token` value as the `token` query parameter to fetch the next page.

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.heygen.com/v3/avatars/looks?token=eyJsYXN0X2lkIjoiNDU2In0" \
    -H "X-Api-Key: $HEYGEN_API_KEY"
  ```
</CodeGroup>

## Using a Look in Video Creation

Once you have a look `id`, pass it as `avatar_id`. When you request a specific rendering engine, pick one from the look's `supported_api_engines` array — for example, pass `"engine": {"type": "avatar_v"}` when the array includes `"avatar_v"`. Omitting `engine` uses Avatar IV. See [Models](/models) for how the engines compare.

<CodeGroup>
  ```bash "Video Agent" theme={null}
  curl -X POST "https://api.heygen.com/v3/video-agents" \
    -H "X-Api-Key: $HEYGEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "A product demo for our new app",
      "avatar_id": "look_def456"
    }'
  ```

  ```bash "Avatar Video" theme={null}
  curl -X POST "https://api.heygen.com/v3/videos" \
    -H "X-Api-Key: $HEYGEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "avatar",
      "avatar_id": "look_def456",
      "voice_id": "voice_xyz789",
      "script": "Welcome to our product walkthrough."
    }'
  ```
</CodeGroup>


# Avatar Groups
Source: https://heygen-1fa696a7.mintlify.app/docs/avatars

Generate AI avatar videos via the HeyGen API. Choose from 500+ stock avatars or train custom digital twins. Includes avatar looks, voices, and instant.

<img alt="" />

Avatars come in two layers: a **group** is a character (e.g. "Monica"); each group has one or more **looks** (outfits, poses, styles). This page is about listing and inspecting groups via [`GET /v3/avatars`](/reference/list-avatar-groups) and [`GET /v3/avatars/{group_id}`](/reference/get-avatar-group). To pick a specific look to render with, see [Avatar Looks](/docs/avatar-looks). To train your own avatar, see [Create Avatar](/docs/create-avatar).

## Quick Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.heygen.com/v3/avatars?ownership=public&limit=5" \
    -H "X-Api-Key: $HEYGEN_API_KEY"
  ```

  ```json Response theme={null}
  {
    "data": [
      {
        "id": "group_abc123",
        "name": "Monica",
        "gender": "female",
        "preview_image_url": "https://files.heygen.ai/avatar/preview_abc123.jpg",
        "preview_video_url": "https://files.heygen.ai/avatar/preview_abc123.mp4",
        "looks_count": 3,
        "default_voice_id": "voice_xyz789",
        "consent_status": null,
        "status": "completed",
        "created_at": 1711382400
      }
    ],
    "has_more": true,
    "next_token": "eyJsYXN0X2lkIjoiMTIzIn0"
  }
  ```
</CodeGroup>

## Query Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `ownership` | string | No | all | `"public"` for HeyGen's preset avatars or `"private"` for your own. Omit for both. |
| `limit` | integer | No | `20` | Results per page (1–50). |
| `token` | string | No | — | Opaque cursor token for the next page. |

## Response Fields

Each avatar group in the `data` array contains:

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique group identifier. Pass to [`GET /v3/avatars/{group_id}`](/reference/get-avatar-group) for details, or use as `group_id` in [`GET /v3/avatars/looks`](/reference/list-avatar-looks) to filter. |
| `name` | string | Display name of the avatar character. |
| `gender` | string or null | Gender of the avatar. |
| `preview_image_url` | string or null | URL to a preview image. |
| `preview_video_url` | string or null | URL to a preview video. |
| `looks_count` | integer | Number of looks (outfits/styles) available for this character. |
| `default_voice_id` | string or null | Default voice ID for this avatar — pair with [Browse Voices](/docs/voices/search-voices) or [`GET /v3/voices`](/reference/list-voices). |
| `consent_status` | string or null | Consent status for the group: `"pending"`, `"accepted"`, or `"rejected"`. `null` means consent is not required, as for photo and prompt groups, which have no consent step. |
| `status` | string or null | Group status, driven by consent and review: `"pending_consent"`, `"completed"`, or `"failed"` (consent rejected, reason in `error.message`). Training progress is reported on each look's `status`, see [Avatar Looks](/docs/avatar-looks). Only present for private avatars. |
| `created_at` | integer | Unix timestamp of creation. |

## Get a Single Avatar Group

Full schema: [`GET /v3/avatars/{group_id}`](/reference/get-avatar-group). To change the default voice of an avatar you own, send `default_voice_id` to [`PATCH /v3/avatars/{group_id}`](/reference/update-avatar-group); any voice available to your workspace works, including imported clones. Public avatars cannot be updated.

To remove a character you own and every look in it, call [`DELETE /v3/avatars/{group_id}`](/reference/delete-avatar-group). Source assets and any cloned voice are kept; see [Delete an avatar](/docs/create-avatar#delete-an-avatar).

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.heygen.com/v3/avatars/group_abc123" \
    -H "X-Api-Key: $HEYGEN_API_KEY"
  ```

  ```json Response theme={null}
  {
    "data": {
      "id": "group_abc123",
      "name": "Monica",
      "gender": "female",
      "preview_image_url": "https://files.heygen.ai/avatar/preview_abc123.jpg",
      "preview_video_url": "https://files.heygen.ai/avatar/preview_abc123.mp4",
      "looks_count": 3,
      "default_voice_id": "voice_xyz789",
      "consent_status": null,
      "status": "completed",
      "created_at": 1711382400
    }
  }
  ```
</CodeGroup>

## Pagination

If `has_more` is `true`, pass the `next_token` value as the `token` query parameter to fetch the next page.

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.heygen.com/v3/avatars?token=eyJsYXN0X2lkIjoiMTIzIn0" \
    -H "X-Api-Key: $HEYGEN_API_KEY"
  ```
</CodeGroup>

## Avatars vs. Looks

Avatar **groups** represent characters (e.g. "Monica"). Each group has one or more **looks** — different outfits, poses, or styles for that character. When creating a video, you pass a **look ID** (not a group ID) as the `avatar_id`. See [Avatar Looks](/docs/avatar-looks) for how to browse and select looks.


# Brand Glossary
Source: https://heygen-1fa696a7.mintlify.app/docs/brand-glossary

Control how HeyGen says and translates your custom terms. Create a brand glossary over the API with pronunciations, do-not-translate terms, and forced translations, then pass its brand_glossary_id on videos and translations.

<img alt="" />

A brand glossary holds your terms and how HeyGen should treat them: how the voice pronounces them, and whether translation keeps or replaces them. Pass its `brand_glossary_id` on a video or translation request to apply it. Glossaries can be authored in the HeyGen app under **Brand Kit** or over the API; the API is how you give each of your own customers their own vocabulary.

<Info>
  **API reference:** [Create Brand Glossary](/reference/create-brand-glossary) · [Update Brand Glossary](/reference/update-brand-glossary) · [Get Brand Glossary](/reference/get-brand-glossary) · [List Brand Glossaries](/reference/list-brand-glossaries) · [Delete Brand Glossary](/reference/delete-brand-glossary)
</Info>

## Three lists

| List | Applies in | Effect |
| - | - | - |
| `terms` | Generation: [Studio](/studio-videos), [Templates](/templates), `avatar` and `image` videos, [Video Agent](/docs/video-agent) | The voice says `pronunciation` instead of `term`. Captions keep the original spelling. |
| `do_not_translate_terms` | Translation: [video translation](/docs/video-translate) over the API, and a Studio or Video Agent draft translated in the HeyGen app | `term` stays untranslated in every target language. |
| `forced_translations` | Translation, as above | `term` becomes its exact `translation` in every target language. |

Translation rules take effect only through a translation feature; plain video generation and text-to-speech use `terms` alone. Matching is case-insensitive. A `translation` is inserted verbatim with no inflection, so pick a form that reads correctly on its own. If a term is in both `do_not_translate_terms` and `forced_translations`, it stays untranslated.

## Create

[`POST /v3/brand-glossaries`](/reference/create-brand-glossary) takes a `name` (1–64 characters, unique per workspace) and any of the three lists. The `201` response is the full glossary, usable immediately.

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/brand-glossaries" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "name": "Acme Product Names",
    "terms": [
      { "term": "HeyGen", "pronunciation": "hey-jen" },
      { "term": "2024", "pronunciation": "twenty twenty-four" }
    ],
    "do_not_translate_terms": [
      { "term": "HeyGen" }
    ],
    "forced_translations": [
      { "term": "CEO", "translation": "Geschäftsführer" }
    ]
  }'
```

A pronunciation is a respelling, written the way you would coach someone to say it: `hey-jen`, `hyper frames`, `twenty twenty-four`. Add a term once you have heard it come out wrong.

## Language-specific rules

A pronunciation or forced translation can apply to one language. Add `pronunciation_language` to a `terms` entry or `target_language` to a `forced_translations` entry:

```json theme={null}
{
  "terms": [
    { "term": "Acme", "pronunciation": "ack-mee" },
    { "term": "Acme", "pronunciation": "ak-may", "pronunciation_language": { "scope": "specific", "code": "fr" } }
  ],
  "forced_translations": [
    { "term": "Hello", "translation": "Bonjour", "target_language": { "scope": "specific", "code": "fr" } }
  ]
}
```

Here French videos say `ak-may` and every other language says `ack-mee`.

* Omit the field, or send `{ "scope": "all" }`, for a rule that applies to all languages.
* `code` is a base language code: `fr`, `es`, `de`.
* A language-specific rule takes precedence over an all-languages rule for that language.
* The same term can appear once per language in each list.
* `do_not_translate_terms` always applies to all languages.

Responses include the language field only on language-specific rules, so all-languages entries keep their existing shape.

## Update

[`PATCH /v3/brand-glossaries/{brand_glossary_id}`](/reference/update-brand-glossary) replaces each field independently. Omit a field to leave it alone, send a list to replace it in full, send `[]` to clear it. Send at least one field. A list replaces that kind of rule across every language, so send language-specific entries back with their language fields. A term repeated for the same language within one list returns `409 conflict`.

To add a single entry, read the glossary, append, and send the whole list back:

```python theme={null}
import requests

base = "https://api.heygen.com/v3/brand-glossaries/8c2d5e91a47b4f3c8d1e6a9b2f5c7d40"
headers = {"X-Api-Key": HEYGEN_API_KEY}

current = requests.get(base, headers=headers).json()["data"]["terms"]
current.append({"term": "Reformer", "pronunciation": "ree-form-er"})

requests.patch(base, headers=headers, json={"terms": current})
```

Tone settings are managed in the HeyGen app under **Brand Kit** and are untouched by `PATCH`.

## Read

[`GET /v3/brand-glossaries`](/reference/list-brand-glossaries) lists names, IDs, and timestamps, paged with `limit` and `token`. [`GET /v3/brand-glossaries/{brand_glossary_id}`](/reference/get-brand-glossary) returns the full glossary; `do_not_translate_terms` and `forced_translations` appear whenever the glossary has rules of that kind, including rules set in the app. Read it when a video pronounces or translates a term unexpectedly.

## Delete

[`DELETE /v3/brand-glossaries/{brand_glossary_id}`](/reference/delete-brand-glossary) removes a glossary. Videos and translations already created with it are unaffected. This cannot be undone.

## Apply

Pass `brand_glossary_id` at the top level of the request, one glossary per call:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar",
    "brand_glossary_id": "8c2d5e91a47b4f3c8d1e6a9b2f5c7d40",
    "avatar_id": "YOUR_AVATAR_ID",
    "script": "HeyGen shipped this in 2024.",
    "voice_id": "YOUR_VOICE_ID"
  }'
```

[On Brand](/docs/on-brand) lists every endpoint that accepts the field. On [`POST /v3/video-agents`](/reference/create-video-agent-session) it is set once per session. In a [translation batch](/batch-video-translations) or [video batch](/batch-videos) it is set per item. Scenes with their own `audio_url` or `audio_asset_id` have no synthesis step, so `terms` leaves them unchanged.

An unknown `brand_glossary_id` fails the request with `400` before rendering, so no credits are spent. Glossaries are workspace-scoped: an ID visible in the app is rejected if the API key belongs to another workspace.

## Errors

| Status | Code | Meaning |
| - | - | - |
| `400` | `invalid_parameter` | A field is out of range. `param` names the field. |
| `404` | `resource_not_found` | No glossary with that ID in this workspace. |
| `409` | `conflict` | A glossary with this name already exists, a term is repeated for the same language within one list, or the glossary changed during the update. Read it again and retry. |
| `409` | `request_in_progress` | A request with this `Idempotency-Key` is still running. Retry shortly. |
| `429` | `rate_limit_exceeded` | Retry after `Retry-After`. |
| `503` | `service_unavailable` | Temporary. Retry shortly. |

## Migrating from v1 brand voice

`brand_voice_id` is the deprecated former name of `brand_glossary_id`. It is still accepted on [`POST /v3/templates/{template_id}`](/reference/generate-video-from-template), [`POST /v3/video-translations`](/reference/create-video-translation), and [`POST /v3/video-translations/proofreads`](/reference/create-proofread-session). [`POST /v3/videos`](/reference/create-video) accepts `brand_glossary_id` only.

The legacy `POST /v1/brand_voice/{brand_voice_id}` lists map to the v3 glossary as follows, ahead of the [October 31, 2026 v1/v2 sunset](/endpoint-version-comparison):

| v1 field | v1 shape | v3 field | v3 shape |
| - | - | - | - |
| `vocabulary` | `[["HeyGen", "hey-jen"]]` | `terms` | `[{ "term": "HeyGen", "pronunciation": "hey-jen" }]` |
| `blacklist` | `["HeyGen"]` | `do_not_translate_terms` | `[{ "term": "HeyGen" }]` |
| `whitelist` | `[["CEO", "Geschäftsführer"]]` | `forced_translations` | `[{ "term": "CEO", "translation": "Geschäftsführer" }]` |
| `tones`, `tone` | — | — | Managed in the HeyGen app under **Brand Kit**. |


# Brand Kits
Source: https://heygen-1fa696a7.mintlify.app/docs/brand-kits

Create a brand kit over the API by importing a website's colors, fonts, and logos, then pass its brand_kit_id to Video Agent so every generated video ships on-brand.

<img alt="" />

A brand kit is a saved set of brand colors, fonts, and logos. Pass its `brand_kit_id` to the [Video Agent](/docs/video-agent) and the agent applies it to everything it builds — scene backgrounds, text treatments, chart palettes, logo placement — so output ships on-brand without describing your brand in the prompt.

Author a kit in the HeyGen app under **Brand Kit**, or import one from a public website over the API. Either way you get a `brand_kit_id`, and a kit created over the API stays editable in the app.

A brand kit governs how a video **looks**. To control how your terms are **spoken**, pair it with a [brand glossary](/docs/brand-glossary) — see [On Brand](/docs/on-brand).

<Info>
  **API reference:** [Create Brand Kit](/reference/create-brand-kit) · [Get Brand Kit](/reference/get-brand-kit) · [List Brand Kits](/reference/list-brand-kits) · [Update Brand Kit](/reference/update-brand-kit) · [Delete Brand Kit](/reference/delete-brand-kit) · [Create Session](/reference/create-video-agent-session) · [Send Message](/reference/send-message-or-request-revision)
</Info>

## Import a kit from a website

[`POST /v3/brand-kits`](/reference/create-brand-kit) visits a public URL, imports the logos, colors, and font files it finds, and assembles them into a kit. This is the path to on-brand output for a workspace that has never opened the HeyGen app — onboard a customer by their own domain and generate their first branded video in the same run.

<Note>
  By calling this endpoint you confirm you have the rights and licenses necessary to upload, store, and use the imported assets in HeyGen.
</Note>

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/brand-kits" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{ "url": "https://www.acme.com", "name": "Acme Corp — Primary" }'
```

`201` returns `{ "brand_kit_id": "…", "status": "loading" }` as soon as the record exists, before any asset has been imported. The ID is usable immediately, including on a Video Agent request.

Send an `Idempotency-Key` so a retry is free: a repeat within 24 hours replays the original response instead of importing the same site twice. A retry that arrives while the first is still in flight gets a `409` with `request_in_progress`. The key is matched on its own rather than against the body, so reusing one with a different `url` replays the first kit instead of importing the new site.

## Read a kit and wait for the import

[`GET /v3/brand-kits/{brand_kit_id}`](/reference/get-brand-kit) returns the kit's `colors`, `logos`, and `fonts` alongside the `color_roles`, `logo_roles`, and `font_roles` that say which of them plays which part.

Poll every 2 to 5 seconds until `status` is `completed`, and read the palette only then. A website import usually settles in under two minutes; fonts are typically last to land, so a kit that already has colors and a logo may still be `loading`. Both the collections and the roles are provisional until then.

Two habits keep a kit reader robust once a human starts editing the kit in the app:

* **A role can name a color outside `colors`.** The palette lists the brand's core swatches; a role such as `tertiary` may point at a supporting surface color that isn't one of them. Read `color_roles` for roles and `colors` for the palette rather than deriving one from the other.
* **A role can name an asset that no longer exists.** Deleting a logo or font leaves the role that referenced it in place, so look the `logo_id` or `font_id` up in `logos` or `fonts` and handle the miss.

`status` is `error` when the import failed. The kit still exists and keeps whatever was assembled first, so it remains usable — check the collections to see what made it through, and fill the gaps in the app.

## List your brand kits

[`GET /v3/brand-kits`](/reference/list-brand-kits) returns the kits in the authenticated workspace — the endpoint to reach for when you need the ID of a kit somebody else created in the app. Page with `limit` and `token`; the response carries `data`, `has_more`, and `next_token` at the top level.

The listing is a summary: it carries `logo_url` for the primary logo and the color list, but not fonts or role assignments. Read a kit by ID for those. `logo_url` is `null` when a kit defines colors and fonts but no logo, which is common.

## Correct a kit's roles

Creation assigns roles automatically, with no human in the loop, so [`PATCH /v3/brand-kits/{brand_kit_id}`](/reference/update-brand-kit) is how a caller fixes a slot the importer read differently than you would. It sets the kit's **name** and its **role assignments** — `color_roles` (`primary`, `secondary`, `tertiary`, `accent`), `logo_roles` (`primary`), and `font_roles` (`title_text` and `body_text`, each with a `font_id` and `weight`). The colors, logos, and font files themselves are curated in the HeyGen app.

```bash theme={null}
curl -X PATCH "https://api.heygen.com/v3/brand-kits/3f9a1c47b8e24d5fa0c61e8b7d24f6a1" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "color_roles": { "primary": "#FF5733", "secondary": "#1A1A1A" } }'
```

An omitted field is left unchanged, so send only what you are changing. A role object you do send is **replaced in full rather than merged** — a role left out of it is cleared, which is why the example above clears `tertiary` and `accent` — and `{}` clears a group outright and stays cleared.

<Warning>
  Clearing is `{}`, never `null` — a `null` on any field is rejected. Generated clients serialize with `exclude_none` and drop a `null` before it reaches the wire, so honoring it would clear the role over raw HTTP and silently do nothing through an SDK.
</Warning>

Role edits need an assembled kit and return `409` while `status` is `loading` or `error`. Renaming is allowed at any time, so a kit can be titled the moment its import starts.

## Delete a kit

[`DELETE /v3/brand-kits/{brand_kit_id}`](/reference/delete-brand-kit) removes a kit along with the colors, logos, and fonts it holds, and cannot be undone — the API has no way to restore one. A kit that is still assembling can be deleted at any time.

Videos already generated with the kit keep their branding, since the colors were applied at render time. A Video Agent session still configured with the deleted `brand_kit_id` reports it as invalid on its next use.

## Apply a brand kit to a video

Pass `brand_kit_id` when you create the session. It works in both `generate` and `chat` modes.

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/video-agents" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a 45-second explainer about our Q3 product launch.",
    "brand_kit_id": "3f9a1c47b8e24d5fa0c61e8b7d24f6a1",
    "orientation": "landscape"
  }'
```

In an [interactive session](/docs/interactive-sessions), `brand_kit_id` is also accepted on each follow-up message, so you can re-brand without starting over — useful when producing the same video for several brands or sub-brands.

`brand_kit_id` and `style_id` are independent and compose: a [style](/docs/styles-and-references) picks the look, the brand kit makes that look yours.

## Errors

| Status | Code | Meaning |
| - | - | - |
| `400` | `invalid_parameter` | On an import, the URL could not be read — `"URL is not supported"`. Check that it is a public page reachable without a login. On an update, `"Provide at least one field to update."` means the body arrived empty. |
| `403` | `forbidden` | Your workspace settings do not allow creating brand kits. |
| `403` | `resource_access_denied` | A kit shared into your workspace by another workspace is readable, and the workspace that owns it holds updates and deletion. |
| `404` | `resource_not_found` | No brand kit with that ID in the authenticated workspace. |
| `409` | `request_in_progress` | A request with this `Idempotency-Key` is still running. Retry shortly. |
| `409` | `brand_kit_not_ready` | A role edit reached a kit that is not assembled — `status` is still `loading`, or the import ended in `error`. Renaming is unaffected. |
| `429` | `rate_limit_exceeded` | Retry after the duration in the `Retry-After` header. |

An unknown or inaccessible `brand_kit_id` on a Video Agent request is rejected with `400` `invalid_parameter` when the request is made, rather than failing partway through the render — so a bad ID costs you nothing. Brand kits are workspace-scoped: if you get this with an ID that exists, confirm the API key belongs to the workspace that owns the kit.


# Burst Concurrency
Source: https://heygen-1fa696a7.mintlify.app/docs/burst

Run above your included concurrency on demand. Enterprise workspaces opt in to burst, set an extra cap of up to 50 workflows, and pay 1.5× the contract rate only on the jobs that run above the included slots.

<img alt="" />

<Info>
  Burst is available on **Enterprise** plans. It is enabled per workspace by your account team; [contact sales](https://www.heygen.com/contact-us/sales) to turn it on.
</Info>

Every Enterprise workspace includes a fixed number of concurrent workflow slots (20 by default). Burst lets the workspace run **above** that number when a batch lands, without buying a higher permanent cap. You set one extra cap for the workspace, and it applies to each burst-eligible workflow type separately: with a +30 cap, up to 30 extra avatar renders **and** up to 30 extra video translations can run at the same time. Only the workflows that actually run above the included slots are billed at the burst rate. Burst is shared across the web app and the API.

## Turn on burst

1. Open [Usage](https://app.heygen.com/developers/usage) in the API dashboard. Under **Capacity**, the **Concurrency** tile shows your included slots.
2. Click **Set up burst**, choose the extra cap (**+5 to +50** workflows), and accept the rate notice.
3. Save. The tile now reads `20 + 30` with a **Burst** chip, and **Manage burst** lets you change the cap or turn burst off at any time.

Workspace admins can also see included and burst capacity under **Settings → Usage & History**.

## How burst is billed

| | Included slots | Burst slots |
| :- | :- | :- |
| Rate | Your contract rate | **1.5×** your contract rate |
| Example, Avatar IV | 0.1 credits / sec | 0.15 credits / sec |
| Applies to | All workflows | [Avatar video](/reference/create-video) renders and [video translations](/docs/video-translate), each with its own pool of extra slots |

A workflow takes a slot when it is admitted and holds it until it completes. If every included slot for its type is busy at admission, the workflow runs in a burst slot and its whole render is billed at the burst rate: the duration is billed to the second as usual, then the 1.5× is applied and rounded up to the next whole quota unit. Workflows admitted into an included slot bill at the normal rate even while others are bursting. You only pay the premium for workflows that actually burst.

Burst covers full avatar renders and video translations. Segment renders and free regenerations run in the included slots at the normal rate, and [Video Agent](/docs/video-agent) sessions keep their own concurrency limit.

## See what burst cost you

Every burst workflow is tagged **Burst** in the [Activity tab](https://app.heygen.com/developers/usage?tab=activity), next to its credits. While burst is on, the Usage sidebar shows a **Burst** panel with the premium credits and the number of burst workflows for the selected period.

## API behavior

With burst on, [`POST /v3/videos`](/reference/create-video) and [`POST /v3/video-translations`](/reference/create-video-translation) each accept requests up to *included + extra* concurrent workflows of their own type, so a +30 cap allows up to 50 avatar renders and up to 50 translations at once. Requests beyond that total return `429 Too Many Requests` with a `Retry-After` header, the same as any [concurrency limit](/docs/usage-limits#concurrency-limits). Batch endpoints such as [`POST /v3/videos/batch`](/reference/create-video-batch) queue their items through the same slots.


# Create Avatar
Source: https://heygen-1fa696a7.mintlify.app/docs/create-avatar

The four ways to create a HeyGen avatar over the API: from video footage, from one photo, from a text prompt, or by applying a Look Pack to an avatar you already own.

<img alt="" />

Every avatar you create is a **look** on a **character**. The look id is what you pass as `avatar_id` when you create a video. The character, called an avatar group, is the identity that holds all of that person's looks together. Browse them with [Avatar Groups](/docs/avatars) and [Avatar Looks](/docs/avatar-looks).

## Pick a starting point

| You have | You get | Guide |
| - | - | - |
| Video footage of a person | A digital twin of that person, plus a voice cloned from the same recording | [Video to Avatar](/docs/avatar-from-video) |
| One photo of a person | An avatar from that image, ready in minutes | [Photo to Avatar](/docs/avatar-from-photo) |
| A text description | A synthetic character, no real person depicted | [Prompt to Avatar](/docs/avatar-from-prompt) |
| An avatar you already own | A new outfit, setting, or style for that same character | [Prompt to Avatar](/docs/avatar-from-prompt) or [Look Packs](/docs/avatar-look-packs) |

The first three go through [`POST /v3/avatars`](/reference/create-avatar), distinguished by the `type` field. The fourth generates looks for an existing character: one at a time in your own words through the same endpoint, or a curated set in one call through [`POST /v3/avatars/looks`](/reference/create-avatar-looks).

## What creation returns

`POST /v3/avatars` answers the same shape for all three types: the new look in `avatar_item`, the character it belongs to in `avatar_group`.

```json theme={null}
{
  "data": {
    "avatar_item": {
      "id": "look_abc123",
      "name": "Sarah",
      "avatar_type": "digital_twin",
      "group_id": "group_xyz789",
      "preview_image_url": "https://files.heygen.ai/...",
      "supported_api_engines": ["avatar_iv", "avatar_v"],
      "default_voice_id": "voice_cloned123",
      "status": "processing"
    },
    "avatar_group": {
      "id": "group_xyz789",
      "name": "Sarah",
      "looks_count": 1,
      "default_voice_id": "voice_cloned123",
      "status": "pending_consent",
      "consent_status": "pending",
      "created_at": 1717000000
    }
  }
}
```

Creation is asynchronous, so a new look starts at `status: "processing"`. Poll [`GET /v3/avatars/looks/{look_id}`](/reference/get-avatar-look) until it reports `completed`. For digital twins you can also subscribe to the `instant_avatar.success` and `instant_avatar.fail` [webhook events](/docs/webhook-events), then read the look to confirm its status. Before requesting a specific engine, check the look's `supported_api_engines` against [Models](/models).

The character carries a status of its own, covering consent and moderation rather than training, so `avatar_group.status` and `avatar_item.status` move independently. `avatar_group.status` follows `consent_status`: `pending_consent` while consent is outstanding, `failed` if it was rejected, and `completed` otherwise. A photo or prompt avatar renders as soon as its look reports `completed`. A digital twin renders once the look is `completed` and its group has cleared consent, so wait for both.

## Consent

A [digital twin](/docs/avatar-from-video) generates video once the person depicted has agreed to be cloned, which is what `consent_status` tracks. A group created from a photo or a prompt has no consent step, so it reports `consent_status` of `null`. A photo still shows a real person: you are responsible for having their permission, as [Photo to Avatar](/docs/avatar-from-photo) explains. The field belongs to the group, so a photo or prompt look added to an existing twin's group carries that group's status. [Avatar Consent](/docs/avatar-consent) covers the [`POST /v3/avatars/{group_id}/consent`](/reference/create-avatar-consent) flow and the three levels of access to it.

## One character, many looks

Adding looks to a character you already have keeps one identity across every video: pass `avatar_group_id` when you create, hand an existing look to [a prompt](/docs/avatar-from-prompt), or apply [a Look Pack](/docs/avatar-look-packs). List everything a character owns with [`GET /v3/avatars/looks?group_id=...`](/reference/list-avatar-looks), rename a look with [`PATCH /v3/avatars/looks/{look_id}`](/reference/update-avatar-look), and remove one with [`DELETE`](/reference/delete-avatar-look). Deleting the last look in a character deletes the character with it.

## Delete an avatar

[`DELETE /v3/avatars/{group_id}`](/reference/delete-avatar-group) deletes the character and every look in it. To remove a single look instead, use [`DELETE /v3/avatars/looks/{look_id}`](/reference/delete-avatar-look) as above. Neither can be undone through the API.

Deleting an avatar does not delete the files you created it from, or anything else made with it:

| Resource | Removed with the avatar? | How to remove it |
| - | - | - |
| Training footage, consent video, or photo you supplied | No, each is a separate asset | [`DELETE /v3/assets/{asset_id}`](/reference/delete-asset) |
| Voice cloned from twin footage | No, it stays in your voice library | [`DELETE /v3/voices/{voice_id}`](/reference/delete-a-voice) |
| Videos already generated | No | [`DELETE /v3/videos/{video_id}`](/reference/delete-video) |

A `file` or `consent_video` passed as a `url` or base64 is also saved as an asset in your workspace. To keep the `asset_id` of every source file so you can delete it later, upload with [`POST /v3/assets`](/docs/upload-assets) first and pass `asset_id`. To remove an avatar and everything you supplied for it, delete the avatar group, then each source asset and the cloned voice. Delete source assets only after the look reports `completed` or `failed` and consent has been accepted or rejected.


# Discord
Source: https://heygen-1fa696a7.mintlify.app/docs/discord

Join the HeyGen developer Discord for API help, feature announcements, and community recipes. Talk to the API team and other developers building on HeyGen.

<img alt="" />

<Note>
  Engineers and PMs are active in the community every day.
</Note>

Got a question the docs didn't fully answer? Stuck on an integration? Want to see what others are building? Our [Discord](https://discord.gg/mGKRsCtSC3) is the fastest way to get real help — from the engineers and PMs who build the product, and from developers who've probably hit the same wall you're hitting.

<Card title="Join the HeyGen Discord" icon="discord" href="https://discord.gg/mGKRsCtSC3">
  Ask questions, get direct access to engineers and PMs, and connect with developers building with HeyGen. Free to join, no waitlist.
</Card>

<CardGroup>
  <Card title="Ask questions directly" icon="1">
    No ticket queues. Post in the right channel and get answers from engineers who built the feature — often within hours.
  </Card>

  <Card title="Talk to PMs and engineers" icon="2">
    Share feedback, report rough edges, and request features. PMs actively monitor the community and feed insights back to the team.
  </Card>

  <Card title="Learn from other developers" icon="3">
    Browse what others are building, share your own projects, and find patterns and workarounds not in the docs yet.
  </Card>
</CardGroup>

| Channel | What it's for |
| :- | :- |
| `#general` | General questions about the API and docs |
| `#heygen-api` | Questions, integrations, and troubleshooting for the HeyGen API |
| `#hyperframes` | Showcase and discuss HyperFrames projects |
| `#heygen-cli-and-mcp` | Support and discussions for the HeyGen CLI and MCP tools |
| `#hackathon` | project ideas, submissions, and hackathon updates |
| `#announcements` | Release notes and major updates |

<br />


# Edit Scenes
Source: https://heygen-1fa696a7.mintlify.app/docs/edit-scenes

Revise two scenes of a Video Agent video without touching the rest. Read the scene list, send an edit_plan with one instruction per scene, and poll the new draft.

<img alt="" />

<Info>
  **API reference:** [Get Video Scenes](/reference/get-video-scenes) · [Send Message or Request Revision](/reference/send-message-or-request-revision) · [Get Video](/reference/get-video) · [List Session Videos](/reference/list-session-videos)
</Info>

A scene edit changes only the scenes you name. Everything else in the video keeps its script, visuals, and pacing, so a small fix stays small: one call, a few minutes of rendering, and no re-prompting of the whole video. It works on any Video Agent session, whether you created it with `"mode": "generate"` or `"mode": "chat"` (see [Interactive Sessions](/docs/interactive-sessions)).

<div>
  <Frame>
    <video>
      <source type="video/mp4" />
    </video>
  </Frame>

  <Frame>
    <video>
      <source type="video/mp4" />
    </video>
  </Frame>
</div>

## Three calls

<Steps>
  <Step title="Read the scenes">
    [`GET /v3/videos/{video_id}/scenes`](/reference/get-video-scenes) on a completed video from the session. The response lists every scene in order with its `id`, `script`, `background`, and `elements`, plus one `edit_version` for the whole document. Wait for the video to reach `completed` first: while it is still rendering this call returns `409 resource_not_ready`.
  </Step>

  <Step title="Send the edit plan">
    [`POST /v3/video-agents/{session_id}`](/reference/send-message-or-request-revision) with an `edit_plan` array. Each item names one `scene_id`, the change in plain language, the `scene_snapshot_video_id` you read the scene from, and that snapshot's `edit_version`. No `message` is needed. The response carries the `video_id` of the new working draft.
  </Step>

  <Step title="Poll the draft">
    [`GET /v3/videos/{video_id}`](/reference/get-video) with the returned `video_id` until `status` is `completed`. The session's own `video_id` stays `null` while the edit runs, so poll the draft directly. [`GET /v3/video-agents/{session_id}/videos`](/reference/list-session-videos) lists every cut the session has produced.
  </Step>
</Steps>

## Example

The plan below produced the "after" video above. Two items, two scenes, one request.

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/video-agents/$SESSION_ID" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "edit_plan": [
      {
        "scene_id": "ff943f68-159d-463b-84ac-b784a61c8bca",
        "text": "Change the on-screen headline to Evening mode and make the background a much darker, warmer night-time room with a single lit lamp. Keep the narration the same.",
        "scene_snapshot_video_id": "7c852479652e4e09b2cc6b12382b31f6",
        "edit_version": "e6eb1e63074cbfc694e4e6b64d3dc1b9cc004da54074d073631baaa825ce0e53"
      },
      {
        "scene_id": "e89c22a1-7619-4f26-bdb5-c5ec5555da4e",
        "text": "Replace the closing line with: Lumen. Light that knows you. Available now. Drop the pre-order URL from narration and on-screen text.",
        "scene_snapshot_video_id": "7c852479652e4e09b2cc6b12382b31f6",
        "edit_version": "e6eb1e63074cbfc694e4e6b64d3dc1b9cc004da54074d073631baaa825ce0e53"
      }
    ]
  }'
```

```json Response theme={null}
{
  "data": {
    "session_id": "6cbd1fbc886b434a920acfed05fa931b",
    "run_id": "c3817fcd60b543da8480b6bc7d03026f",
    "title": "Lumen Explainer Video",
    "video_id": "1af65ebabfdc48ed84fc2f4ec2abd20f"
  }
}
```

With the [CLI](/cli), the same turn is `heygen video scenes get <video_id>` followed by `heygen video-agent send <session_id> -d edit_plan.json`.

## What to expect

| Situation | What happens |
| - | - |
| Narration | Say "keep the narration" and the scene keeps its script while the visuals change. Give new copy and both change. |
| Untouched scenes | Same script and visuals as before. The new draft is a new document, so scene and element ids are reissued; compare by content, not by id. |
| Several edits in a row | Each accepted turn returns the current working draft in `video_id`. Read that draft's scenes for the next `edit_version`. |
| `edit_version` no longer current | `409 stale_edit_version`. Read the scenes again and resend with the new version. |
| A `scene_id` outside the snapshot | `400 invalid_parameter`. The whole plan is rejected before anything is submitted, so a typo never produces a half-applied edit. |
| Reading scenes | A heavy read with a lower rate limit than `GET /v3/videos/{video_id}`. Poll the video for status and read scenes once it completes. |
| Plan size | Up to 50 items per request, each up to 10,000 characters. Items may point at different snapshots from the same session, including earlier videos. |

## Edit with an agent

Ask a coding agent to make the change for you: it reads the scenes, picks the ones that match your description, and sends the plan.

```text Prompt for your agent wrap theme={null}
Read https://developers.heygen.com/docs/edit-scenes.md and https://developers.heygen.com/docs/for-ai-agents.md first. My HeyGen API key is in the HEYGEN_API_KEY environment variable; never ask me to paste it. Video Agent session <SESSION_ID> has a completed video <VIDEO_ID>. Call GET /v3/videos/<VIDEO_ID>/scenes, show me each scene's script in one line, and ask me which scenes to change and how. Then send one POST /v3/video-agents/<SESSION_ID> with an edit_plan covering only those scenes, using the scene ids and edit_version you read. Poll the returned video_id until completed and give me the video URL.
```


# Error Codes
Source: https://heygen-1fa696a7.mintlify.app/docs/error-codes

Error codes, HTTP status codes, and troubleshooting for the HeyGen API

HeyGen uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate an error with the information provided (e.g., a missing parameter, insufficient credits, or a resource not found). Codes in the `5xx` range indicate an error on HeyGen's servers.

Every error response includes a machine-readable `code`, a human-readable `message`, a `doc_url` linking to the relevant section below, and a `request_id`. Some errors that relate to a specific request field also include a `param` attribute.

The `request_id` is also returned in the `X-HeyGen-Request-Id` response header, including on errors that have no JSON body. Include it when contacting support. The text-to-speech and speech-to-speech endpoints under `/v3/models/audio/` are served separately and do not include it.

## Error response format

```json theme={null}
{
  "error": {
    "code": "insufficient_credit",
    "message": "Your account has 5 credits but this video requires 10 credits.",
    "doc_url": "https://developers.heygen.com/docs/error-codes#insufficient-credit",
    "request_id": "8c4f0b9e1d2a4f6b9e3c7a1d5f2b8e40"
  }
}
```

| Attribute | Type | Description |
| - | - | - |
| `code` | string | A short, machine-readable identifier for the error. See the full list below. |
| `message` | string | A human-readable description of what went wrong and, where possible, how to fix it. |
| `param` | string | The request field that caused the error. Only present for validation errors. |
| `doc_url` | string | A link to the documentation for this specific error code. |
| `request_id` | string | The identifier of this request, the same value as the `X-HeyGen-Request-Id` response header. Include it when contacting support. |

## HTTP status code summary

| Status | Meaning |
| - | - |
| `200 OK` | Everything worked as expected. |
| `400 Bad Request` | The request was malformed or contained invalid parameters. |
| `401 Unauthorized` | No valid API key was provided. |
| `402 Payment Required` | The request requires additional credits or a plan upgrade. |
| `403 Forbidden` | The API key doesn't have permission to perform the request. |
| `404 Not Found` | The requested resource doesn't exist. |
| `429 Too Many Requests` | Too many requests hit the API too quickly, or a usage quota was exceeded. |
| `500 Internal Server Error` | Something went wrong on HeyGen's end. |

***

## Error codes

### `unauthorized`

**HTTP status:** `401`

The API key provided is invalid, expired, or missing. Verify that you are sending your API key in the `X-Api-Key` header and that the key is active in your [HeyGen account settings](https://app.heygen.com/settings).

### `api_key_owner_workspace_access_revoked`

**HTTP status:** `401`

The API key's owner no longer has active access to the workspace the key belongs to, or that workspace was deleted. For an active workspace, ask its admin to restore the owner's membership. For a deleted workspace (including a personal workspace), use a key for an active workspace. Restoring active membership in an active workspace lets the same key work again; retrying or refreshing the credential without restoring access will not help.

### `forbidden`

**HTTP status:** `403`

The request is authenticated but cannot use the current workspace or action. This can happen when the workspace session expires or the caller lacks access. Reauthenticate if the session expired; otherwise use a workspace or role with the required access.

It is also returned when a voice provider rejects the API key of a voice provider account you connected, because the key is invalid or the account is inactive. Update the API key in your settings.

### `insufficient_api_key_scope`

**HTTP status:** `403`

The API key is valid but its permission scopes don't cover this endpoint. Restricted API keys are only authorized for the resources and access levels (read/write) explicitly granted when the key was created. Check the key's configured scopes in your [HeyGen account settings](https://app.heygen.com/settings), or use a key with broader access. The `message` names the scopes the endpoint requires, so it can be compared against the key's grants directly.

### `api_key_required`

**HTTP status:** `403`

The request was made with an OAuth token whose client can't pay for this endpoint. Either the endpoint charges only API credits, which only a HeyGen API key can spend, or the client has no wallet it can pay from. Send the request with a HeyGen API key in the `X-Api-Key` header. A request that carries both a key and a token is treated as the key. Nothing was created or charged.

### `resource_access_denied`

**HTTP status:** `403`

The authenticated user does not have access to the specific resource referenced in the request. The resource may belong to a different user or organization. Verify that the resource ID is correct and belongs to your account.

### `encryption_setup_pending`

**HTTP status:** `409`

The workspace was created with a customer-managed encryption key (BYOK) and that key has not yet been registered, validated and activated. Until it is, the workspace refuses every media write — uploads, generation, renders — so that nothing it ever holds is outside the customer's key. A workspace administrator completes the setup from Settings → Workspace Controls → Encryption, or HeyGen completes it on the customer's behalf.

### `encryption_disabled`

**HTTP status:** `403`

The workspace's customer-managed encryption cannot be used for this request: it has been stood down, or the workspace is marked for customer-managed encryption and its key record cannot be resolved. Either way the media write is refused rather than falling back to a HeyGen-managed key.

Standing it down is deliberate and one-way, and it leaves the workspace unable to store media: its existing objects are under a key it would no longer use, and moving them out is a separate migration that does not exist yet. So this is not a way to return a workspace to ordinary shared storage — a customer who wants customer-managed encryption again is provisioned a new workspace, and support should treat a workspace in this state as one that needs a decision rather than a retry.

This is also not the error for a key the customer has disabled in their own AWS account. That needs no change on this side: the operation fails because AWS refuses it, and uploads and playback resume on their own once the key is usable again.

### `encryption_cross_tree_transfer`

**HTTP status:** `409`

Content cannot be moved or copied between a BYOK space and any other workspace, in either direction. Moves re-point database rows at the same stored object rather than copying bytes, so a cross-BYOK move would leave media outside the customer's key, or put another customer's media under it. Moves within one BYOK space are unaffected.

### `invalid_encryption_key`

**HTTP status:** `400`

The supplied KMS key reference was rejected. It must be a full key ARN (not an alias or bare key id, which would resolve inside HeyGen's account rather than the customer's), for a symmetric `ENCRYPT_DECRYPT` key in `us-east-2`.

### `encryption_setup_failed`

**HTTP status:** `409`

Provisioning the workspace's encrypted bucket, or the validation round trip against it, did not complete. The key itself may be fine: this is the bucket refusing to be configured, an AWS error during setup, or a check in the validation report coming back red. The response carries the per-step or per-check report; act on the first failed entry. Nothing was activated. A provisioning failure during key registration means the key was not recorded; during activation the key stays recorded and the BYOK space stays `awaiting_key`.

### `encryption_temporarily_unavailable`

**HTTP status:** `503`

The service could not tell whether this workspace's media must be stored under a customer-managed key, so the media was not stored. Nothing is wrong with the workspace or its key: the record that answers the question could not be read. Retry with backoff.

### `ai_vendor_access_restricted`

**HTTP status:** `403`

The workspace has restricted which AI vendor companies may be used. The action or model you requested relies on a vendor that is not allowed under the workspace’s AI vendor access policy. Ask a workspace administrator to update the policy if this vendor should be permitted.

### `brand_kit_locked`

**HTTP status:** `403`

The workspace's brand policy is locked (an enterprise governance setting): only the workspace default brand kit may be applied, and the request named a different `brand_kit_id`. Pass the default brand kit id (included in the error message) or omit `brand_kit_id` entirely — the workspace default is applied automatically. Ask a workspace administrator to pin a different default or unlock the brand policy if another kit is needed.

### `voice_not_usable`

**HTTP status:** `403`

The voice referenced in the request cannot currently be used to generate this video. The voice is in a state that blocks generation and will not resolve on retry. Select a different voice.

This code is also returned when the upstream voice provider restricts the voice: it is only offered on a higher tier of the provider's own plan, or the provider has suspended access to it. Upgrading your HeyGen plan does not change this. If you connected your own voice provider account, the error message names the provider tier the voice requires; otherwise, choose a different voice.

It is also returned when the voice provider has the voice but will not generate speech with it, for example because the voice is disabled, needs verification, has not been fine-tuned or has invalid samples at the provider, or because the provider returned no audio, which usually means the voice does not support the language of the text. Choose a different voice. If the voice is in your own connected ElevenLabs account, the error message says how to fix a disabled, unverified or not fine-tuned voice in that account: enable, verify or regenerate it.

### `phone_verification_required`

**HTTP status:** `403`

The account associated with this request must complete phone (SMS) verification before this request can proceed. This is an anti-abuse safeguard that can apply to any generation feature (video, voice, avatar, and related operations). This also applies during API-key authentication, including requests that do not consume credits. Sign in to HeyGen and complete phone verification, then retry the request.

Older HeyGen app endpoints may return the numeric code `400193` for the same requirement.

### `rate_limit_exceeded`

**HTTP status:** `429`

You are sending requests too frequently. Back off and retry with exponential backoff. Check the `Retry-After` response header for the number of seconds to wait before retrying. See [Usage Limits](/docs/usage-limits#concurrency-limits) for concurrency and per-endpoint limits; Enterprise workspaces can raise effective concurrency with [burst](/docs/burst).

This code is also returned when the upstream voice provider throttles a speech or voice request. That response carries no `Retry-After` header; back off and retry with exponential backoff.

### `api_endpoint_disabled`

**HTTP status:** `403`

This endpoint is not available for your account. Contact support.

### `quota_exceeded`

**HTTP status:** `429`

You have exceeded a usage quota (e.g., the free-tier limit for video agent or AI clip requests). Upgrade your plan or wait for your quota to reset. Check your current usage in the [HeyGen dashboard](https://app.heygen.com).

### `insufficient_credit`

**HTTP status:** `402`

Your account does not have enough credits to complete this request. The error message includes how many credits you have and how many are required. Purchase additional credits or reduce the scope of your request (e.g., shorter video duration, fewer scenes).

### `usage_limit_reached`

**HTTP status:** `402`

The member reached a workspace usage limit. Ask a workspace administrator to check the limit, or wait for the limit to reset. Buying more credits does not remove this limit.

### `trial_limit_exceeded`

**HTTP status:** `402`

You have reached the video generation limit for trial accounts. Upgrade to a paid plan to continue creating videos.

### `subscription_required`

**HTTP status:** `402`

You have used all the credits included in your pay-as-you-go trial, and further top-ups are not available on your account. Choose a plan to continue making API requests — see [pricing](https://www.heygen.com/pricing).

This is distinct from `insufficient_credit`: buying more credits will not resolve it, because purchases are no longer available. Subscribing to a plan is the only action that restores API access.

### `hf_subscription_required`

**HTTP status:** `402`

HyperFrames Desktop asked to pay with the workspace's HyperFrames plan, and the workspace has no HyperFrames plan or usage. Choose a HyperFrames plan in HyperFrames Desktop, or send the request with a HeyGen API key in the `X-Api-Key` header. Nothing was created or charged.

### `hf_usage_exhausted`

**HTTP status:** `402`

HyperFrames Desktop asked to pay with the workspace's HyperFrames plan, and the plan's usage left does not cover this request. Wait for the plan to renew, change the plan in HyperFrames Desktop, or send the request with a HeyGen API key in the `X-Api-Key` header. Nothing was created or charged.

### `plan_upgrade_required`

**HTTP status:** `402`

The requested feature or resource requires a higher subscription tier than your current plan. This can occur when:

* Using a premium avatar that is not available on your plan.
* Accessing an integration that requires a higher tier.
* Requesting a resolution or feature gated by plan level.

A higher plan is required to access this feature. Learn more about the available plans on [HeyGen](https://www.heygen.com).

### `resolution_not_allowed`

**HTTP status:** `400`

The requested video resolution exceeds the resolution available on your current plan. Avatar, image, and studio OAuth video creation check this before accepting the generation request. When resolution is omitted, avatar and image videos use 720p, while studio uses 1080p.

Choose a lower resolution or a plan that supports the requested resolution. [Continue on HeyGen](https://www.heygen.com) to learn more. Retrying the same request will not resolve the restriction. API-key video creation retains its existing resolution access.

### `video_not_found`

**HTTP status:** `404`

No video, draft, or video translation was found matching the provided ID. Verify that:

* The `video_id` is correct and was not mistyped.
* The video has not been deleted.
* The video belongs to your account.

### `avatar_not_found`

**HTTP status:** `404`

No avatar was found matching the provided ID. This applies to all avatar types — standard avatars, photo avatars (photars), instant avatars, and avatar kits. Verify that:

* The `avatar_id` is correct.
* The avatar has finished training (if recently created).
* The avatar belongs to your account or is a public avatar.

### `voice_not_found`

**HTTP status:** `404`

No voice was found matching the provided ID. Verify that the `voice_id` is correct and that the voice is available in your account. If using a cloned voice, ensure it has finished processing.

### `template_not_found`

**HTTP status:** `404`

No template was found matching the provided ID. Verify that the `template_id` is correct and that the template is shared with your account or is publicly available.

### `asset_not_found`

**HTTP status:** `404`

No asset was found matching the provided ID. Assets may have been deleted or may not have finished uploading. Verify that the `asset_id` was returned from a successful [`POST /v3/assets`](/reference/upload-asset) call and that the asset has not been removed.

### `webhook_not_found`

**HTTP status:** `404`

No webhook endpoint was found matching the provided ID. Verify that the `endpoint_id` is correct and that the webhook has not been deleted. List your existing webhooks with `GET /v3/webhooks/endpoints` to find valid endpoint IDs.

### `batch_not_found`

**HTTP status:** `404`

No batch was found matching the provided ID. Verify that the `batch_id` is correct and that the batch belongs to your account.

### `resource_not_found`

**HTTP status:** `404`

The requested resource was not found. This is a generic not-found error for resources that do not have a more specific error code (e.g., streaming sessions, audio records). Verify that the resource ID is correct and belongs to your account.

It is also returned when a voice from a voice provider account you connected no longer exists in that account. Restore or re-import the voice in that account, or choose a different voice.

### `voice_not_cloneable`

**HTTP status:** `400`

The selected voice is provider-owned and cannot be cloned, duplicated, improved, or changed to a different provider. Use the voice with one of its listed `allowed_engines`, or choose a cloneable voice for mutation operations.

### `invalid_parameter`

**HTTP status:** `400`

One or more request parameters are invalid, missing, or in the wrong format. The `message` field describes which parameter failed validation and why. The `param` field, when present, identifies the specific field.

Common causes:

* A required field is missing from the request body.
* A field value is the wrong type (e.g., string instead of number).
* A field value is outside the allowed range or not in the set of accepted values.
* The request body is not valid JSON or is not a JSON object.

### `graph_invalid`

**HTTP status:** `422`

The workflow product graph is structurally well-formed JSON but semantically invalid, so it cannot be saved as submitted or compiled into a version. Distinct from `invalid_parameter` (400), which means the request body itself is malformed; a `graph_invalid` response means the graph parsed but violates the workflow contract.

The `errors[]` array lists every problem found in one pass — validation never stops at the first issue. Each entry carries a stable `code` (for example `unknown_node_type`, `node_type_unavailable`, `invalid_config`, `dangling_dependency`, `cycle_detected`), a human-readable `message`, and where applicable the offending `node_id`, `port`, and `path` (a field path such as `config.prompt` or `outputs.result`). Fix every listed issue and resubmit; use `GET /v3/workflows/node-types` to discover the node types and config schemas available for authoring.

### `conflict`

**HTTP status:** `409`

The request conflicts with existing state. For example, attempting to create a webhook endpoint with a URL that is already registered for your account, or creating a brand glossary whose name another glossary in your workspace already uses (names are compared without regard to case). On brand glossary writes this also covers a `term` that appears more than once within any one of the `terms`, `do_not_translate_terms`, or `forced_translations` lists in the request body (terms are compared without regard to case). Use a different value or delete the existing resource first.

A brand glossary update can also conflict with a concurrent edit. The update is rolled back; fetch the latest glossary, reapply your changes and retry.

On the workflow authoring endpoints this also covers `Idempotency-Key` reuse: sending a key that was already used with a different request body or target returns this code instead of replaying the original response. Send a new key for a new request.

### `brand_kit_not_ready`

**HTTP status:** `409`

The brand kit is still being assembled, or its import failed, so its role assignments cannot be edited yet. A brand kit imported from a website gathers its colors, logos and fonts in the background; until `status` is `completed` the assets a role would name may not exist. Poll `GET /v3/brand-kits/{brand_kit_id}` until `status` is `completed`, then retry. Renaming a kit is allowed at any time and never returns this.

### `voice_not_ready`

**HTTP status:** `409`

The professional voice clone (PVC) is still training and cannot serve inference yet. Training normally completes within minutes; retry the stream request after a short delay.

### `voice_training_failed`

**HTTP status:** `409`

Training for this professional voice clone (PVC) ended in a terminal failure, so the voice cannot serve inference. Retrying the stream request will not succeed; contact support to retrain or replace the voice.

### `stale_workflow_draft`

**HTTP status:** `409`

Returned by `PATCH /v3/workflows/{workflow_id}` when the workflow draft moved before your write landed: the `expected_revision` you sent no longer matches. Nothing was written. Re-read the workflow to pick up the current `draft_revision` and reapply your change; retrying the same request unchanged will keep failing. Publishing (`POST .../versions`) no longer surfaces this code — its graph rides the request body, so a concurrent draft edit cannot invalidate it.

### `workflow_archived`

**HTTP status:** `409`

The workflow definition is archived, so it cannot be published or modified. This is terminal for that definition — retrying will not help. Create a new workflow instead.

### `template_update_in_progress`

**HTTP status:** `409`

Another write to this template is still being applied. Writes to one template, from the API or from the HeyGen editor, are serialized so two of them cannot interleave. The template row is only written by the writer that holds the lock; the editor keeps its lock alive while it stores element metadata, and a save that lost the lock is refused before it writes the row. Wait a moment and retry; if you use `expected_edit_version`, re-read the template first.

### `workflow_run_admission_refused`

**HTTP status:** `409`

The workflow run was created, but its coordinator workflow was authoritatively refused by workflow scheduling — its inputs failed scheduling validation. This is terminal for the run: retrying the same request will not help. Check the run's status for details, or contact [HeyGen support](https://help.heygen.com) with the run id.

### `resource_not_ready`

**HTTP status:** `409`

The requested resource exists but is not yet in a ready state. This can occur when a video translation is still processing, an instant avatar has not finished training, or an existing reference image does not yet have its stored object. Poll the resource or asset status and retry once it reaches a ready state. Also returned when the uploaded object is not yet present in storage (e.g. `POST /v3/assets/{asset_id}/complete` called before the upload PUT landed), or while `/complete` is still checking the uploaded file, which it waits on for a few seconds before answering; safe to retry. Missing or deleted reference images return `asset_not_found` instead.

### `image_processing_failed`

**HTTP status:** `422`

The referenced image exists but its processing has permanently ended without producing a usable result (for example, image processing failed, or it completed without generating a thumbnail), so the requested operation cannot be performed. Unlike `resource_not_ready`, this is terminal — retrying or polling will not change the outcome. Upload a new image and retry with it.

### `artifact_unavailable`

**HTTP status:** `409`

The requested artifact exists but permanently failed to resolve to a durable storage location, so no download URL can be issued. Unlike `resource_not_ready`, this is terminal — retrying or polling will not change the outcome. Inspect the artifact's `failure` field for the reason.

### `context_limit_exceeded`

**HTTP status:** `409`

The Video Agent session's conversation has grown too long for the agent to continue, so the message was not sent. This is terminal for the session: retrying, shortening the message or waiting will not help. `GET /v3/video-agents/{session_id}` reports the same condition as an `error` with this code. Start a new session with `POST /v3/video-agents` and carry over the brief and any assets you still need; videos the session already produced stay available.

### `stale_edit_version`

**HTTP status:** `409`

The Video Agent draft changed after the caller read its scenes, so the supplied `edit_version` no longer identifies the current scene graph. No edit was submitted. Fetch `GET /v3/videos/{video_id}/scenes` again, choose scene IDs from that response, and retry with its new `edit_version`.

On `PUT /v3/templates/{template_id}/variables`, the `expected_edit_version` you sent does not match the template's current `edit_version`, so something changed the template after you last read it. Every write changes it, whether from another API client or from a save in the HeyGen editor, and the write itself is refused if the template moved between your read and your write. Re-read the template with `GET /v3/templates/{template_id}`, rebuild your variable set from the current state, and send it again with the new `edit_version`.

### `request_in_progress`

**HTTP status:** `409`

A prior request with this `Idempotency-Key` is still in progress. Wait for the original request to complete and retry. Once the original request finishes, subsequent retries with the same key within 24 hours replay the original response.

### `content_policy_violation`

**HTTP status:** `400`

The request was rejected for violating HeyGen's content policy. This can occur when an instant avatar does not pass the moderation review, when submitted content contains inappropriate content, or when an uploaded image/video asset that was flagged by moderation is used in a request. Create a new resource (or upload a new asset) that complies with our [usage policy](https://www.heygen.com/policy).

For `POST /v3/models/videos`, an explicit prompt moderation rejection stops captioning and video generation when enforcement is enabled. Revise the prompt before retrying. With enforcement disabled, violations are recorded and generation proceeds. Moderation errors and timeouts currently allow generation to proceed in either mode.

This code is also returned as a look's `error.code` (with `status: failed`) when a look generated from a prompt fails because the image provider's content safety check refused the prompt. Retrying the same prompt fails the same way, so change the prompt. No credits are used for the refused generation.

It is also returned when the voice provider refuses a speech request under its own content policy, either for the text or for the selected voice. Retrying the same request fails the same way, so change the text or choose a different voice.

### `avatar_not_usable`

**HTTP status:** `400`

The requested avatar cannot be used because it did not pass content moderation or its creation failed. Select a different avatar; the error message identifies which condition occurred.

### `unlimited_mode_disabled`

**HTTP status:** `400`

The avatar does not support unlimited mode. Use a different avatar, or use Avatar IV or Avatar V.

### `scenes_unavailable`

**HTTP status:** `400`

This video's scenes cannot be returned. Not every video has a scene representation, and there is no fix on the caller's side — re-create the video through the API if you need its scenes.

### `video_not_editable`

**HTTP status:** `400`

This video cannot be edited through the API. It belongs to a Video Agent session, it is interactive or branching, it is a type the API cannot edit yet, or it uses avatars the workspace can no longer use or voices that no longer exist. The message names the reason, and an alternative where there is one. Nothing was changed.

### `edit_not_supported`

**HTTP status:** `400`

The request changes a field or uses an action that cannot be edited through the API yet. `param` names the part of the request at fault. Remove it and send the rest. Nothing was changed.

### `template_source_unsupported`

**HTTP status:** `400`

The video passed to `POST /v3/templates` cannot become a template. Either it has no editable draft in the current editor format (videos rendered before the current editor, or whose draft was never saved), or it was produced by a flow that does not keep an editable draft, such as URL to Video. Create the template from a video generated with `POST /v3/videos` or saved in the HeyGen editor. For an older editor video, open it in the editor and save it again, then retry.

### `variable_match_not_found`

**HTTP status:** `400`

A text variable in `PUT /v3/templates/{template_id}/variables` was declared with `match`, but that exact text does not occur in the template's script or on-screen text (or not in the `element_ids` you limited it to). Check the current text in `GET /v3/templates/{template_id}` under `elements[].current.text`; matching is literal and case-sensitive. If the template already contains `{{name}}` placeholders for this variable, declare it without `match`.

### `variable_match_spans_styles`

**HTTP status:** `400`

The `match` text for a text variable occurs in a rich-text element only across differently styled runs (for example, half bold and half regular), so a single placeholder cannot replace it without losing styling. Shorten `match` to text inside one styled run, or make the styling uniform in the HeyGen editor and retry.

### `avatar_consent_required`

**HTTP status:** `400`

The avatar group used in the request requires consent before it can be used to generate a video (its instant-avatar consent was skipped, rejected, or never completed). Complete the consent flow for the avatar group (e.g. `POST /v3/avatars/{group_id}/consent`), then retry the request.

### `avatar_expired`

**HTTP status:** `400`

The digital twin used in the request has expired because the workspace exceeded its avatar slot limit — typically after an avatar-slot add-on lapsed or the plan was downgraded. Existing videos are unaffected, but the expired digital twin cannot be used to generate new videos. Renew or purchase avatar slots, or delete other digital twins to bring the workspace back within its limit; the digital twin becomes usable again immediately.

### `voice_expired`

**HTTP status:** `400`

The professional voice clone used in the request has expired because the workspace exceeded its professional voice clone slot limit — typically after a voice clone add-on lapsed or its quantity was reduced. The voice and its data are untouched, but it cannot be used to generate new speech. Purchase more professional voice clone slots, or delete other professional voice clones to bring the workspace back within its limit; the voice becomes usable again immediately.

### `resource_limit_reached`

**HTTP status:** `400`

You have reached the maximum number of a resource allowed for your account (e.g., voice clone slots, instant avatar redo attempts, verified avatar group slots). Delete unused resources to free up capacity, wait for limits to reset, or contact [HeyGen support](https://help.heygen.com) to request a higher limit.

Also returned when an account reaches the number of voice clones its plan includes. Every plan has a number; higher plans include more. The web and API clone pools are shared, so a clone created on either surface counts toward the same allowance, and voices created as part of avatar creation do not count against a paid plan's allowance. Deleting a clone frees a slot; upgrading raises the limit where a higher plan exists.

### `template_limit_reached`

**HTTP status:** `400`

The workspace already holds the maximum number of templates (2000), so `POST /v3/templates` cannot create another one. Delete templates you no longer need with the HeyGen editor's template library and retry. The limit is per workspace and shared with templates created in the web app.

### `role_not_allowed`

**HTTP status:** `400`

The requested space member role is no longer available and cannot be assigned. The viewer role has been retired; assign a different role (for example creator) instead. Distinct from `invalid_parameter`, which means the request was malformed — here the request is well-formed but names a role the workspace no longer offers.

### `voice_unavailable`

**HTTP status:** `400`

The requested voice exists but is not in a usable state. This occurs when a cloned voice failed processing, expired, or was canceled. Delete the voice and create a new voice clone, or use a different voice.

### `voice_settings_not_supported`

**HTTP status:** `400`

The voice is valid, but the requested voice-and-engine combination cannot be honored. Unlike `voice_unavailable` (the voice itself is in a broken state) and `invalid_parameter` (the request was malformed), the request is well-formed but this voice cannot run under the selected engine or configuration. Common causes:

* The selected engine needs a source clip for the voice and none could be prepared.
* A third-party (bring-your-own-key) voice was requested on an engine that only runs on HeyGen's house account.
* The engine configuration mapping for the voice is missing and cannot be recreated.

Some cases are transient rather than configuration problems: the voice's source clip may still be being prepared, or a newly created voice may still be propagating at the provider. In those cases, a later attempt with the same voice and engine may succeed. Allow a few seconds between retries for source preparation, or up to a minute between retries for provider propagation. The `message` field does not currently distinguish a transient source-clip failure from a permanent one. If the error persists after a few spaced retries, try a different engine or voice, or contact support.

### `script_too_short`

**HTTP status:** `400`

The script provided is too short to generate a video. HeyGen requires the text-to-speech audio to be at least 1.0 second long. Very short scripts (a single word, a period, or a few characters) will not produce enough audio. Add more content to your script and retry the request.

### `tts_text_invalid`

**HTTP status:** `400`

The text provided for text-to-speech conversion is invalid or cannot produce speech. Check that the script is not empty and contains speakable words or valid pauses, then retry.

### `video_too_long`

**HTTP status:** `400`

The input video exceeds the maximum supported duration for this endpoint (for example, filler word removal supports sources up to 2 hours). The error message includes the probed duration and the limit. Trim or split the video and retry.

### `no_audio_track`

**HTTP status:** `400`

The input video has no audio track. Speech-based processing (such as filler word removal) needs speech audio to transcribe. Provide a video that contains an audio stream.

### `download_failed`

**HTTP status:** `400`

A URL provided in your request could not be downloaded. This applies to video URLs, image URLs, audio URLs, and any other user-supplied resource link. Common causes:

* The URL is not publicly accessible (authentication required, private video, restricted sharing settings).
* The URL is malformed or points to a page rather than a direct file.
* The remote server refused the connection or returned an error.
* For Google Drive links, the file must be shared with "Anyone with the link" access.
* For YouTube/Vimeo, the video must be public (unlisted or private videos are not supported).

When the failing URL is one you supplied and could be safely re-rendered, the `message` field names it, without any query parameters. Otherwise — the failure involves one of HeyGen's own internal resources, or your URL could not be parsed — `message` is the fixed string `Failed to download a required asset`. If you supplied the URL, check it first; if it recurs on a URL you've confirmed is valid and reachable, contact support and quote that message.

### `youtube_video_download_forbidden`

**HTTP status:** `400`

A YouTube URL you provided points to a video that cannot be downloaded because YouTube itself forbids it. Unlike `download_failed`, this is not a connectivity or parsing problem — the video is reachable but not permitted for download. Common causes:

* The video is members-only, age-restricted, or otherwise gated behind a YouTube sign-in.
* The URL points to a live stream, a premiere, or an upcoming event rather than a finished video.
* The video is region-locked or blocked in the region HeyGen downloads from.

Supply a different, publicly downloadable YouTube video. Check the `message` field for the specific reason.

### `batch_too_large`

**HTTP status:** `400`

The batch request contains more items than the maximum allowed. Split the request into smaller batches and retry.

### `batch_item_invalid`

**HTTP status:** `400`

One or more items in the batch request failed validation. Check the `message` field for details about which item failed and why, correct the payload, and retry.

### `too_many_ids`

**HTTP status:** `400`

The request specified more IDs than the maximum allowed in a single call. Reduce the number of IDs and split the request across multiple calls.

### `video_delete_failed`

**HTTP status:** `500`

The video could not be deleted due to an internal error. Retry the request. If the error persists, contact [HeyGen support](https://help.heygen.com) with the `video_id`.

### `internal_error`

**HTTP status:** `500`

An unexpected error occurred on HeyGen's servers. This is not caused by your request. If the error persists, contact [HeyGen support](https://help.heygen.com) and include the full error response for faster debugging.

### `voice_provider_error`

**HTTP status:** `502`

An upstream voice provider that HeyGen relies on (for text-to-speech, voice cloning, or voice design) failed or closed the connection unexpectedly. This is not caused by your request. Retry after a short delay. If the error persists, contact [HeyGen support](https://help.heygen.com) and include the full error response for faster debugging.

### `bad_gateway`

**HTTP status:** `502`

The LiveAvatar API behind `/v3/live-avatar/*` could not be reached: the connection was refused, reset, or could not be established in time. This is not caused by your request. Retry after a short delay. If the error persists, contact [HeyGen support](https://help.heygen.com) and include the full error response for faster debugging.

### `not_implemented`

**HTTP status:** `501`

The requested endpoint exists, but its server-side implementation has not shipped yet. Retrying the same request will not succeed until the feature is implemented.

### `gateway_timeout`

**HTTP status:** `504`

An upstream dependency did not respond within the time limit. For a resource URL in your request (for example, background audio or an image), verify that the URL is publicly accessible, responds quickly, and is not blocked by firewall or geo-restrictions. For voice generation, retry after a short delay.

When the timeout came from a resource URL you supplied, `message` names that URL when it can be rendered safely; otherwise asset-download timeouts use the fixed string `Failed to download a required asset`. Voice-generation timeouts instead explain that the voice service is temporarily unavailable. For `/v3/live-avatar/*`, the LiveAvatar API accepted the connection but did not answer within 30 seconds. Clients should branch on `code`, not `message`.

### `service_unavailable`

**HTTP status:** `503`

A downstream service needed to fulfill your request (for example, the text-to-speech synthesis backend or video quality comparison judge) is temporarily overloaded or unavailable. This is transient and not caused by your request. Back off and retry after a short delay.

Also returned when brand glossary access cannot be determined temporarily. No glossary read or write is performed. Retry the request after a short delay.

Also returned when publishing a workflow version loses the version number to a concurrent publish on the same workflow. Same guidance: back off and retry.

Also returned when creating or duplicating a workflow without a name could not assign one because concurrent creates in the same space kept taking the next free name. Nothing was created; retry the request.

Also returned by `PUT /v3/templates/{template_id}/variables` when the element metadata store cannot be read while binding a character variable. The variable set is left unchanged rather than stored with a guessed avatar type; retry the same request.

Also returned when starting a workflow run could not confirm its coordinator workflow was accepted (a timeout, transport error, or an unrecognized response from workflow scheduling). This is safe and expected to retry: repeat the request with the same `Idempotency-Key` to resume the same run.

Also returned when canceling a workflow run could not be confirmed as settled (workflow scheduling was unreachable or returned an error). The run is never moved backward by an unconfirmed cancel; retry the cancel request, or fetch the run to see its current status.

Also returned when a workflow run's `url` or `base64` asset input could not be resolved yet. The run stays `preparing`; repeat the run-create request with the same `Idempotency-Key` to resume resolution at the first unresolved input.

Also returned when professional voice source-audio ingestion is temporarily saturated or a finalized source cannot be read consistently. Back off and retry the create request with the same `Idempotency-Key`.

Also returned by `GET /v3/audio/sounds` when the search backend is temporarily rate-limited. Nothing was searched; retry the same request after a short delay.

Also returned by `POST /v3/assets/{asset_id}/complete` when the uploaded file cannot be checked right now. Nothing was finalized; retry the same request after a short delay.

### `render_not_started`

**HTTP status:** `503`

The video's document changed, but its render did not start, so nothing is charged. Read the video's scenes again for the new `edit_version`, then send the edit again with no changes to render it.

### `hyperframes_project_invalid`

**HTTP status:** `400`

The HyperFrames project zip you supplied isn't a valid composition. Make sure the zip contains an `index.html` (or the `composition` entry file you specified) at the root or in a single top-level directory, and that it opens correctly with the `hyperframes` CLI before submitting.

### `hyperframes_project_too_large`

**HTTP status:** `413`

The HyperFrames project zip exceeds the maximum allowed size for the ingestion method you used. Use `asset_id` (pre-upload via [`POST /v3/assets`](/reference/upload-asset)) for projects larger than the `url` / `base64` caps.

### `hyperframes_render_not_found`

**HTTP status:** `404`

No HyperFrames render with that `render_id` exists for your space, or the render has been soft-deleted. Check that the `render_id` is correct and was created under the same API key / space.

### `hyperframes_render_failed`

**HTTP status:** `500`

The HyperFrames render failed server-side while producing the video. The project was accepted and the render started, so this is not a problem with your request payload. Retry the render; if it fails repeatedly for the same project, verify the composition renders locally with the `hyperframes` CLI before contacting support with the `render_id`.

When the cause is in the composition, the render's `failure_message` names it instead of the generic text:

| Cause | What `failure_message` says | What to do |
| - | - | - |
| A font cannot be resolved | Which fonts could not be resolved | Embed the font with `@font-face` or use a Google Fonts family |
| A video cannot be loaded | Why: the server refused the download (HTTP 401/403), the URL returned 404, the file is missing from the project, or it is not a playable video | Use a public URL, a signed URL valid for the whole render, or put the file in the project zip |
| A media element points at the wrong kind of file | Which element type and file type disagree, e.g. an `<audio>` pointing at a video | Use `<video>`, `<audio>` or `<img>` to match the file |
| A media file cannot be read | The file is an incomplete MP4 or a web page instead of media | Check the file plays locally, then re-export or re-download it |
| The render plan is too large | The plan size and the limit | Shorten the composition or split the render |


# For AI Agents
Source: https://heygen-1fa696a7.mintlify.app/docs/for-ai-agents

Agent-first onboarding for AI coding agents — detect auth before writing code, follow the MCP → CLI → raw API ladder, and go from a blank session to a finished video.

<img alt="" />

<Info>
  **Who this is for.** AI coding agents acting on a user's behalf — Claude Code, Codex, Cursor, Gemini CLI, Manus, and similar. Humans should start with the [Quick Start](/docs/quick-start) instead.
</Info>

The most common failure mode for an agent generating a HeyGen video is: read the API reference → write a `curl` script → fail at auth → hand the user a "ready-to-run" file that never actually runs. This page exists to make that failure impossible. **Detect auth before writing any integration code.**

## 1. Detect what's already wired up

Before writing code, check what HeyGen tooling is available in the current environment. Use the **first** one that resolves — don't combine them.

<Steps>
  <Step title="MCP server (fastest path)">
    If `mcp__heygen__*` tools are visible in your toolset, the user is already connected to the [HeyGen Remote MCP](/mcp/overview) over OAuth. **Use these tools directly.** No API key, no key handling, no separate billing — videos consume the user's existing HeyGen plan credits.

    Verify with `mcp__heygen__get_current_user`. If it returns a profile, you're authenticated. Skip to [step 3](#3-generate-the-video).

    Not connected yet? Point the user at the host-specific setup guide: [Claude Code](/mcp/claude-code) · [Claude Web](/mcp/claude-web) · [Gemini CLI](/mcp/gemini-cli) · [Manus](/mcp/manus) · [OpenAI](/mcp/open-ai) · [Superhuman](/mcp/superhuman). For Cursor and other hosts, use the generic endpoint instructions in the [MCP overview](/mcp/overview).
  </Step>

  <Step title="HeyGen CLI">
    **Not installed?** Offer to install it for the user — it's a single binary, no runtime dependencies, headless-friendly:

    ```bash theme={null}
    curl -fsSL https://static.heygen.ai/cli/install.sh | bash
    ```

    Installs to `~/.local/bin`. macOS (Apple Silicon and Intel) and Linux (x64 and arm64) supported. Verify with `heygen --version`. See the [CLI Overview](/cli) for full details.

    **Already installed?** Authenticate it.

    For agent environments, **prefer the environment variable** — it takes precedence over stored credentials and works headlessly without an interactive prompt:

    ```bash theme={null}
    export HEYGEN_API_KEY=<your-key>
    ```

    Then verify with `heygen auth status`. If `HEYGEN_API_KEY` is already set, you're done — no further action.

    Interactive login (`heygen auth login`) is fine for a developer at a terminal, but as an agent you should not depend on it: it blocks on a TTY paste prompt and writes to `~/.heygen/credentials`, neither of which composes well with scripted flows. Only suggest it as a fallback if the user explicitly prefers it.

    If neither auth source is available, ask once and stop:

    ```text theme={null}
    HeyGen CLI installed but no credentials found. Set one of:
      export HEYGEN_API_KEY=<your-key>   (preferred for agent use)
      heygen auth login                  (interactive, stores in ~/.heygen)
    Get your key from https://platform.heygen.com/api-keys — it's shown once.
    Reply "ready" when done and I'll generate the video.
    ```

    Once authenticated, drive the workflow via [`heygen` commands](/commands) — JSON output by default, no need to hand-roll requests.
  </Step>

  <Step title="Raw API (last resort)">
    No MCP, no CLI — fall back to direct HTTPS calls to `api.heygen.com`. Check for `HEYGEN_API_KEY` in the environment first. If it's missing, **do not** invent a key, hardcode one, or prompt the user to paste one into chat. Tell them:

    ```text theme={null}
    HeyGen API key not found. Set it with:
      export HEYGEN_API_KEY=<your-key>
    Get the key from https://platform.heygen.com/api-keys (shown once on creation).
    Reply "ready" when set and I'll generate the video.
    ```

    Once `HEYGEN_API_KEY` is set, follow the [Quick Start](/docs/quick-start) flow: `POST /v3/video-agents` → poll `GET /v3/videos/{video_id}`. Prefer the [Video Agent](/docs/video-agent) endpoint over assembling avatars/voices manually — it handles scripting, casting, and composition for you.
  </Step>
</Steps>

## 2. Install HeyGen skills (recommended)

For agent hosts that support installable skills (Claude Code, Codex, Cursor, OpenClaw, Hermes), install the official [`heygen-com/skills`](https://github.com/heygen-com/skills) repo. It ships a runtime contract, mode-detection ladder, and producer pipelines for video, avatar creation, and translation — so each new session starts from the same baseline instead of re-deriving it from the API reference.

Agent-facing install guide: [`INSTALL_FOR_AGENTS.md`](https://github.com/heygen-com/skills/blob/master/INSTALL_FOR_AGENTS.md). Hand the URL to the agent and it will pick the right install path for the host.

| Agent host | Default skill install path |
| - | - |
| Claude Code | `~/.claude/skills/heygen-skills` |
| Codex | `~/.codex/skills/heygen-skills` |
| Cursor | `~/.cursor/skills/heygen-skills` |
| OpenClaw | `~/.openclaw/skills/heygen-skills` (or `clawhub install heygen-skills`) |
| Hermes | `~/.hermes/skills/heygen-skills` |

## 3. Generate the video

Once authentication is confirmed, prefer one direct action over a multi-file scaffold. For most prompts:

* **MCP**: call `mcp__heygen__create_video_from_avatar` or the Video Agent variant.
* **CLI**: `heygen video-agent create --prompt "<prompt>"` — JSON output by default, see [Output Modes](/output-modes).
* **API**: `POST /v3/video-agents` with `{ "prompt": "<prompt>" }`, then poll `GET /v3/videos/{video_id}` until `status` is `completed` (1–5 minutes). In production, pass a `callback_url` and skip polling.

For prompt structure (scenes, pacing, visual style, casting), see [Writing Effective Video Prompts](/writing-effective-video-prompts). For visual styles, see [Video Agent Styles](/video-agent-with-styles).

## Rules for agents

* **Check auth before writing code.** Run the verifier for whichever path resolved (`mcp__heygen__get_current_user`, `heygen auth status`, or a probe of `GET /v3/users/me`). Don't write integration code on the assumption that auth will work.
* **Never ask the user to paste an API key into chat.** Direct them to the [dashboard](https://platform.heygen.com/api-keys), have them `export HEYGEN_API_KEY=<key>` (preferred — works headlessly for both CLI and raw API), then continue. `heygen auth login` is only a fallback for users at an interactive terminal.
* **If the CLI isn't installed, offer to install it.** It's a single binary (`curl -fsSL https://static.heygen.ai/cli/install.sh | bash`) and is strictly a better surface than raw `curl` for agent flows — structured JSON output, fewer lines of code, and the same `HEYGEN_API_KEY` env-var path.
* **Never invent a key, account, or URL.** If something is missing, say so and ask.
* **Prefer Video Agent over manual assembly.** A single `POST /v3/video-agents` produces a finished video; chaining avatar + voice + composition endpoints by hand is slower and more error-prone unless the user explicitly needs that control.
* **Polling has a ceiling.** Most videos complete in 1–5 minutes. Use exponential backoff, respect `Retry-After` on `429`s ([Usage Limits](/docs/usage-limits)), and prefer `callback_url` in production.
* **Don't hand the user "ready-to-run" scripts as a substitute for actually generating the video.** If you're blocked, name the blocker in one sentence and ask for the one thing you need.

## When things break

* Auth errors → [API Key guide](/docs/api-key).
* Video failed (non-2xx, or `status: failed` with `failure_code`) → [Error Codes](/docs/error-codes).
* Rate-limited → [Usage Limits](/docs/usage-limits).
* Translation, lipsync, avatars, voices → start at the [Cookbook overview](/overview) and follow the per-product card.


# Interactive Sessions
Source: https://heygen-1fa696a7.mintlify.app/docs/interactive-sessions

Build realtime avatar conversations with the HeyGen Interactive Avatar API. Stream live video, low-latency speech, and bidirectional audio over LiveKit-backed.

<img alt="" />

Interactive sessions give you a multi-turn conversation with the Video Agent. Instead of going straight to rendering, the agent pauses at checkpoints (like storyboard review) so you can provide feedback, adjust direction, and approve before the final video is generated. For the fire-and-forget alternative, see [Prompt to Video](/docs/video-agent).

## Session lifecycle

<Steps>
  <Step title="Create a session">
    [`POST /v3/video-agents`](/reference/create-video-agent-session) with `"mode": "chat"` — Send your initial prompt. The agent begins processing.
  </Step>

  <Step title="Poll for status">
    [`GET /v3/video-agents/{session_id}`](/reference/get-video-agent-session) — Check progress and read agent messages. The session pauses at `reviewing` status.
  </Step>

  <Step title="Review and iterate">
    [`POST /v3/video-agents/{session_id}`](/reference/send-message-or-request-revision) — Send feedback or approve the storyboard. Repeat as needed.
  </Step>

  <Step title="Generate the video">
    Approve the storyboard by sending a confirmation message. The session moves to `generating`, then `completed`. Fetch the final video with [`GET /v3/videos/{video_id}`](/reference/get-video).
  </Step>
</Steps>

### Session statuses

| Status | Description |
| - | - |
| `thinking` | Agent is working (scripting, composing scenes, preparing storyboard). |
| `waiting_for_input` | Agent is paused, waiting for your input. |
| `reviewing` | Agent is paused at a review checkpoint. Review the storyboard and messages. |
| `generating` | Storyboard approved — video is rendering. |
| `completed` | Video is ready. Retrieve it via [`GET /v3/videos/{video_id}`](/reference/get-video). |
| `failed` | Something went wrong. Check messages for error details. |

## Create a session

Full schema: [`POST /v3/video-agents`](/reference/create-video-agent-session). Pass `"mode": "chat"` to enable interactive mode.

### Request body

| Parameter | Type | Required | Description |
| - | - | - | - |
| `prompt` | string | **Yes** | Initial message to the agent (1–10,000 characters). |
| `mode` | string | No | Set to `"chat"` for interactive sessions. Defaults to `"generate"` (one-shot). |
| `avatar_id` | string | No | Specific avatar look ID. |
| `voice_id` | string | No | Specific voice ID for narration. |
| `style_id` | string | No | Style ID from [`GET /v3/video-agents/styles`](/reference/list-video-agent-styles). Applies a curated visual template. See [Styles & References](/docs/styles-and-references). |
| `brand_kit_id` | string | No | Brand kit ID from [`GET /v3/brand-kits`](/reference/list-brand-kits). Applies your brand colors, fonts, and logo. See [Brand Kits](/docs/brand-kits). |
| `brand_glossary_id` | string | No | Brand glossary ID from [`GET /v3/brand-glossaries`](/reference/list-brand-glossaries). Sets how your custom terms are pronounced in the narration, for the whole session. See [Brand Glossary](/docs/brand-glossary). |
| `orientation` | string | No | `"landscape"` or `"portrait"`. Auto-detected if omitted. |
| `files` | array | No | Up to 20 file attachments (asset\_id, url, or base64). See [Upload Assets](/docs/upload-assets) and [`POST /v3/assets`](/reference/upload-asset). |
| `callback_url` | string | No | [Webhook](/docs/webhooks) URL for completion/failure notifications. |
| `callback_id` | string | No | Caller-defined ID echoed back in the webhook payload. |
| `incognito_mode` | boolean | No | When `true`, disables memory injection and extraction for this session. Default: `false`. |

<Tip>
  To skip the review step entirely, create the session with `"mode": "generate"` instead of `"chat"`. It runs straight through to generation and you still get a `session_id` to track. `mode` is the only control over whether the agent pauses — there is no separate flag.
</Tip>

### Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://api.heygen.com/v3/video-agents" \
    -H "X-Api-Key: $HEYGEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Create a 2-minute onboarding video for new engineering hires. Cover team culture, dev tools, and first-week checklist.",
      "mode": "chat",
      "orientation": "landscape"
    }'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://api.heygen.com/v3/video-agents",
      headers={"X-Api-Key": HEYGEN_API_KEY},
      json={
          "prompt": "Create a 2-minute onboarding video for new engineering hires.",
          "mode": "chat",
          "orientation": "landscape",
      },
  )
  session = resp.json()["data"]
  session_id = session["session_id"]
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "data": {
    "session_id": "sess_abc123",
    "status": "thinking",
    "video_id": null,
    "created_at": 1711382400
  }
}
```

## Poll session status

Full schema: [`GET /v3/video-agents/{session_id}`](/reference/get-video-agent-session). Returns the current session status, progress percentage, chat messages, and the `video_id` once generation starts.

### Response

```json theme={null}
{
  "data": {
    "session_id": "sess_abc123",
    "status": "reviewing",
    "progress": 45,
    "title": "Engineering Onboarding Video",
    "video_id": null,
    "created_at": 1711382400,
    "messages": [
      {
        "role": "model",
        "content": "I've drafted a storyboard with 4 scenes covering team culture, dev environment setup, key tools, and the first-week checklist. Would you like to review it or should I proceed?",
        "type": "text",
        "created_at": 1711382450,
        "resource_ids": ["res_storyboard_001"]
      },
      {
        "role": "user",
        "content": "Create a 2-minute onboarding video for new engineering hires.",
        "type": "text",
        "created_at": 1711382400,
        "resource_ids": null
      }
    ]
  }
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `session_id` | string | Session identifier. |
| `status` | string | Current status: `thinking`, `waiting_for_input`, `reviewing`, `generating`, `completed`, `failed`. |
| `progress` | integer | Progress percentage (0–100). |
| `title` | string \| null | Agent-generated session title. |
| `video_id` | string \| null | Video ID once generation starts. Use with [`GET /v3/videos/{video_id}`](/reference/get-video). |
| `created_at` | integer | Unix timestamp of session creation. |
| `messages` | array | Most recent visible messages (max 40, newest-first). |

### Message object

| Field | Type | Description |
| - | - | - |
| `role` | string | `"user"` or `"model"`. |
| `content` | string | Message text. |
| `type` | string | `"text"`, `"resource"`, or `"error"`. |
| `created_at` | integer \| null | Unix timestamp. |
| `resource_ids` | array \| null | Resource IDs resolvable via [`GET /v3/video-agents/{session_id}/resources/{resource_id}`](/reference/get-session-resource). |

## Send a follow-up message

Full schema: [`POST /v3/video-agents/{session_id}`](/reference/send-message-or-request-revision). Send feedback, request changes, or approve the storyboard. The agent processes your message and updates the session.

### Request body

| Parameter | Type | Required | Description |
| - | - | - | - |
| `message` | string | Yes, unless `edit_plan` is sent | Your message to the agent (1–10,000 characters). |
| `edit_plan` | array | No | Scene-scoped edits, one item per scene, applied together. Read scene ids and `edit_version` from [`GET /v3/videos/{video_id}/scenes`](/reference/get-video-scenes) first. See [Edit Scenes](/docs/edit-scenes). |
| `avatar_id` | string | No | Override avatar for this message. |
| `voice_id` | string | No | Override voice for this message. |
| `brand_kit_id` | string | No | Apply a brand kit from this message onward. Lets you switch brands mid-session. See [Brand Kits](/docs/brand-kits). The brand glossary, by contrast, is fixed at session creation. |
| `files` | array | No | Additional file attachments (max 20). |

<Note>
  There is no `auto_proceed` parameter. Sending any follow-up message resumes the agent, so a confirmation like "looks good, generate it" is what approves the storyboard. Both this endpoint and session creation reject unrecognized fields with a `422`.
</Note>

### Example: Request changes

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/video-agents/sess_abc123" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Looks great, but add a scene about our code review process before the checklist scene."
  }'
```

### Example: Approve and generate

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/video-agents/sess_abc123" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Looks perfect, go ahead and generate the video."
  }'
```

### Response

```json theme={null}
{
  "data": {
    "session_id": "sess_abc123",
    "run_id": "run_def456",
    "title": "Engineering Onboarding Video"
  }
}
```

After sending a message, poll [`GET /v3/video-agents/{session_id}`](/reference/get-video-agent-session) to see the agent's response and updated status.

## Get a session resource

Full schema: [`GET /v3/video-agents/{session_id}/resources/{resource_id}`](/reference/get-session-resource). Retrieve a specific resource by ID — storyboard images, draft videos, selected avatars, and voices are all exposed as resources. Resource IDs are referenced in message `resource_ids` arrays. To list all videos generated by a session, use [`GET /v3/video-agents/{session_id}/videos`](/reference/list-session-videos).

### Example

```bash theme={null}
curl "https://api.heygen.com/v3/video-agents/sess_abc123/resources/res_storyboard_001" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

### Response

```json theme={null}
{
  "data": {
    "resource_id": "res_storyboard_001",
    "resource_type": "image",
    "source_type": "generated",
    "url": "https://files.heygen.ai/resources/res_storyboard_001.png",
    "thumbnail_url": "https://files.heygen.ai/resources/res_storyboard_001_thumb.png",
    "created_at": 1711382450,
    "metadata": {}
  }
}
```

### Resource object

| Field | Type | Description |
| - | - | - |
| `resource_id` | string | Unique identifier. Referenced in message `resource_ids`. |
| `resource_type` | string | Type: `image`, `video`, `draft`, `avatar`, `voice`, etc. |
| `source_type` | string \| null | `"generated"` or `"user_uploaded"`. |
| `url` | string \| null | Primary media URL. |
| `thumbnail_url` | string \| null | Thumbnail URL. |
| `preview_url` | string \| null | Preview URL. |
| `created_at` | integer \| null | Unix timestamp. |
| `metadata` | object \| null | Type-specific metadata. |

## Stop a session

Full schema: [`POST /v3/video-agents/{session_id}/stop`](/reference/stop-video-agent-session). Stop an in-progress agent run — the agent halts at the next checkpoint, and partial results are preserved.

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/video-agents/sess_abc123/stop" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```json Response theme={null}
{
  "data": {
    "session_id": "sess_abc123"
  }
}
```


# HeyGen Image
Source: https://heygen-1fa696a7.mintlify.app/docs/models/heygen-image

One identity, any scene. HeyGen Image keeps a person's face and takes the pose, clothing, light and setting from a reference image, on POST /v3/models/images.

<img alt="" />

One person. Six scenes she was never photographed in. HeyGen Image takes identity photos of a person and one reference image, and returns portraits that keep her face while following the reference's pose, clothing, light and setting.

## From one identity to any scene

Three photos of the HeyGen public avatar Serena went in as `identity_images`. Each scene below is one call with one `reference_images` entry, shown inset at the bottom left of its output. The reference's person never appears; only her pose, outfit and world do.

<Identity />

<Scenes />

The six references are generated images, not photographs of real people. A reference can be a photo you own, a frame from a film, or a product shot with a model in it; it must contain exactly one person, or the job fails with `multiple_faces_detected`.

The scene, light, clothing and framing come from the reference. The face, hair, expression and gaze come from the identity photos: these three are studio portraits looking at the camera, so every output looks at the camera too. For candid results, use candid identity photos. For video, a still becomes the first frame of a [HeyGen Video](/docs/models/heygen-video#modes) `image_to_video` clip; start the prompt with "Keep the person exactly as they appear in the first frame" and describe one camera move.

<Warning>
  Generate people you have the right to generate: yourself, a consenting colleague, or a licensed HeyGen public avatar as here. A public photo is not a licence for someone's face.
</Warning>

## Build it with an agent

Not technical? Paste this into [Claude Code](https://claude.com/claude-code), [Codex](https://openai.com/codex/), or Cursor. Bring a few photos of the person and a few scene photos you own; it generates the set with you.

```text Prompt for your agent wrap theme={null}
I want a set of portraits of one person in six different scenes with the HeyGen API. I am not a developer, so run the commands for me where you can, explain each step in one plain sentence, and when I have to do something myself tell me exactly what and wait for me.

Read these first and follow them exactly:
- https://developers.heygen.com/docs/models/heygen-image.md
- https://developers.heygen.com/docs/upload-assets.md
- https://developers.heygen.com/docs/for-ai-agents.md (rules for agents)

Then take me through this, checking each step before the next:
1. API key. Look for HEYGEN_API_KEY in my environment. If it is missing, send me to https://platform.heygen.com/api-keys to create one and have me export it in my terminal myself. Never ask me to paste the key into this chat. Confirm it works with GET /v3/users/me.
2. Identity. Ask me for one to five clear photos of the person I have the right to use, or offer to use a HeyGen public avatar from GET /v3/avatars?ownership=public. Upload the photos with POST /v3/assets and keep the asset_ids.
3. Scenes. Ask me for up to six scene photos I own, each showing exactly one person whose pose, clothing, light and setting I want. Check each one: one person, whole head in frame. Upload them with POST /v3/assets and keep the asset_ids. Tell me which aspect ratio from the Parameters table matches each photo.
4. Portraits. For each reference, call POST /v3/models/images with model heygen-image-1, my identity asset_ids, that one reference, the same aspect_ratio, and an Idempotency-Key. Poll GET /v3/models/images/{generation_id} until completed, download each PNG and show it to me. If a job fails with no_face_detected, tell me which input to replace. Offer a second seed for any scene I want to re-roll.

If a request fails, look the error code up in the Errors tables on those pages and tell me the fix. Never invent keys, IDs, or URLs; if something is missing, ask me for that one thing.
```

## The API

| | |
| - | - |
| Model | `heygen-image-1`, mode `identity_remix` (the only mode; omit it) |
| Create | [`POST /v3/models/images`](/reference/create-heygen-image), returns `202` and a `generation_id` |
| Retrieve | [`GET /v3/models/images/{generation_id}`](/reference/get-heygen-image), poll until `completed` |
| Inputs | 1–5 `identity_images` of one person, exactly 1 `reference_images` entry |
| Outputs | 1–5 PNGs per job, same shape, up to 3840 × 2160 |
| Auth | `X-Api-Key` from the [API keys page](https://platform.heygen.com/api-keys); scopes `images:write`, `images:read`, `assets:write` for uploads |

### Create

The call behind the train scene above:

```bash theme={null}
curl -X POST https://api.heygen.com/v3/models/images \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: serena-train-window-001" \
  -d '{
    "model": "heygen-image-1",
    "identity_images": [
      { "type": "asset_id", "asset_id": "'"$IDENTITY_1"'" },
      { "type": "asset_id", "asset_id": "'"$IDENTITY_2"'" },
      { "type": "asset_id", "asset_id": "'"$IDENTITY_3"'" }
    ],
    "reference_images": [{ "type": "asset_id", "asset_id": "'"$TRAIN_WINDOW_REF"'" }],
    "aspect_ratio": "3:4",
    "num_images": 1,
    "seed": 3000
  }'
```

```json Response theme={null}
{ "data": { "generation_id": "e09432dfc8ce463799250d489965cbea", "status": "pending" } }
```

### Retrieve

```bash theme={null}
curl https://api.heygen.com/v3/models/images/e09432dfc8ce463799250d489965cbea \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

```json Response theme={null}
{
  "data": {
    "generation_id": "e09432dfc8ce463799250d489965cbea",
    "status": "completed",
    "model": "heygen-image-1",
    "num_images": 1,
    "created_at": 1791593640,
    "images": [
      { "image_id": "IMAGE_ID", "image_url": "https://…/signed.png", "width": 2160, "height": 2880, "seed": 3000 }
    ]
  }
}
```

| Status | Meaning | `images` |
| - | - | - |
| `pending` | Waiting or generating. Keep polling. | `[]` |
| `completed` | Every requested image is ready. | Exactly `num_images` entries, stable order |
| `failed` | Read `failure_code` and `failure_message`. | `[]` |
| `cancelled` | Read `failure_code` and `failure_message`. | `[]` |

The response is `200` even when the job failed. There is no partial result and no callback. Download URLs expire; retrieve the job again for fresh ones, and keep `generation_id` and `image_id` as the stable identifiers.

## Choose your inputs

* **`identity_images`**: one to five photos of the person whose identity should appear in the result. Use clear photos where their face is visible. These are multiple views of one identity, not separate generation requests.
* **`reference_images`**: an array with exactly one image showing the desired clothing, pose, composition, and background. It guides the look of every output in the job.

Each input uses the same asset format as other HeyGen APIs. You can mix input types within a request.

<CodeGroup>
  ```json Uploaded asset theme={null}
  { "type": "asset_id", "asset_id": "ASSET_ID" }
  ```

  ```json HTTPS URL theme={null}
  { "type": "url", "url": "https://example.com/photo.jpg" }
  ```

  ```json Inline base64 theme={null}
  { "type": "base64", "media_type": "image/jpeg", "data": "BASE64_ENCODED_IMAGE" }
  ```
</CodeGroup>

Uploaded assets must be images owned by the calling workspace. Use the returned `asset_id` from the [asset upload API](/reference/upload-asset), not a generated output's `image_id`.

URL inputs must be publicly accessible HTTPS URLs pointing directly to an image; redirects are not followed. Image downloads are limited to 16 MiB. Inline base64 inputs are limited to 5 MiB of decoded image data.

## Parameters

| Field | Required | Description |
| - | - | - |
| `model` | Yes | Only `heygen-image-1`. Release IDs and internal model names are not accepted. |
| `mode` | No | Only `identity_remix`. Defaults to `identity_remix` when omitted. |
| `identity_images` | Yes | Array of 1–5 image assets for the identity to preserve. |
| `reference_images` | Yes | Array of exactly one image asset showing the desired look. Empty arrays and arrays with more than one image are rejected. |
| `aspect_ratio` | No | One of `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, or `16:9`. Omit or use `null` to match the reference image after EXIF orientation. |
| `num_images` | No | Integer from 1 to 5. Defaults to `1`. |
| `seed` | No | Integer from 0 to 4,294,967,295 for the first output. Chosen randomly when omitted or `null`. |

Unknown fields are rejected. `prompt`, the singular `reference_image` field, custom dimensions, and callback fields are not supported.

## Output

Use `aspect_ratio` to choose the output shape, or omit it to follow the reference image. Identity images do not determine output shape. When inferring from the reference, its width-to-height ratio must be between 1:4 and 4:1.

The model chooses its native canvas using its 4K training policy and then center-crops a narrow border to deliver the requested ratio. There is no output upscaling. Explicit presets have exact ratios; inferred ratios round to the nearest pixel. Returned dimensions do not have to be multiples of 32.

| `aspect_ratio` | Delivered width × height |
| - | - |
| `1:1` | 2176 × 2176 |
| `2:3` | 2176 × 3264 |
| `3:2` | 3264 × 2176 |
| `3:4` | 2160 × 2880 |
| `4:3` | 2880 × 2160 |
| `4:5` | 2176 × 2720 |
| `5:4` | 2720 × 2176 |
| `9:16` | 2160 × 3840 |
| `16:9` | 3840 × 2160 |

Always read `width` and `height` from each output. An aspect override changes the generation canvas and may change composition; it is not just a crop of the reference photo. All images in one job share the chosen output shape.

## Retries and seeds

Use a unique `Idempotency-Key` for each new job, and reuse that key with the same body when retrying a submission after a timeout. While the idempotency record is retained, the retry resumes or returns the original job. Use a new key when you want a new generation, even if the inputs are the same. The header is optional, but omitting it allows retries to create additional jobs.

`seed` controls the first output. Later outputs use `seed + 1`, `seed + 2`, and so on. With `seed: 42` and `num_images: 2`, the outputs report seeds `42` and `43`. Each output reports its actual seed; later seeds can exceed the request field's maximum. Different seeds provide variation, but do not guarantee visibly different images. A seed is not an idempotency key or a guarantee of identical results across model updates.

## Errors

Request errors use the standard [HeyGen error format](/docs/error-codes). An invalid field or unsupported image count returns HTTP 400. A generation that is missing or belongs to another workspace returns HTTP 404. API keys need the scopes listed above, and trial API keys are not supported. Insufficient API credits return HTTP 402 (`insufficient_credit`). A temporary billing or service failure can return HTTP 503; retry with the same idempotency key.

The default rate limits are 30 creation requests per minute and 300 retrieval requests per minute. Workspace limits can differ. If a request returns HTTP 429, follow `Retry-After`.

A generation failure is different from an HTTP request error. A successful status lookup returns HTTP 200 with a terminal status and these fields:

| `failure_code` | Action |
| - | - |
| `no_face_detected` | Replace the image named in `failure_message` with a clear face photo. |
| `multiple_faces_detected` | Replace the image named in `failure_message` with a photo of one person. |
| `generation_failed` | Read `failure_message`. If the failure persists, contact support with the generation ID. |
| `generation_cancelled` | The job was cancelled. Submit a new job if needed. |

Failed and cancelled jobs return no partial images. There is no API endpoint for cancelling a job.

## Specs at a glance

| | |
| - | - |
| Model | `heygen-image-1` |
| Mode | `identity_remix` |
| Identity inputs | 1–5 images of one person |
| Appearance reference | Exactly one image in `reference_images` |
| Outputs | 1–5 PNG images per job |
| Shape | Nine aspect-ratio presets, or inferred from the reference image |
| Custom prompt | Not supported |
| Completion | Poll by `generation_id`; no callbacks or partial results |
| API keys | Paid API keys |


# HeyGen Video
Source: https://heygen-1fa696a7.mintlify.app/docs/models/heygen-video

HeyGen Video, built on MiniMax H3 and post-trained by HeyGen, generates a whole scene from a prompt: subject, setting and sound together, in one call. Text to video, image to video and reference to video.

<img alt="" />

**HeyGen Video is our general-purpose video model, built on MiniMax H3 and post-trained by HeyGen.** Give it a prompt and it generates the whole scene: subject, setting, light and sound together, in one call. Each clip runs 5 to 15 seconds with its own audio track of dialogue, ambience and sound effects, so there is no separate speech pass, lip-sync step or avatar to pick.

One model, `heygen-video-1`, called in three ways:

| Mode | You give it | You get |
| - | - | - |
| **Text to video** (`text_to_video`) | A prompt | A new scene with its sound |
| **Image to video** (`image_to_video`) | A prompt and one image | A clip that opens on your image as its first frame |
| **Reference to video** (`reference_to_video`) | A prompt and your images, videos or audio | A new scene that keeps the products, people or places you supplied |

It is a different tool from the [avatar rendering engines](/models) behind [`POST /v3/videos`](/reference/create-video). Those animate a look you already own from a script you already wrote. This one invents the subject, the setting, the light and the sound at once, from a description. The rest of this page starts with the call itself, then what the model is good at and how to prompt it, then the full API reference.

## Build with it

| | |
| - | - |
| Model identifier | `heygen-video-1` |
| Create | [`POST /v3/models/videos`](/reference/create-heygen-video) |
| Retrieve | [`GET /v3/models/videos/{video_id}`](/reference/get-heygen-video) |
| Examples | [The launch films clip by clip](https://developers.heygen.com/heygen-video-1.0-catalog), with the prompt behind every shot |
| Auth | `x-api-key` header, from [the API keys page](https://platform.heygen.com/api-keys) |
| Scopes | `videos:write` to create, `videos:read` to retrieve, `assets:write` to upload references |

### Generate a video

```bash theme={null}
curl -X POST https://api.heygen.com/v3/models/videos \
  -H "x-api-key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen-video-1",
    "mode": "text_to_video",
    "prompt": "A plant supervisor in a plain grey coat stands beside a conveyor line and speaks to camera.",
    "duration": 5,
    "resolution": "768p",
    "aspect_ratio": "16:9",
    "seed": 42
  }'
```

Submission returns `202`:

```json theme={null}
{ "data": { "status": "pending", "video_id": "VIDEO_ID" } }
```

Send an `Idempotency-Key` header to retry safely: a retry with the same key within 24 hours returns the original response, and a concurrent duplicate returns `409`.

### Retrieve the result

Poll `GET /v3/models/videos/{video_id}`. `pending` means queued and `processing` means running. The terminal states are `completed`, `failed` and `cancelled`.

```bash theme={null}
curl https://api.heygen.com/v3/models/videos/VIDEO_ID \
  -H "x-api-key: $HEYGEN_API_KEY"
```

```json theme={null}
{
  "data": {
    "video_id": "VIDEO_ID",
    "status": "completed",
    "model": "heygen-video-1",
    "created_at": 1789689600,
    "video_url": "https://resource2.heygen.ai/videos/.../VIDEO.mp4",
    "duration": 5,
    "aspect_ratio": "16:9",
    "width": 1344,
    "height": 768,
    "seed": 42
  }
}
```

`video_url` is a signed link: poll again to refresh it. Failed and cancelled jobs carry `failure_code` (`generation_failed` or `generation_cancelled`) and `failure_message`. An unknown ID, or one from another workspace, returns `404`.

The same job is also readable through `GET /v3/videos/{video_id}`, alongside your other videos, with `video_page_url` and a `title` taken from the first 64 characters of the prompt.

## What it is good at

Sound on for everything below. Every clip on this page is raw model output, with the audio it generated.

<CardGroup>
  <Card title="Scenes that hold together" icon="cube">
    Objects stay the same size and shape, stay where they were put, and obey physics. Things do not duplicate, vanish or reappear mid-shot.
  </Card>

  <Card title="Doing what you asked" icon="list-check">
    It follows a brief literally rather than improvising. If you did not ask for dialogue, you do not get dialogue.
  </Card>

  <Card title="Picture and sound together" icon="waveform-lines">
    Room tone, effects and speech are generated with the image from the same prompt, so they match the space you described.
  </Card>

  <Card title="Holding an object you supply" icon="image">
    Give it a photograph in `reference_to_video` and the colour, form and markings of that object survive into the shot.
  </Card>
</CardGroup>

It is at its best on **short, contained shots**: one subject, one place, one action, a locked or barely moving camera. It is least reliable on **long on-screen text**, **soft organic motion** such as petals, paper and hair, and **close hand work** like assembling or operating equipment.

## How to prompt it

Long prompts beat short ones. A few hundred to a few thousand characters gives materially better output, and there is no penalty for detail. The examples below are shots from the HeyGen Video launch film, each with the exact prompt that produced it. The last two use the sectioned layout the film was written in for its longer shots; it is plain text in the same `prompt` field.

<Grid />

### The rules worth knowing

<AccordionGroup>
  <Accordion title="Name the camera, not the mood">
    A body, a lens and an aperture set depth of field, grain and motion together. "Cinematic" and "high quality" do almost nothing. `Shot on an ARRI Alexa Mini LF, 50mm T2, locked off on a tripod` changes the image.
  </Accordion>

  <Accordion title="Ask for texture, then forbid the correction">
    Describing pores and fine lines gets you part way. Adding `no retouching, no beauty filter, no glamour lighting` gets you the rest. Without the second clause, faces drift toward a retouched look. The same applies to colour: ask for muted colour, then rule out the default with `no teal-orange grade`.
  </Accordion>

  <Accordion title="Rule out marks you did not ask for">
    Plain clothing and equipment will otherwise pick up invented branding. Add `no logos, brand names, printed words or badges anywhere in frame`.
  </Accordion>

  <Accordion title="Keep lettering short and spelled out">
    A short capitalised phrase renders reliably when the prompt spells it exactly and names it as the only lettering in frame: `The only lettering anywhere is the words NOT ANYMORE, spelled exactly NOT ANYMORE`. Keep everything else free of text with the marks clause above. Paragraphs, small print and labelled diagrams read best as real type composited afterwards.
  </Accordion>

  <Accordion title="Prefer stillness to manipulation">
    A static camera with the subject wearing or holding an object is the most reliable composition available. Objects worn on the body render best of all. Close hand work degrades fastest: if a procedure needs explaining, let the speech carry the steps and keep the hands still.
  </Accordion>

  <Accordion title="Say where things touch">
    When an action involves one thing meeting another, name the contact point and say it holds. Without that, the gesture often lands near the target rather than on it.
  </Accordion>

  <Accordion title="Describe the sound">
    Audio comes from the same prompt, so direct it. Name the room tone, the specific effects and their distance. Say `no music` when you do not want a bed, because one may otherwise appear. Written dialogue fits at roughly 2.5 words per second.
  </Accordion>

  <Accordion title="Iterate with a fixed seed">
    Set `seed` yourself and the same prompt returns the same clip, so you can change one clause at a time. Omit it and the server picks a random one, so two identical requests give you different videos.
  </Accordion>
</AccordionGroup>

## Twelve styles

Style is a prompt variable. The launch films shot the same driver close-up in four media, and took one drawing from pencil to oil paint to a clay model, each step an [`image_to_video`](#modes) shot that starts from the last frame of the one before. The reliable way to get a real style is to name an actual production process and the physical marks it leaves, restrict the palette, and rule out the smooth digital default.

<Grid />

## Lettering in the shot

Every title in the launch films was generated inside the shot: painted on a wall, stamped in ink or pressed into paper. The painted track and the platform display under [How to prompt it](#how-to-prompt-it) are two more. Short phrases, spelled out exactly, render reliably, which is what makes these work.

<Note>
  Each prompt spelled the phrase exactly and named it as the only lettering in frame. For longer copy, such as a full lockup with a tagline, add real type afterwards.
</Note>

<Grid />

## Callbacks

Pass `callback_url` on the create request to be notified when a job finishes, and `callback_id` to correlate the delivery.

| | |
| - | - |
| `callback_url` | Must be an HTTPS URL |
| `callback_id` | At most 256 characters, returned with the delivery |
| Events | `avatar_video.success` and `avatar_video.fail` |
| Success payload | `video_id`, `callback_id`, `url`, `video_page_url`, `video_share_page_url` |
| Failure payload | `video_id`, `callback_id`, `video_page_url`, `msg` |

Send `callback_id` alone to deliver to the webhook endpoints registered for your workspace. One event fires per job, at the terminal status, and a callback is attempted **once**. Treat it as a latency optimisation and keep polling as the fallback for anything you cannot afford to miss.

## Modes

`mode` selects how the model is conditioned. Each mode has its own fields; a field from another mode returns `400` when it carries a value (an empty list or `null` passes).

| Mode | Requires | Takes |
| - | - | - |
| `text_to_video` | `prompt` | the shared fields |
| `image_to_video` | `prompt` and `image` | `image` as the first frame |
| `reference_to_video` (default) | `prompt` and at least one reference image or video | `reference_images`, `reference_videos`, `reference_audio` |

The short forms `t2v`, `i2v` and `ref2va` are accepted as aliases. New integrations should use the long names, which is what validation errors return.

`image_to_video` treats the supplied image as the literal first frame, so the clip opens exactly as that still looks. To place a product or piece of equipment into a scene of your own, use `reference_to_video` and describe the scene around it.

```json theme={null}
{
  "model": "heygen-video-1",
  "mode": "reference_to_video",
  "prompt": "A supervisor wearing the harness in <Picture 1> stands still and speaks to camera.",
  "reference_images": [{ "type": "asset_id", "asset_id": "ASSET_ID" }],
  "duration": 10
}
```

## References and prompt labels

In `reference_to_video`, list order becomes the label you address in the prompt. The first entry of `reference_images` is `<Picture 1>`, the second is `<Picture 2>`, the first entry of `reference_videos` is `<Video 1>`, and so on. Images, videos and audio are numbered independently.

The API does not rewrite these labels. [Prompt enhancement](#prompt-enhancement) can reword the rest of the prompt; set it to `disabled` to keep your text as written.

| List | Maximum |
| - | - |
| `reference_images` | 9 |
| `reference_videos` | 3 |
| `reference_audio` | 3 |
| Total across all three | 12 |

The model reads the first 5 seconds of each reference video, so longer clips are trimmed to that length before generation. Cut each clip to the 5 seconds you want followed before you upload it.

Each reference accepts an HTTPS URL, an uploaded asset ID, or inline base64.

```json theme={null}
{ "type": "url",      "url": "https://example.com/photo.jpg" }
{ "type": "asset_id", "asset_id": "ASSET_ID" }
{ "type": "base64",   "media_type": "image/jpeg", "data": "<base64>" }
```

| Input | Maximum size |
| - | - |
| Image by URL | 16 MB |
| Video or audio by URL | 32 MB |
| Image as base64 | 5 MB |
| Video or audio as base64 | 16 MB |

URLs are fetched server side with SSRF checks and staged before dispatch. The fetcher does not follow redirects, so upload anything you do not control through `POST /v3/assets` and pass the returned `asset_id`.

```bash theme={null}
curl -X POST https://api.heygen.com/v3/assets \
  -H "x-api-key: $HEYGEN_API_KEY" \
  -F "file=@harness.jpg"
```

Uploaded assets must belong to the calling workspace and are reusable across requests.

## Prompt enhancement

Before generation, the prompt passes through an enhancement step that expands it for the model. `prompt_enhancement` picks how:

| Value | Behaviour |
| - | - |
| `turbo` | Fastest |
| `quality` (default) | Balanced between quality and speed |
| `ultraquality` | Highest quality, slowest |
| `disabled` | The prompt goes to the model exactly as you wrote it |

```json theme={null}
{
  "model": "heygen-video-1",
  "mode": "text_to_video",
  "prompt": "A pastry chef pipes a single line of cream along a tart shell, then stops.",
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "prompt_enhancement": "ultraquality"
}
```

Use `disabled` when you have already written a long, fully specified prompt and want it followed word for word.

## Parameters

| Field | Type | Default | Notes |
| - | - | - | - |
| `model` | string | required | `heygen-video-1` |
| `mode` | enum | `reference_to_video` | `text_to_video`, `image_to_video`, `reference_to_video` |
| `prompt` | string | required | 1 to 32,000 characters |
| `duration` | integer | `5` | Any integer from 5 to 15 seconds |
| `resolution` | enum | `768p` | `480p`, `768p`, `1080p` or `2k`. `1080p` and `2k` bill at 3× the `768p` rate. |
| `prompt_enhancement` | enum | `quality` | `turbo`, `quality`, `ultraquality` or `disabled` |
| `aspect_ratio` | enum | see below | `21:9`, `16:9`, `4:3`, `1:1`, `3:4` or `9:16`, plus `adaptive` for `reference_to_video`. `image_to_video` follows the first frame. |
| `seed` | integer | random | Unsigned 32-bit. Random when omitted; set it yourself to iterate on a shot. |
| `callback_url` | string | | HTTPS only |
| `callback_id` | string | | At most 256 characters |
| `image` | asset | | `image_to_video` only, required there |
| `reference_images` | array | `[]` | `reference_to_video` only |
| `reference_videos` | array | `[]` | `reference_to_video` only |
| `reference_audio` | array | `[]` | `reference_to_video` only |

The schema is strict: unknown fields are rejected rather than ignored.

## Output

| | |
| - | - |
| Container | MP4, H.264 |
| Frame rate | 24 fps, rounded up to the next whole frame: a 7-second request encodes 175 frames |
| Audio | AAC, 32 kHz stereo, generated dialogue and effects |
| Delivery | HTTPS URL on the job record |

`resolution` names a size class and `aspect_ratio` sets the shape. When you set `aspect_ratio` explicitly, the two resolve to a fixed pixel size:

| `aspect_ratio` | `2k` | `1080p` | `768p` | `480p` |
| - | - | - | - | - |
| `21:9` | | | 1536 × 672 | 960 × 416 |
| `16:9` | 2688 × 1536 | 1890 × 1080 | 1344 × 768 | 832 × 480 |
| `4:3` | | | 1024 × 768 | 640 × 480 |
| `1:1` | | | 768 × 768 | 480 × 480 |
| `3:4` | | | 768 × 1024 | 480 × 640 |
| `9:16` | 1536 × 2688 | 1080 × 1890 | 768 × 1344 | 480 × 832 |

`1080p` and `2k` render in `16:9` or `9:16`. Set `aspect_ratio` to one of them for `text_to_video` and `reference_to_video`, since `adaptive` resolves at `480p` and `768p` only. `image_to_video` follows the first frame at every resolution.

### Default aspect ratio

`text_to_video` has nothing to take a shape from and defaults to `16:9`.

`reference_to_video` defaults to `adaptive`: the aspect ratio of the first reference image, or the first reference video when there are no images. Pass one of the six ratios to override it.

`image_to_video` always follows the first frame, including its EXIF orientation. To change the output shape, crop the image before uploading it.

In both adaptive cases the output follows the source ratio, scaled to the short edge of the resolution with each side rounded to a multiple of 32. A 1280 × 852 reference at `480p` returns 736 × 480. The completed job reports the actual `width` and `height`, and `aspect_ratio` as the reduced pixel ratio, for example `23:15`.

## Seeds

Set `seed` yourself to make a shot repeatable: the same prompt and the same seed, submitted in succession, return an identical file. Hold the seed and change one clause at a time to iterate.

When `seed` is omitted the server picks a random one, so two identical requests return different videos. The completed job reports the seed it used as `seed`.

Treat a seed as reproducible within a deployment rather than as a permanent handle on one render.

## Errors

Errors return `{"error": {"code", "message", "param", "doc_url"}}`. Validation errors use code `invalid_parameter` and set `param` to the field.

| Situation | `param` | Message |
| - | - | - |
| Wrong model identifier | `model` | Must be `heygen-video-1` |
| Unknown mode | `mode` | `mode must be one of: text_to_video, image_to_video, reference_to_video.` |
| No references in `reference_to_video` | `reference_images` | `Provide at least one reference image or video.` |
| Reference list outside `reference_to_video` | the field sent | `reference_images is only accepted with mode reference_to_video.` |
| `image_to_video` without `image` | `image` | `Field required` |
| Duration out of range | `duration` | `Input should be greater than or equal to 5` |
| Unsupported aspect ratio | `aspect_ratio` | Lists the ratios the mode accepts |
| Non-HTTPS callback | `callback_url` | `Value error, callback_url must be an HTTPS URL` |
| Unfetchable reference URL | absent | `Invalid URL in reference_image[0]: Could not download the file. Ensure the URL is publicly accessible.` |
| Oversized inline reference | absent | `Base64 file in reference_image[0] is too large (N bytes).` |
| Unknown field | the field | `Extra inputs are not permitted` |
| Insufficient credits | absent | Returned as `400` |

This route runs on paid API keys.

## Specs at a glance

| | |
| - | - |
| Duration | 5 to 15 seconds |
| Resolution | `480p`, `768p`, `1080p` or `2k` (`1080p` and `2k` at 3× the `768p` rate) |
| Aspect ratio | Six ratios, plus `adaptive` for `reference_to_video`; `image_to_video` follows the first frame |
| Jobs | Run to completion once submitted |
| Callbacks | Delivered once; poll as the fallback |
| API keys | Paid API keys |

<CardGroup>
  <Card title="Get an API key" icon="key" href="https://platform.heygen.com/api-keys">
    Create a key and check your usage.
  </Card>

  <Card title="HeyGen Avatar" icon="user" href="/avatar-v">
    Animate a look you own from a script, with Avatar V, IV and III.
  </Card>
</CardGroup>


# HeyGen Voice
Source: https://heygen-1fa696a7.mintlify.app/docs/models/heygen-voice

HeyGen Voice is HeyGen's in-house voice model: instant voices from one recording, professional clones trained per speaker, and completed or streaming speech from either.

<img alt="" />

HeyGen Voice is HeyGen's in-house voice model. It learns one speaker's voice, then speaks your text in that voice. Make a voice in one of two modes; both speak through the same endpoints.

## Choose a mode

| | Instant <sup>New</sup> | Professional |
| - | - | - |
| `mode` | `instant` | `professional` |
| You give it | One recording. The first 3 minutes are used. | 1–10 recordings of the same speaker, 20+ minutes in total |
| Ready | Usually within seconds | After training. Poll until `ACTIVE`. |
| Retrain | No. Create a new voice. | Yes, with new recordings |
| Speech controls | `expressiveness_boost` | `seed`, `speed`, `pitch_shift`, `pitch_variance`, `<break>` pauses |
| Cost to create | Free during the preview | One purchased voice clone slot per voice |
| Guide | [Instant Voice Clone](/docs/voices/heygen-voice-instant-clone) | [Professional Voice Clone](/docs/voices/professional-voice-clone) |

## Endpoints

| Endpoint | Purpose |
| - | - |
| [`POST /v3/models/audio/voices`](/reference/create-or-retrain-an-audio-voice) | Create an instant or professional voice, or retrain a professional voice. |
| [`GET /v3/models/audio/voices/{voice_id}`](/reference/get-an-audio-voice) | Read a voice: `mode`, `status`, and `failure_reason`. |
| [`GET /v3/models/audio/voices`](/reference/list-audio-voices) | List your instant and professional voices, newest first, or HeyGen's public voices with `type=public`. Each `ACTIVE` voice has a `preview_audio_url`. |
| [`DELETE /v3/models/audio/voices/{voice_id}`](/reference/delete-an-audio-voice) | Delete a voice. |
| [`POST /v3/models/audio/tts`](/reference/generate-model-speech) | Generate one completed WAV. |
| [`POST /v3/models/audio/tts/stream`](/reference/stream-speech) | Stream audio parts as they are generated. |

Send your API key in the `X-Api-Key` header; create one in the [API keys page](https://platform.heygen.com/api-keys). Voices belong to the workspace that created them.

## Voice slots

| | |
| - | - |
| Instant voice | Free to create during the preview. Counts toward the workspace's voice clone allowance. |
| Professional voice | One purchased voice clone slot per voice, bought on the [Usage page](https://platform.heygen.com/usage). Five pooled trainings per slot per monthly billing period, initial training included. Failed trainings are free. |

A professional voice beyond the workspace's slot limit, for example after a slot add-on lapses, returns `voice_expired` on speech. Add a slot or delete another professional voice and it works again immediately.

## The voice catalog

The [voice catalog](/docs/voices/overview) (`/v3/voices`) is a separate surface: 300+ stock voices and [designed voices](/docs/voices/design-voices). Catalog voices speak through [Third Party Speech](/docs/voices/speech), which also runs on the HeyGen Voice engine, and in [`POST /v3/videos`](/reference/create-video). HeyGen Voice `voice_id`s speak through [Text to Speech](/docs/voices/heygen-voice-speech).

<CardGroup>
  <Card title="Instant Voice Clone" icon="bolt" href="/docs/voices/heygen-voice-instant-clone">
    One recording, ready in seconds.
  </Card>

  <Card title="Professional Voice Clone" icon="microphone" href="/docs/voices/professional-voice-clone">
    Train from 20+ minutes of recordings.
  </Card>

  <Card title="Text to Speech" icon="waveform-lines" href="/docs/voices/heygen-voice-speech">
    Completed or streaming speech from any `ACTIVE` voice.
  </Card>
</CardGroup>


# On Brand
Source: https://heygen-1fa696a7.mintlify.app/docs/on-brand

Make HeyGen output match your brand over the API. A brand kit carries your colors, fonts, and logo; a brand glossary controls how your custom terms are spoken and translated. Learn which endpoints accept each.

<img alt="" />

Two workspace records control how on-brand a generated video is, and they cover different halves of the problem:

* **[Brand kit](/docs/brand-kits)** — how the video **looks**. Your colors, fonts, and logo, applied to scene backgrounds, text treatments, chart palettes, and logo placement. Import one from a website with `POST /v3/brand-kits`.
* **[Brand glossary](/docs/brand-glossary)** — how the video **sounds** and **reads**. Your custom terms with the pronunciation each one should get, plus do-not-translate terms and forced translations for translation, so `HeyGen` is spoken `hey-jen` and stays `HeyGen` in every target language. Create one with `POST /v3/brand-glossaries`.

Each record has its own page covering its whole life — create it, read it, edit it, apply it. This page is the map: which endpoint accepts which ID, and how the two fields behave on a request.

Both can also be authored in the HeyGen web app under **Brand Kit**. Records made in the app are readable and usable over the API, and records made over the API stay editable in the app.

## Which endpoint takes which

Video Agent is the only consumer of a brand kit — and, because the agent both composes the scenes and voices the narration, the one endpoint that accepts both IDs on the same request. Everywhere else the two IDs go to different endpoints: everything that turns a written script into speech takes a glossary.

| Endpoint | Field | What it does |
| - | - | - |
| [`POST /v3/video-agents`](/reference/create-video-agent-session) | `brand_kit_id` | Applies your colors, fonts, and logo to every scene the agent composes. |
| [`POST /v3/video-agents`](/reference/create-video-agent-session) | `brand_glossary_id` | Sets pronunciation in the narration the agent writes and voices. Combines freely with `brand_kit_id` on the same request. |
| [`POST /v3/video-agents/{session_id}`](/reference/send-message-or-request-revision) | `brand_kit_id` | Re-brands an [interactive session](/docs/interactive-sessions) on a follow-up message, without starting over. The glossary is the one set when the session was created. |
| [`POST /v3/videos`](/reference/create-video) with `"type"` of `studio`, `avatar`, or `image` | `brand_glossary_id` | Sets pronunciation wherever audio is synthesized from a `script`: every [Studio](/studio-videos) scene, or the single scene of an `avatar` or `image` video. Not accepted on `cinematic_avatar`, which has no script or voice. |
| [`POST /v3/videos/batches`](/reference/create-video-batch) | `brand_glossary_id` | Same, set per item inside `videos`. Batch items are `avatar` or `image`; a `studio` item is rejected by this endpoint. |
| [`POST /v3/templates/{template_id}`](/reference/generate-video-from-template) | `brand_glossary_id` | Sets pronunciation in the speech generated for a [template](/templates). |
| [`POST /v3/video-translations`](/reference/create-video-translation) | `brand_glossary_id` | Fixes how your terms are carried into the [translated](/docs/video-translate) script. |
| [`POST /v3/video-translations/batches`](/reference/create-video-translation-batch) | `brand_glossary_id` | Same, set per item inside `video_translations`. |
| [`POST /v3/video-translations/proofreads`](/reference/create-proofread-session) | `brand_glossary_id` | Applies your terms to the editable subtitles a proofread session returns. |

A brand kit reaches a Studio or Templates video the other way around: build the look into the composition or the template itself, then use a glossary for the audio.

### Scope of each field

`brand_kit_id` and `brand_glossary_id` are both **global to the request** — one value per call, applied to everything it produces. In a translation batch or a video batch the glossary is per item, so a single batch can send different glossaries to different videos. On [`POST /v3/video-agents`](/reference/create-video-agent-session) the two ride the same request and divide the work cleanly: the kit shapes what you see, the glossary shapes what you hear.

On `POST /v3/videos`, `brand_glossary_id` applies to the `studio`, `avatar`, and `image` composition types. It takes effect only where speech is synthesized from a `script`, so a caller-supplied `audio_url` or `audio_asset_id` is unaffected, and captions keep the original script wording either way. `cinematic_avatar` does not accept the field, because it has no script or voice: motion and speech are driven by the `prompt` and its reference assets.

## Both IDs are workspace-scoped

A brand kit or glossary is visible only to API keys belonging to the workspace that owns it. IDs are 32-character hex strings with no prefix:

```json theme={null}
{
  "brand_kit_id": "3f9a1c47b8e24d5fa0c61e8b7d24f6a1",
  "brand_glossary_id": "8c2d5e91a47b4f3c8d1e6a9b2f5c7d40"
}
```

An ID that does not exist in the caller's workspace is rejected when the request is made, so a bad ID costs you nothing — no video is created and no credits are consumed. If a valid-looking ID is rejected, confirm the API key belongs to the same workspace that owns the record.

## Combining brand with a style

For Video Agent, `brand_kit_id` and `style_id` are independent and compose: a [style](/docs/styles-and-references) picks the look — scene layout, pacing, aesthetic — and the brand kit makes that look yours. Use a style for the shape of the video and a brand kit to make it recognizably you.


# Prompting Guide
Source: https://heygen-1fa696a7.mintlify.app/docs/prompting-guide

Write Video Agent prompts that land on the first cut. Set the duration, direct the look with a style paragraph, and paste a script for scene-by-scene control.

<img alt="" />

The prompt is the whole interface to the [Video Agent](/docs/video-agent). The agent makes every decision you leave open, so the more direction you give, the closer the first cut lands to what you pictured. A good prompt reads like a creative brief: what the video is, how long it runs, and what it should look like.

This page builds one real prompt step by step — and ends with the video it produced.

## Put the duration in the prompt

The agent paces scenes to the length you ask for. Lead with it: *"Make a 30-second portrait real estate market update…"* produces a video paced to 30 seconds, scene by scene.

## Add a style paragraph

Describe the video you want, then add a short style paragraph: what the graphics should look like, the colors, the energy, how things move. The agent reads it and makes every visual decision through it — anything you leave out, it decides for you.

```text Example prompt theme={null}
Make a 45-second portrait video introducing our new app to Gen Z.

Style: Arcade Cabinet – Pixel Power-Up. CRT Black #111111, Neon Cyan #00E5FF,
Electric Magenta #FF2DAA, Power-Up Yellow #FFD400, Pixel Grass Green #4CFF4C.
Chunky pixel art, scanlines, glowing vector HUD, and bold bitmap typography.
Sprites pop in with 8-bit bounce, score counters tick rapidly, and power-ups
burst into pixel particles. Transitions are CRT glitches, screen wipes, and
coin-in flashes. Playful, nostalgic, and unmistakably arcade.
```

A style paragraph that works has a consistent anatomy: a **name** for the style, the **exact palette** (hex codes and all), the **art direction**, **how things move**, **what the transitions are**, and one closing line for the **vibe**. Five or six sentences, and every graphic in the video has a rulebook — because scenes are [built in code with Hyperframes](/docs/video-agent#powered-by-hyperframes), the agent follows it literally. Prefer a pre-built look instead? Pass a `style_id` — see [Styles & References](/docs/styles-and-references).

## Paste your script for exact control

If you already have a script, paste the whole thing in and the agent follows it scene by scene, building the visuals around your exact words. Combine it with the style paragraph and a duration for the tightest brief:

```text Example prompt with script theme={null}
Make a 30-second portrait real estate market update for Austin, Texas,
presented by Ava. Follow the script below exactly, scene by scene. Use motion
graphics for every stat, and stock footage of the Austin skyline and
neighborhoods for texture between them.

Style: Elevated Estates – Quiet Luxury. Ivory #F7F4EE, Charcoal Ink #1E1E1C,
Sage #A6BB94, Deep Forest #24352A, Brushed Brass #C9A227. Editorial serif
headlines over generous whitespace, hairline rules, small-caps labels, and
full-bleed architectural photography with soft depth. Numbers count up gently,
chart lines draw themselves in, and photography drifts in slow parallax.
Transitions are soft crossfades, ivory paper wipes, and hairline reveals.
Calm, polished, and quietly luxurious.

Script:

Scene 1 (0-5s) - Ava on camera, skyline behind her.
"Austin, here's your market minute for July."

Scene 2 (5-12s) - Motion graphic: median price counts up to $450K, sage trend
line drawing upward.
"The metro median now sits at four hundred fifty thousand, up one percent from
last summer, and prices are firming."

Scene 3 (12-19s) - Motion graphic: inventory bars stepping down, brass accent
on the final bar.
"Inventory tells the story. Active listings are down fifteen percent from a
year ago, at four and a half months of supply."

Scene 4 (19-25s) - Stock footage of a front door and porch, stat card
overlay: 24 DAYS.
"And well-priced homes are moving in about twenty-four days."

Scene 5 (25-30s) - Ava on camera, hairline rule and small-caps CTA card.
"The window favors sellers again. Thinking about a move? Let's talk before fall."
```

## The output

This is the video that prompt produced — one prompt, one pass:

<Frame>
  <video>
    <source type="video/mp4" />
  </video>
</Frame>

The first cut is a draft. To close the gap to post-ready, keep talking to the agent in [chat mode](/docs/interactive-sessions) — revise a single scene ("change the background of scene two") while every other scene holds still. Prompt for the 90, edit for the 10.

## More levers

1. **Attach reference files.** Pass slides, images, or documents in the `files` array — the agent folds them into the video as visual context or content sources. See [Upload Assets](/docs/upload-assets).
2. **Pin a specific avatar or voice** with `avatar_id` (see [Avatars](/docs/avatars)) and `voice_id` (see [Browse Voices](/docs/voices/search-voices)) for consistency, or omit them to let the agent choose.
3. **Apply your brand once** with `brand_kit_id` from [`GET /v3/brand-kits`](/reference/list-brand-kits) — colors, fonts, and logo ship on-brand by default on every video after.
4. **Set `orientation`** when you know the target platform (`"portrait"` for mobile/social, `"landscape"` for presentations).
5. **Review the plan before it builds.** With `"mode": "chat"`, the agent comes back with a scene-by-scene plan you can push back on before production starts. See [Interactive Sessions](/docs/interactive-sessions).

For more worked examples, see the [Video Agent prompt guide](https://www.heygen.com/blog/video-agent-prompt-guide) on the blog.


# Quick Start
Source: https://heygen-1fa696a7.mintlify.app/docs/quick-start

Generate your first AI video with the HeyGen API in minutes: authenticate, send one request, and get back an MP4.

<video>
  <source type="video/mp4" />
</video>

## What you can build

<CardGroup>
  <Card title="Create Your Avatar" href="/docs/create-avatar">
    A digital twin from video, or an avatar from one photo.
  </Card>

  <Card title="Video Agent" href="/docs/video-agent">
    Prompt to finished video. Edit single scenes after.
  </Card>

  <Card title="HeyGen Video" href="/docs/models/heygen-video">
    Text, image, or reference to a 5–15s clip, up to 2K. **New.**
  </Card>

  <Card title="Avatar Video" href="/generate-avatar-video">
    Your avatar, voice, and script, up to Avatar V.
  </Card>

  <Card title="HeyGen Image" href="/docs/models/heygen-image">
    Your identity, a new look. Portraits from reference photos.
  </Card>

  <Card title="Templates" href="/create-template">
    Turn any video into a template, then one call per viewer. **New.**
  </Card>

  <Card title="Look Packs" href="/docs/avatar-look-packs">
    Dress an avatar in a curated set of looks.
  </Card>

  <Card title="HyperFrames" href="/hyperframes">
    HTML, CSS, and JS to motion-graphics video.
  </Card>

  <Card title="Instant Voice Clone" href="/docs/voices/heygen-voice-instant-clone">
    One recording to a HeyGen Voice in seconds. **New.**
  </Card>

  <Card title="Professional Voice Clone" href="/docs/voices/professional-voice-clone">
    Studio-grade voice trained on 20+ minutes of audio.
  </Card>

  <Card title="Text to Speech" href="/docs/voices/heygen-voice-speech">
    Completed or streaming speech from your HeyGen Voice. **New.**
  </Card>

  <Card title="Video Translation" href="/docs/video-translate">
    175+ languages with voice cloning and lip-sync.
  </Card>
</CardGroup>

## Start with your agent

Paste this into [Claude Code](https://claude.com/claude-code), [Codex](https://openai.com/codex/), or Cursor. It reads the whole API, sets up your key, and makes your first video with you.

```text Prompt for your agent wrap theme={null}
I want to build with the HeyGen API. Run the commands for me where you can, explain each step in one plain sentence, and when I have to do something myself tell me exactly what and wait for me.

Read these first and follow them exactly:
- https://developers.heygen.com/llms.txt (index of every guide and endpoint)
- https://developers.heygen.com/docs/for-ai-agents.md (rules for agents)

Then:
1. API key. Look for HEYGEN_API_KEY in my environment. If it is missing, send me to https://platform.heygen.com/api-keys to create one and have me export it in my terminal myself. Never ask me to paste the key into this chat. Confirm it works with GET /v3/users/me.
2. Ask me what I want to make, and pick the right endpoint from the docs (Video Agent, HeyGen Video, avatar video, HeyGen Image, templates, voice cloning, text to speech, or translation).
3. Make the first call, poll until it finishes, and give me the result URL.
```

## Your first video

<CardGroup>
  <Card title="Get your API key" icon="key" href="https://platform.heygen.com/api-keys">
    Create a key in the API dashboard. Every request below needs it.
  </Card>

  <Card title="Try it in the Playground" icon="play" href="/reference/create-video">
    Fire a real request from your browser before writing any code.
  </Card>
</CardGroup>

<Info>
  **Base URL** `https://api.heygen.com` · **Auth header** `X-Api-Key: <your-key>`
</Info>

<Steps>
  <Step title="Authenticate" icon="key">
    Create a key in the [API keys page](https://platform.heygen.com/api-keys). For key rotation, see the [API Key guide](/docs/api-key).

    ```bash theme={null}
    export HEYGEN_API_KEY="your-api-key-here"
    ```
  </Step>

  <Step title="Create a video" icon="wand-magic-sparkles">
    Send a prompt to the [Video Agent](/reference/create-video-agent-session). It scripts, picks the avatar and voice, and renders.

    <Tabs>
      <Tab title="curl">
        ```bash theme={null}
        curl -X POST "https://api.heygen.com/v3/video-agents" \
          -H "X-Api-Key: $HEYGEN_API_KEY" \
          -H "Content-Type: application/json" \
          -d '{"prompt": "A presenter explaining our product launch in 30 seconds"}'
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        import requests

        resp = requests.post(
            "https://api.heygen.com/v3/video-agents",
            headers={"X-Api-Key": HEYGEN_API_KEY},
            json={"prompt": "A presenter explaining our product launch in 30 seconds"},
        )
        session_id = resp.json()["data"]["session_id"]
        ```
      </Tab>

      <Tab title="Node.js">
        ```javascript theme={null}
        const resp = await fetch("https://api.heygen.com/v3/video-agents", {
          method: "POST",
          headers: {
            "X-Api-Key": process.env.HEYGEN_API_KEY,
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            prompt: "A presenter explaining our product launch in 30 seconds",
          }),
        });
        const { session_id } = (await resp.json()).data;
        ```
      </Tab>
    </Tabs>

    ```json Response theme={null}
    { "data": { "session_id": "sess_abc123", "status": "generating", "video_id": null } }
    ```

    <Tip>
      Watch it build live at `https://app.heygen.com/video-agent/{session_id}`.
    </Tip>
  </Step>

  <Step title="Get the result" icon="circle-check">
    Poll the session for a `video_id`, then the video for its `video_url`. Or skip polling with a [webhook](/docs/webhooks) via `callback_url`.

    <Tabs>
      <Tab title="Python">
        ```python theme={null}
        import time

        # 1. Wait for the video_id to be assigned
        video_id = None
        while not video_id:
            sess = requests.get(
                f"https://api.heygen.com/v3/video-agents/{session_id}",
                headers={"X-Api-Key": HEYGEN_API_KEY},
            ).json()["data"]
            video_id = sess.get("video_id")
            if not video_id:
                time.sleep(5)

        # 2. Poll the video until it's done
        while True:
            video = requests.get(
                f"https://api.heygen.com/v3/videos/{video_id}",
                headers={"X-Api-Key": HEYGEN_API_KEY},
            ).json()["data"]
            if video["status"] in ("completed", "failed"):
                break
            time.sleep(10)

        print(video["video_url"])
        ```
      </Tab>

      <Tab title="curl">
        ```bash theme={null}
        # 1. Session → video_id
        curl "https://api.heygen.com/v3/video-agents/sess_abc123" \
          -H "X-Api-Key: $HEYGEN_API_KEY"

        # 2. video_id → video_url
        curl "https://api.heygen.com/v3/videos/vid_xyz789" \
          -H "X-Api-Key: $HEYGEN_API_KEY"
        ```
      </Tab>
    </Tabs>

    ```json Response (completed) theme={null}
    { "data": { "id": "vid_xyz789", "status": "completed", "video_url": "https://files.heygen.ai/video/vid_xyz789.mp4", "duration": 32.5 } }
    ```
  </Step>
</Steps>

## Working from an agent or terminal?

Skip the raw HTTP. Both surfaces wrap the same API.

<CardGroup>
  <Card title="MCP Server" icon="plug" href="/mcp/overview">
    Plug HeyGen into Claude, Cursor, or any MCP-capable agent. It handles the calls for you.
  </Card>

  <Card title="CLI" icon="terminal" href="/cli">
    `heygen video create`, `heygen video download`. Scriptable from any shell or CI job.
  </Card>
</CardGroup>

## Build with your stack

<CardGroup>
  <Card title="Webhooks" icon="bell" href="/docs/webhooks" />

  <Card title="Authentication" icon="lock" href="/docs/api-key" />

  <Card title="Usage Limits" icon="gauge" href="/docs/usage-limits" />
</CardGroup>

<Note>
  Migrating from **v1/v2**? Supported until **October 31, 2026**. See the [version comparison](/endpoint-version-comparison).
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Video status is failed" icon="circle-xmark">
    Inspect `failure_code` and `failure_message` on [`GET /v3/videos/{video_id}`](/reference/get-video). Full catalog in [Error Codes](/docs/error-codes).
  </Accordion>

  <Accordion title="401 Unauthorized" icon="key">
    Confirm the `X-Api-Key` header is set and the key is active in the [API keys page](https://platform.heygen.com/api-keys).
  </Accordion>

  <Accordion title="429 Too Many Requests" icon="gauge-high">
    Rate or concurrency limit hit. Respect `Retry-After` and back off. Enterprise plans get higher limits; see [Usage Limits](/docs/usage-limits).
  </Accordion>

  <Accordion title="400 download_failed" icon="link-slash">
    A URL you passed couldn't be fetched. It must be publicly accessible and point directly at the file.
  </Accordion>
</AccordionGroup>


# Slack Integration
Source: https://heygen-1fa696a7.mintlify.app/docs/slack

Connect HeyGen to Slack for video render notifications, agent triggers, and team-level activity feeds. Setup takes a few minutes with no code required.

<img alt="" />

Transform your Slack messages into professional AI-generated videos, instantly.

## What is HeyGen for Slack?

The HeyGen Slack app brings the power of AI video generation directly into your workspace. Create professional videos from text prompts without leaving Slack — perfect for team updates, tutorials, announcements, and more.

## Features

* **Instant video creation** - @mention HeyGen with your video idea and get a video in minutes
* **Emoji reactions** - React to any message with 🎥 to turn it into a video
* **Message curation** - Use `/heygen-curate` to find and compile top messages into videos
* **Personal accounts** - Connect your own HeyGen account to use your credits and avatars
* **Rich previews** - HeyGen video links automatically unfurl with thumbnails and metadata

## Installation

### Prerequisites

* **Slack workspace admin permissions** to install apps
* **A HeyGen account** with available video credits ([sign up here](https://app.heygen.com))
* Your HeyGen **username** and **space ID** ready

### Step 1: Install the app

1. Go to the [HeyGen Slack App](https://slack.com/oauth/v2/authorize?client_id=2341957757140.9185742217618\&scope=app_mentions:read,channels:history,channels:read,chat:write,commands,files:read,files:write,groups:history,groups:read,im:history,im:read,im:write,links:read,links:write,mpim:history,mpim:read,reactions:read,users:read\&user_scope=openid,profile) in the Slack App Directory
2. Click **Add to Slack**
3. Select your workspace and click **Allow**

### Step 2: Connect your HeyGen account

After installation, you'll be redirected to connect your HeyGen account:

* **If you're already logged into HeyGen**: Installation completes automatically. You're done!
* **If you're not logged in**: You'll be redirected to HeyGen to log in, then complete the setup by selecting which HeyGen space to use

That's it! The HeyGen bot is now available in your workspace.

## How to use

### Method 1: @mention the bot

Simply @mention HeyGen with your video idea:

```text theme={null}
@HeyGen Create a welcome video saying "Welcome to our team! We're excited to have you here."
```

The bot will:

1. Acknowledge your request
2. Generate the video using your HeyGen account
3. Post the finished video in the thread

### Method 2: React with 🎥 emoji

Convert any message into a video by reacting with the camera emoji:

1. Find a message you want to turn into a video
2. Click **Add reaction** (or press `R`)
3. Choose the 🎥 `:movie_camera:` emoji

The bot will use the message text as the video script.

**Tip:** You can also use a custom `:heygen-video:` emoji if your workspace has one.

**Note:** There's a 5-minute cooldown per message to prevent duplicate videos.

### Method 3: Curate channel messages

Use the `/heygen-curate` slash command to find and compile top messages:

```text theme={null}
/heygen-curate [#channel] [--notify] [--days N]
```

**Examples:**

```text theme={null}
/heygen-curate
/heygen-curate #marketing --days 7 --notify
```

This will:

* Analyze recent messages in the channel (default: last 7 days)
* Score messages based on reactions, replies, and engagement
* Present the top 3 messages
* Optionally notify the thread with `--notify`

## Personal account linking

By default, videos use the workspace's HeyGen account. Team members can link their personal HeyGen accounts to use their own credits and avatars.

### Why link your account?

* Videos you request will use and be saved on **your HeyGen account**
* You'll use **your video credits** and **your avatars**
* Other team members continue using the workspace default

### How to link your account

1. **Visit your HeyGen account settings** at [app.heygen.com](https://app.heygen.com/settings?from=\&nav=General)
2. Navigate to **Connections** → **Slack**
3. Click **Link your Slack account**
4. Sign in to Slack and authorize the connection

Once linked, all videos you create will use your personal HeyGen account.

### Check your link status

1. On the [settings](https://app.heygen.com/settings?from=\&nav=Connections) menu, Make sure you are on **Connections**
2. Check to see if the button is grayed out or says *unlink* on the Slack card

If the button is grayed out or says *unlink*, your heygen account and slack accounts are connected.

### Unlink your account

To stop using your personal account and switch back to the workspace default:

1. Go to your [**HeyGen account settings**](https://app.heygen.com/settings?from=\&nav=General)
2. **Connections** → **Slack**
3. Click **Unlink**

## Rate limits

To ensure fair usage, the following limits apply:

| Action | Limit |
| - | - |
| Video creation | 50 per minute, 500 per hour (per workspace) |
| /heygen-curate command | 30 per minute, 300 per hour (per workspace) |
| Emoji reaction cooldown | 1 video per message every 5 minutes |

If you hit a rate limit, wait a few minutes and try again. You'll see a message like:

<Info>
  Rate limit reached. Please wait a moment and try again.
</Info>

## Troubleshooting

### "Workspace not installed" error

**Problem:** The bot responds with "Workspace not installed. Please reinstall the HeyGen app."

**Solution:**

* The app may have been uninstalled or credentials revoked
* Reinstall the app following the [Installation](https://docs.heygen.com/docs/slack#installation) steps
* Make sure a workspace admin completes the HeyGen account connection

### Bot doesn't respond to @mentions

**Problem:** You @mentioned the bot but nothing happened.

**Check:**

* The bot must be invited to the channel (`/invite @HeyGen`)
* You have available HeyGen video credits
* You're not hitting rate limits (see [Rate limits](https://docs.heygen.com/docs/slack#rate-limits))
* Check the thread for error messages

### Video generation failed

**Problem:** The bot acknowledged your request but the video never arrived.

**Possible causes:**

* **Insufficient credits** - Check your HeyGen account balance
* **Invalid script** - Make sure your prompt is clear and complete
* **API errors** - Try again in a few minutes

**Get help:** Send a direct message to the bot for support information.

### Emoji reaction doesn't work

**Problem:** You reacted with 🎥 but no video was created.

**Check:**

* You're using the correct emoji: 🎥 `:movie_camera:` or `:heygen-video:`
* The message hasn't had a video generated in the last 5 minutes (cooldown)
* The message has enough text to create a video (minimum \~10 words recommended)

### "Invalid HeyGen credentials" error

**Problem:** Videos aren't generating and you see credential errors.

**Solution:**

* Your HeyGen username or space ID may be incorrect
* A workspace admin should:
  1. Go to your Slack workspace settings
  2. **Apps** → **HeyGen** → **Configuration**
  3. Update the HeyGen credentials
  4. Save changes

## FAQ

### How much does it cost?

The HeyGen Slack app is free to install. Video generation uses HeyGen credits from your account:

* **Workspace default**: Uses the account configured during installation
* **Personal linking**: Uses your own HeyGen account and credits

### Can I choose which avatar to use?

By default, videos use your HeyGen account's default avatar. To customize:

* Link your personal HeyGen account (see [Personal account linking](https://app.heygen.com/settings?from=\&nav=Connections))
* By default, Video Agent will auto-select most recently used avatar from your workspace
* The bot will automatically use that avatar for your videos

### Where are videos stored?

Videos are:

1. Created in your HeyGen workspace (visible in your [HeyGen dashboard](https://app.heygen.com))
2. Uploaded directly to Slack (stored in your Slack workspace files)
3. Accessible via the Slack message thread

### Can I use this in private channels?

Yes! Invite the HeyGen bot to any channel:

```text theme={null}
/invite @HeyGen
```

The bot works in:

* Public channels
* Private channels
* Direct messages
* Group messages

### Is my data secure?

* **Message content** is sent to HeyGen's API only when you explicitly request a video
* **Credentials** are encrypted and stored securely
* The bot only reads messages where it's @mentioned or reacted to
* See [HeyGen's security policies](https://heygen.com/security) for details

### How do I uninstall?

To remove the HeyGen app:

1. Go to your **Slack workspace settings**
2. **Apps** → **HeyGen**
3. Click **Remove App**
4. Confirm removal

Your workspace data will be marked as deactivated but not deleted (for potential reinstallation).

## Tips & best practices

### Writing great video prompts

**Do:**

* Be specific and clear: *"Create a welcome video introducing our new design system update"*
* Include context: *"Make a tutorial video explaining how to use the new login flow"*
* Keep it concise: Aim for 30-90 seconds of content

**Don't:**

* Be too vague: ~~"Make a video"~~
* Use very long scripts: Messages over \~500 words may be truncated
* Include formatting: The bot uses plain text, not markdown

### Using /heygen-curate effectively

The curate command works best with:

* **Active channels** with regular discussion
* **Time range**: Last 24-48 hours typically has the best content
* **Engagement metrics**: Reactions and replies indicate valuable messages

**Pro tip:** Use `--notify` in channels where you want to create visibility around the curation process.

### Managing workspace credits

To avoid surprise credit usage:

* Set up **usage alerts** in your HeyGen account
* Encourage personal account linking for team members who create many videos
* Monitor usage in your [HeyGen analytics dashboard](https://app.heygen.com/analytics)

## Support

Need help?

* **Documentation**: [docs.heygen.com/slack](https://docs.heygen.com/slack)
* **Email**: [support@heygen.com](mailto:support@heygen.com)
* **Community**: Join our community for tips and discussions


# Stripe Projects
Source: https://heygen-1fa696a7.mintlify.app/docs/stripe-projects

Provision a HeyGen API key directly from the Stripe CLI. Stripe handles billing and identity; HeyGen creates the account, applies your budget for API credit, and returns the key — no sign-up screen, no card handed to the agent.

<img alt="" />

[Stripe Projects](https://docs.stripe.com/projects) lets an agent discover, provision, and pay for the services it needs to ship — entirely from the command line. HeyGen is available as one of those services, so an agent can stand up video generation the same way it provisions a database or a host.

You give the agent a budget, not your card. Stripe handles identity and billing; HeyGen creates (or links) the account, applies your budget for API credit, and returns an API key.

<Info>
  **What you'll get:** a HeyGen API key, provisioned and billed through Stripe, written to your project's `.env` and ready to use with the [HeyGen CLI](/cli) or API.
</Info>

<Warning>
  Provisioning a paid service spends real money against the budget you set. You control the spending cap, and charges are billed through your Stripe account.
</Warning>

## How it works

1. **Discover.** The agent finds `heygen/api` in the Stripe Projects service catalog.
2. **Authorize.** Stripe passes the user's identity to HeyGen, which creates a new account or links an existing workspace and returns API credentials.
3. **Pay.** A Stripe payment token funds the account up to a budget you set — the agent never sees a card number.
4. **Generate.** The agent uses the returned API key to call the HeyGen API and create videos.

## Prerequisites

A Stripe account with a valid payment method (you can also add a card during provisioning via Stripe Checkout). Then install the CLI and initialize a project:

```bash theme={null} theme={null}
brew install stripe/stripe-cli/stripe   # Stripe CLI
stripe plugin install projects          # Projects plugin
stripe login                            # authenticate (opens browser)
stripe projects init                    # initialize a project in the current directory
```

## Provision a key

### Interactive

Walks you through the service summary, accepting HeyGen's Terms and Privacy Policy, confirming the paid service, and setting up billing. It links your HeyGen account by your Stripe email, provisions the key, and writes it to `.env`.

```bash theme={null} theme={null}
stripe projects add heygen/api
```

On success the key is stored in `.env` (shown masked, never printed in full):

```text theme={null} theme={null}
✓ Connected HeyGen account (you@example.com)
○ Provisioning heygen/api...
  ├─ ✓ Resource requested
  ├─ ✓ Resource provisioned
  ├─ ✓ Credentials synced
  └─ ✓ Project updated
● heygen/api ready
  HEYGEN_HEYGEN_API_KEY=sk_••••••••
```

### Non-interactive (agents / CI)

Confirm the paid service and accept the terms of service up front. Billing must already be configured (`stripe projects billing add`) — it can't be set up non-interactively.

```bash theme={null} theme={null}
stripe projects add heygen/api --json --yes --confirm-paid-service --accept-tos
```

If no payment method is on file, the CLI returns `PAYMENT_METHOD_REQUIRED` with a Stripe Checkout URL to add one.

## Use the API key

The key lives in your project's `.env`. Load it and call HeyGen with the [CLI](/cli):

```bash theme={null} theme={null}
curl -fsSL https://static.heygen.ai/cli/install.sh | bash   # install the HeyGen CLI
set -a && source .env && set +a                             # load the key from .env
export HEYGEN_API_KEY="$HEYGEN_HEYGEN_API_KEY"              # the CLI reads HEYGEN_API_KEY
heygen avatar list
heygen video-agent create --prompt "30-second product demo" --wait
heygen video get <video-id>
```

<Note>
  The key is read from `.env` and never shown on screen. In a new shell, re-run `set -a && source .env && set +a` to load it again.
</Note>

## Manage the project

```bash theme={null} theme={null}
stripe projects status            # providers, services, plans
stripe projects env               # show injected env vars
stripe projects billing show      # billing state
stripe projects rotate heygen-api # rotate the API key
stripe projects remove heygen-api # remove the service (revokes the key)
```

## Take it all the way to a video

Once your agent has a key, it has a production studio — not just a single clip. Pair HeyGen avatars and voices with [HyperFrames](/hyperframes), HeyGen's open-source framework for building videos as HTML and rendering them to MP4. HyperFrames runs locally with no account or API key required, so there's nothing extra to provision: point it at your HeyGen output and the agent authors the whole thing — presenter, captions synced to the audio, motion graphics, scenes, and B-roll — then renders a finished MP4 to share.


# Styles & References
Source: https://heygen-1fa696a7.mintlify.app/docs/styles-and-references

Steer HeyGen AI video output with style presets and reference images. Apply cinematic looks, brand colors, and visual consistency across generations.

<img alt="" />

Styles are curated visual templates that control how the [Video Agent](/docs/video-agent) composes your video — scene layout, script structure, pacing, and overall aesthetic. Apply a style by passing its `style_id` when creating a video. For a fully custom look, you can also describe a style directly in your prompt — see the [Prompting Guide](/docs/prompting-guide).

## List available styles

Full schema: [`GET /v3/video-agents/styles`](/reference/list-video-agent-styles). Returns a paginated list of styles — each includes a name, thumbnail, preview video, tags, and aspect ratio.

### Query parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `tag` | string | — | Filter by tag. Available tags: `cinematic`, `retro-tech`, `iconic-artist`, `pop-culture`, `handmade`, `print`. |
| `limit` | integer | 20 | Results per page (1–100). |
| `token` | string | — | Opaque cursor from a previous response's `next_token` for pagination. |

### Example request

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.heygen.com/v3/video-agents/styles?tag=cinematic&limit=5" \
    -H "X-Api-Key: $HEYGEN_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  resp = requests.get(
      "https://api.heygen.com/v3/video-agents/styles",
      headers={"X-Api-Key": HEYGEN_API_KEY},
      params={"tag": "cinematic", "limit": 5},
  )
  styles = resp.json()["data"]
  for style in styles:
      print(style["style_id"], style["name"])
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "data": [
    {
      "style_id": "style_noir_detective",
      "name": "Noir Detective",
      "thumbnail_url": "https://files.heygen.ai/styles/noir_thumb.jpg",
      "preview_video_url": "https://files.heygen.ai/styles/noir_preview.mp4",
      "tags": ["cinematic"],
      "aspect_ratio": "16:9"
    },
    {
      "style_id": "style_retro_crt",
      "name": "Retro CRT",
      "thumbnail_url": "https://files.heygen.ai/styles/retro_crt_thumb.jpg",
      "preview_video_url": "https://files.heygen.ai/styles/retro_crt_preview.mp4",
      "tags": ["retro-tech"],
      "aspect_ratio": "16:9"
    }
  ],
  "has_more": true,
  "next_token": "eyJsYXN0X2lkIjoic3R5bGVfcmV0cm9fY3J0In0="
}
```

### Style object

| Field | Type | Description |
| - | - | - |
| `style_id` | string | Unique identifier. Pass this to [`POST /v3/video-agents`](/reference/create-video-agent-session) as `style_id`. |
| `name` | string | Display name of the style. |
| `thumbnail_url` | string \| null | Thumbnail image URL (public CDN). |
| `preview_video_url` | string \| null | Preview video URL (public CDN, mp4). |
| `tags` | array \| null | Tags for categorization (e.g. `cinematic`, `retro-tech`, `handmade`). |
| `aspect_ratio` | string \| null | Aspect ratio the style is designed for: `"16:9"`, `"9:16"`, or `"1:1"`. |

## Apply a style to a video

Pass the `style_id` when creating a video with the Video Agent:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/video-agents" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Explain the history of jazz music in 60 seconds",
    "style_id": "style_noir_detective"
  }'
```

The style influences the visual template the agent uses — scenes, transitions, text overlays, and pacing will follow the style's design system. Your prompt still controls the content and narration.

<Tip>
  Preview styles before using them. The `preview_video_url` on each style object shows a sample video rendered in that style — use it to pick the right look before generating.
</Tip>

## Pagination

The styles endpoint uses cursor-based pagination. When `has_more` is `true`, pass the `next_token` value as the `token` query parameter in your next request:

```bash theme={null}
# Page 1
curl "https://api.heygen.com/v3/video-agents/styles?limit=10" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

# Page 2
curl "https://api.heygen.com/v3/video-agents/styles?limit=10&token=eyJsYXN0X2lkIjo..." \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

## Filter by tag

Use the `tag` parameter to narrow results to a specific category:

| Tag | Description |
| - | - |
| `cinematic` | Film-inspired looks with dramatic lighting and composition. |
| `retro-tech` | Vintage technology aesthetics (CRT screens, pixel art, etc.). |
| `iconic-artist` | Styles inspired by iconic artistic movements. |
| `pop-culture` | Bold, colorful styles drawn from pop culture. |
| `handmade` | Handcrafted, organic textures (paper, watercolor, stop-motion). |
| `print` | Magazine, newspaper, and print-inspired layouts. |

```bash theme={null}
curl "https://api.heygen.com/v3/video-agents/styles?tag=handmade" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

## Using file references with styles

Styles and file attachments work together. Attach reference images or documents alongside a style to combine the style's visual template with your own content:

```json theme={null}
{
  "prompt": "Create a product demo using the attached screenshots",
  "style_id": "style_retro_crt",
  "files": [
    { "type": "url", "url": "https://example.com/screenshot-1.png" },
    { "type": "url", "url": "https://example.com/screenshot-2.png" }
  ]
}
```

The agent will render your screenshots within the retro CRT visual template, applying the style's transitions and framing to your content.


# Upload Assets
Source: https://heygen-1fa696a7.mintlify.app/docs/upload-assets

Upload images, audio, and video to HeyGen via the Assets API. Use uploaded assets as backgrounds, voice references, lipsync inputs, or photo avatar sources.

<img alt="" />

The Assets API lets you upload files to HeyGen and receive an `asset_id` you can reference in other endpoints — including [Video Agent](/docs/video-agent), [Avatar creation](/docs/create-avatar), [Video Translation](/docs/video-translate), and [Lipsync](/lipsync-speed).

There are two ways to upload:

* [`POST /v3/assets`](/reference/upload-asset) — a single `multipart/form-data` request. Simplest option, capped at **32 MB**.
* [Direct upload](#upload-large-files-direct-upload) — a presigned-URL flow for files larger than 32 MB, up to 200 MB per video, image, or PDF file and 1.5 GB per audio file. The file bytes go straight to storage and never pass through the API.

## Upload via `POST /v3/assets`

Full schema: [`POST /v3/assets`](/reference/upload-asset). Upload a file using `multipart/form-data` — the MIME type is auto-detected from file bytes.

### Constraints

| Constraint | Value |
| - | - |
| Max file size | 32 MB — for larger files, use [direct upload](#upload-large-files-direct-upload) |
| Max file size (direct upload) | 200 MB for video, image, PDF; 1.5 GB for audio |
| Supported images | png, jpeg |
| Supported video | mp4, webm |
| Supported audio | mp3, wav |
| Other | pdf |

### Example request

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://api.heygen.com/v3/assets" \
    -H "X-Api-Key: $HEYGEN_API_KEY" \
    -F "file=@./product-screenshot.png"
  ```

  ```python Python theme={null}
  import requests

  with open("product-screenshot.png", "rb") as f:
      resp = requests.post(
          "https://api.heygen.com/v3/assets",
          headers={"X-Api-Key": HEYGEN_API_KEY},
          files={"file": ("product-screenshot.png", f, "image/png")},
      )

  asset = resp.json()["data"]
  print(asset["asset_id"])
  ```

  ```javascript Node.js theme={null}
  const fs = require("fs");
  const FormData = require("form-data");

  const form = new FormData();
  form.append("file", fs.createReadStream("./product-screenshot.png"));

  const resp = await fetch("https://api.heygen.com/v3/assets", {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.HEYGEN_API_KEY,
      ...form.getHeaders(),
    },
    body: form,
  });
  const { data } = await resp.json();
  console.log(data.asset_id);
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "data": {
    "asset_id": "asset_abc123def456",
    "url": "https://files.heygen.ai/assets/asset_abc123def456.png",
    "mime_type": "image/png",
    "size_bytes": 245760
  }
}
```

| Field | Type | Description |
| - | - | - |
| `asset_id` | string | Unique identifier to reference this file in other API calls. Does not expire; see [Asset lifetime and deletion](#asset-lifetime-and-deletion). |
| `url` | string | Public URL of the uploaded file. |
| `mime_type` | string | Detected MIME type. |
| `size_bytes` | integer | File size in bytes. |

## Upload large files (direct upload)

For files larger than 32 MB, use the direct upload flow. Direct upload accepts files up to 200 MB (209,715,200 bytes) for video, image, and PDF, and up to 1.5 GB for audio. The limit for your file type is also returned as `max_bytes`. It is a three-step process — **all three steps are required**; the `asset_id` is not usable until you call the complete endpoint:

<Steps>
  <Step title="Initialize the upload">
    Call [`POST /v3/assets/direct-uploads`](/reference/create-asset-upload) with the file's name, MIME type, and exact byte size. The response contains an `asset_id`, a presigned `upload_url`, and `upload_headers`.
  </Step>

  <Step title="PUT the file bytes">
    Send the raw file bytes to `upload_url` with an HTTP `PUT`, including every header from `upload_headers` verbatim. The URL expires after `expires_in_seconds`, and the byte size is signed into it — the upload fails if the file doesn't match the declared `size_bytes`.
  </Step>

  <Step title="Complete the upload">
    Call [`POST /v3/assets/{asset_id}/complete`](/reference/complete-asset-upload) to finalize the asset. This step is idempotent — repeated calls return the same finalized asset. The `asset_id` is now usable anywhere the API accepts assets. The complete response returns `status: "processing"`. You do not need to wait for it to change; pass the `asset_id` to the next request (for example `POST /v3/avatars`) right away.
  </Step>
</Steps>

### Example

<CodeGroup>
  ```bash curl theme={null}
  # Step 1: Initialize
  SIZE=$(stat -f%z ./footage.mp4)  # use `stat -c%s` on Linux
  INIT=$(curl -s -X POST "https://api.heygen.com/v3/assets/direct-uploads" \
    -H "X-Api-Key: $HEYGEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"filename\": \"footage.mp4\", \"content_type\": \"video/mp4\", \"size_bytes\": $SIZE}")

  ASSET_ID=$(echo "$INIT" | jq -r '.data.asset_id')
  UPLOAD_URL=$(echo "$INIT" | jq -r '.data.upload_url')

  # Step 2: PUT the raw bytes to the presigned URL,
  # passing every header from data.upload_headers verbatim
  HEADER_ARGS=$(echo "$INIT" | jq -r '.data.upload_headers | to_entries[] | "-H \"\(.key): \(.value)\""' | tr '\n' ' ')
  eval curl -X PUT "$UPLOAD_URL" $HEADER_ARGS --upload-file ./footage.mp4

  # Step 3: Complete
  curl -X POST "https://api.heygen.com/v3/assets/$ASSET_ID/complete" \
    -H "X-Api-Key: $HEYGEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{}'
  ```

  ```python Python theme={null}
  import os
  import requests

  file_path = "footage.mp4"

  # Step 1: Initialize
  init = requests.post(
      "https://api.heygen.com/v3/assets/direct-uploads",
      headers={"X-Api-Key": HEYGEN_API_KEY},
      json={
          "filename": os.path.basename(file_path),
          "content_type": "video/mp4",
          "size_bytes": os.path.getsize(file_path),
      },
  ).json()["data"]

  # Step 2: PUT the raw bytes to the presigned URL
  with open(file_path, "rb") as f:
      put_resp = requests.put(init["upload_url"], data=f, headers=init["upload_headers"])
  put_resp.raise_for_status()

  # Step 3: Complete
  asset = requests.post(
      f"https://api.heygen.com/v3/assets/{init['asset_id']}/complete",
      headers={"X-Api-Key": HEYGEN_API_KEY},
      json={},
  ).json()["data"]

  print(asset["asset_id"], asset["status"])
  ```

  ```javascript Node.js theme={null}
  const fs = require("fs");

  const filePath = "./footage.mp4";
  const { size } = fs.statSync(filePath);

  // Step 1: Initialize
  const initResp = await fetch("https://api.heygen.com/v3/assets/direct-uploads", {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.HEYGEN_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      filename: "footage.mp4",
      content_type: "video/mp4",
      size_bytes: size,
    }),
  });
  const init = (await initResp.json()).data;

  // Step 2: PUT the raw bytes to the presigned URL
  await fetch(init.upload_url, {
    method: "PUT",
    headers: init.upload_headers,
    body: fs.readFileSync(filePath),
  });

  // Step 3: Complete
  const completeResp = await fetch(
    `https://api.heygen.com/v3/assets/${init.asset_id}/complete`,
    {
      method: "POST",
      headers: {
        "X-Api-Key": process.env.HEYGEN_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({}),
    }
  );
  const asset = (await completeResp.json()).data;
  console.log(asset.asset_id, asset.status);
  ```
</CodeGroup>

### Initialize response fields

| Field | Type | Description |
| - | - | - |
| `asset_id` | string | Reusable asset identifier. Becomes usable after the complete step. |
| `upload_url` | string | Presigned URL. `PUT` the raw file bytes here. |
| `upload_headers` | object | Headers that must be sent verbatim on the `PUT` request. |
| `expires_in_seconds` | integer | Seconds until `upload_url` expires. |
| `max_bytes` | integer | Maximum upload size in bytes for this content type: 209,715,200 (200 MiB) for video, image, and PDF files, 1,500,000,000 (1.5 GB) for audio files. A larger `size_bytes` is rejected at initialize. |
| `status` | string | Always `pending_upload` at this stage. |

<Note>
  Calling complete before the `PUT` has finished returns a `409 conflict` ("Uploaded object not found yet"). Retry after the `PUT` returns `200`. You can optionally pass `checksum_sha256` (hex) at both the initialize and complete steps to have the stored bytes verified end to end.
</Note>

## Use assets in Video Agent

Once uploaded, reference the `asset_id` in the `files` array when creating a video:

```json theme={null}
{
  "prompt": "Create a product demo using the attached screenshots",
  "files": [
    { "type": "asset_id", "asset_id": "asset_abc123def456" },
    { "type": "asset_id", "asset_id": "asset_ghi789jkl012" }
  ]
}
```

## Three ways to provide files

Video Agent and other endpoints accept files in three formats. Use whichever is most convenient for your workflow:

<CardGroup>
  <Card title="Asset ID" icon="database">
    Upload once, reference by ID. Best for files you reuse across multiple videos.
  </Card>

  <Card title="HTTPS URL" icon="link">
    Point to a publicly accessible HTTPS URL. No upload step needed, HeyGen fetches the file directly. Limits: 16 MB for images, 32 MB for video, audio, and PDF.
  </Card>

  <Card title="Base64" icon="code">
    Inline the file content as a base64-encoded string. Useful for small files or when you want a self-contained request.
  </Card>
</CardGroup>

### Format comparison

| Format | Syntax | When to use |
| - | - | - |
| Asset ID | `{ "type": "asset_id", "asset_id": "asset_..." }` | Pre-uploaded files, reusable across requests. Only option for files over 32 MB (via [direct upload](#upload-large-files-direct-upload)). |
| URL | `{ "type": "url", "url": "https://..." }` | Files already hosted publicly, within the [size limits](#size-limits-by-input) below. |
| Base64 | `{ "type": "base64", "media_type": "image/png", "data": "iVBOR..." }` | Small files, self-contained requests, no hosting needed. |

### Size limits by input

| Input | Images | Video, audio, PDF |
| - | - | - |
| `url` | 16 MB | 32 MB |
| `base64` (decoded size) | 5 MB | 16 MB |
| `asset_id` from `POST /v3/assets` | 32 MB | 32 MB |
| `asset_id` from [direct upload](#upload-large-files-direct-upload) | 200 MB | 200 MB (audio 1.5 GB) |

<Warning>
  URL inputs are capped at 16 MB for images and 32 MB for video, audio, and PDF. Pointing at a larger self-hosted file fails with `Maximum size for URL inputs of type 'video/mp4' is 32 MB`. For larger files, use [direct upload](#upload-large-files-direct-upload) and pass the resulting `asset_id`. Base64 encoding additionally inflates payload size by \~33%, so prefer the other two formats for anything beyond a few MB.
</Warning>

<Note>
  Signed URLs (for example S3 or Google Cloud Storage presigned URLs) work like any other `url` input and have the same size limits. Signing a URL does not raise the limit. The URL must use HTTPS, be downloadable without extra headers, return the file directly (redirects are not followed) with a `Content-Type` header, and still be valid when HeyGen fetches it. For files over the URL limit, or when you cannot guarantee the link stays valid, use direct upload and pass the `asset_id`.
</Note>

## Where assets can be used

The `asset_id` format is accepted anywhere the API takes file inputs:

| Endpoint | Use case |
| - | - |
| [`POST /v3/video-agents`](/reference/create-video-agent-session) | Attach reference files (images, slides, video clips, audio). |
| [`POST /v3/video-agents/{session_id}`](/reference/send-message-or-request-revision) | Send additional files in follow-up messages — see [Interactive Sessions](/docs/interactive-sessions). |
| [`POST /v3/avatars`](/reference/create-avatar) | Provide a photo for a photo avatar, or training footage for a digital twin (consent videos go to [`POST /v3/avatars/{group_id}/consent`](/reference/create-avatar-consent)). Twin footage (15 to 600 seconds, about 2 minutes of natural talking at 1080p recommended) is usually larger than 32 MB, so upload it with [direct upload](#upload-large-files-direct-upload), keep the file under 200 MB, and pass the `asset_id`. See [Create Avatar](/docs/create-avatar). |
| [`POST /v3/video-translations`](/reference/create-video-translation) | Provide source video or custom audio — see [Video Translation](/docs/video-translate). |
| [`POST /v3/lipsyncs`](/reference/create-lipsync) | Provide source video and/or replacement audio — see [Lipsync](/lipsync-speed). |

## Asset lifetime and deletion

An `asset_id` does not expire. It stays usable in any request until you delete it, so upload a file once and reuse the same `asset_id` on every retry, for example when you retry `POST /v3/avatars` or resubmit a consent video with [`POST /v3/avatars/{group_id}/consent`](/reference/create-avatar-consent) after a rejected review. You do not need to upload the file again.

Only the presigned `upload_url` from [direct upload](#upload-large-files-direct-upload) is time-limited (`expires_in_seconds`, 24 hours). The `asset_id` it returns becomes usable after the complete step and then follows the same rule.

Delete an asset with [`DELETE /v3/assets/{asset_id}`](/reference/delete-asset):

```bash curl theme={null}
curl -X DELETE "https://api.heygen.com/v3/assets/asset_abc123def456" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

A deleted `asset_id` returns `asset_not_found` in later requests.

Assets are separate from the avatars, videos, and translations you create from them. Deleting an avatar group with [`DELETE /v3/avatars/{group_id}`](/reference/delete-avatar-group) removes the avatar and all its looks, but not the files you uploaded to create it, and deleting an asset does not affect avatars or videos already made from it. To remove an uploaded training footage or consent video file, call `DELETE /v3/assets/{asset_id}` for each `asset_id`.

Files you pass to other endpoints as a `url` or base64 are also saved as assets in your workspace, but those calls do not return the new `asset_id`. If you will need to delete a source file later, upload it here first and pass its `asset_id`.

## Example: Upload then generate

A complete workflow — upload a PDF, then use it to generate a video:

<CodeGroup>
  ```bash curl theme={null}
  # Step 1: Upload the PDF
  ASSET_ID=$(curl -s -X POST "https://api.heygen.com/v3/assets" \
    -H "X-Api-Key: $HEYGEN_API_KEY" \
    -F "file=@./quarterly-report.pdf" | jq -r '.data.asset_id')

  echo "Uploaded asset: $ASSET_ID"

  # Step 2: Generate a video using the uploaded PDF
  curl -X POST "https://api.heygen.com/v3/video-agents" \
    -H "X-Api-Key: $HEYGEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{
      \"prompt\": \"Summarize the key findings from this quarterly report in a 60-second video\",
      \"files\": [{ \"type\": \"asset_id\", \"asset_id\": \"$ASSET_ID\" }]
    }"
  ```

  ```python Python theme={null}
  import requests

  # Step 1: Upload
  with open("quarterly-report.pdf", "rb") as f:
      upload_resp = requests.post(
          "https://api.heygen.com/v3/assets",
          headers={"X-Api-Key": HEYGEN_API_KEY},
          files={"file": f},
      )
  asset_id = upload_resp.json()["data"]["asset_id"]

  # Step 2: Generate
  gen_resp = requests.post(
      "https://api.heygen.com/v3/video-agents",
      headers={"X-Api-Key": HEYGEN_API_KEY},
      json={
          "prompt": "Summarize the key findings from this quarterly report in a 60-second video",
          "files": [{"type": "asset_id", "asset_id": asset_id}],
      },
  )
  session = gen_resp.json()["data"]
  ```
</CodeGroup>


# Usage Limits
Source: https://heygen-1fa696a7.mintlify.app/docs/usage-limits

See HeyGen API rate limits by endpoint and plan tier. Includes concurrent video render quotas, burst concurrency for Enterprise, request-per-minute caps, and input limits.

<img alt="" />

## Concurrency Limits

| Plan | Included Concurrent Workflows | Burst |
| :- | :- | :- |
| Pay-As-You-Go | 10 | — |
| Enterprise | 20 | Up to +50 per workflow type at 1.5× |

Concurrent jobs include any asynchronous generation in progress: [Video Agent sessions](/docs/video-agent), avatar video renders, and [video translations](/docs/video-translate). Burst applies to avatar video renders and video translations, each with its own pool of extra slots. Exceeding the limit returns `429 Too Many Requests` with a `Retry-After` header — see the [`rate_limit_exceeded` error](/docs/error-codes#rate-limit-exceeded).

### Burst

Enterprise workspaces run above their included slots on demand instead of buying a higher permanent cap. Turn it on under **Capacity → Concurrency** in [Usage](https://app.heygen.com/developers/usage), pick an extra cap of up to 50 workflows, and only the workflows that run above the included slots bill at **1.5×** your contract rate. Burst workflows are tagged in the [Activity tab](https://app.heygen.com/developers/usage?tab=activity). See [Burst Concurrency](/docs/burst) for how slots are assigned and billed.

## Endpoint Limits

### Video Generation Input

Resources provided to [`POST /v3/videos`](/reference/create-video) must meet these limits. Invalid resources will cause render failures with [`download_failed`](/docs/error-codes#download-failed).

| Resource Type | Supported Formats | Max File Size | Max Resolution |
| :- | :- | :- | :- |
| Video | MP4, WebM | 100 MB | \< 2K |
| Image | JPG, PNG | 50 MB | \< 2K |
| Audio | WAV, MP3 | 50 MB | — |

Requirements:

* Resource URLs must be **publicly accessible** (no authentication required).
* The file extension must **match the actual file format**.
* Files must not be **corrupted or malformed**.

### Avatar Input

* **Script text:** Maximum 5,000 characters.
* **Audio input:** Maximum 10 minutes (600 seconds).

### Video Agent Input

* **Prompt:** 1–10,000 characters.
* **File attachments:** Up to 20 files. Supported types: image (PNG, JPEG), video (MP4, WebM), audio (MP3, WAV), and PDF.
* Files can be provided as an `asset_id` (from [`POST /v3/assets`](/reference/upload-asset)), an HTTPS URL, or base64-encoded content. See [Upload Assets](/docs/upload-assets).

### Asset Upload ([`POST /v3/assets`](/reference/upload-asset))

* **Maximum file size:** 32 MB. The same limit applies to files provided by URL. For larger files, use the [direct upload flow](/docs/upload-assets#upload-large-files-direct-upload) ([`POST /v3/assets/direct-uploads`](/reference/create-asset-upload)) — its per-upload cap is returned as `max_bytes` in the initialize response.
* **Supported types:** Image (PNG, JPEG), video (MP4, WebM), audio (MP3, WAV), and PDF.

### Text-to-Speech Input ([`POST /v3/voices/speech`](/reference/generate-speech))

* **Text length:** 1–5,000 characters.
* **Speed multiplier:** 0.5× to 2.0×.
* **Input type:** Plain text, with `<break time="1s"/>` pause tags supported for pacing.

### Output Video Specifications

* **Frame rate:** 25 fps for videos containing avatars.
* **Resolution:** Width and height must each be between 128 and 4,096 pixels. Default output is 1080p.
* **Aspect ratio:** 16:9 or 9:16.
* **Maximum scenes:** 50 per video.
* **Maximum duration:** 30 minutes per scene.

<Note>
  The cap is per scene. An `avatar` or `image` request to [`POST /v3/videos`](/reference/create-video) renders a single scene, so 30 minutes is also its whole-video maximum. The multi-scene modes — [studio videos](/studio-videos) and [templates](/templates) — run as long as the sum of their scenes, provided each scene stays within 30 minutes. A scene over the cap fails during rendering.
</Note>

## Pagination

Most list endpoints use cursor-based pagination with a `limit` parameter and `next_token` for the next page.

| Endpoint | Default | Max |
| :- | :- | :- |
| [`GET /v3/videos`](/reference/list-videos) | 10 | 100 |
| [`GET /v3/avatars`](/reference/list-avatar-groups) | 20 | 50 |
| [`GET /v3/avatars/looks`](/reference/list-avatar-looks) | 20 | 50 |
| [`GET /v3/voices`](/reference/list-voices) | 20 | 100 |
| [`GET /v3/video-agents/styles`](/reference/list-video-agent-styles) | 20 | 100 |
| [`GET /v3/video-translations`](/reference/list-video-translations) | 10 | 100 |
| [`GET /v3/webhooks/endpoints`](/reference/list-webhook-endpoints) | 10 | 100 |
| [`GET /v3/webhooks/events`](/reference/list-webhook-events) | 10 | 100 |

## Rate Limiting

Request-rate limits apply per user and per endpoint path, and depend on your plan and the type of endpoint. Requests to a path that contains an ID, such as [`GET /v3/videos/{video_id}`](/reference/get-video), are counted separately for each ID.

| Endpoint type | Examples | Pay-As-You-Go and subscription | Enterprise |
| :- | :- | :- | :- |
| Read | [`GET /v3/voices`](/reference/list-voices), [`GET /v3/videos`](/reference/list-videos) | 300 per minute | 1,000 per minute |
| Write | [`POST /v3/videos`](/reference/create-video) | 10 per second | 30 per second |
| Heavy | [`POST /v3/voices/speech`](/reference/generate-speech), [`POST /v3/assets`](/reference/upload-asset) | 30 per minute | 120 per minute |
| Status polling | [`GET /v3/videos/{video_id}`](/reference/get-video) and the other status endpoints | 500 per minute, and 600 per minute per IP address | 1,500 per minute, and 1,800 per minute per IP address |

The Enterprise column applies to workspaces on an Enterprise API plan. Enterprise workspaces can also ask their account team for custom limits on specific endpoints.

### Endpoints with fixed limits

These endpoints have the same limit on every plan:

| Endpoint | Limit |
| :- | :- |
| [`POST /v3/videos/batches`](/reference/create-video-batch) | 30 per minute |
| [`POST /v3/video-translations/batches`](/reference/create-video-translation-batch) | 30 per minute |
| [`POST /v3/lipsyncs/batches`](/reference/create-lipsync-batch) | 30 per minute |
| [`POST /v3/assets/direct-uploads/batches`](/reference/create-asset-upload-batch) | 30 per minute |
| [`POST /v3/hyperframes/renders`](/reference/create-hyperframes-render) | 5 per second |
| [`POST /v3/models/audio/tts`](/reference/generate-model-speech) and [`POST /v3/models/audio/tts/stream`](/reference/stream-speech) | 30 per minute |

### When you exceed a limit

The API returns `429 Too Many Requests` with the [`rate_limit_exceeded`](/docs/error-codes#rate-limit-exceeded) error. The error message names the limit you hit, and the response includes these headers:

| Header | Meaning |
| :- | :- |
| `Retry-After` | Seconds to wait before retrying. |
| `X-RateLimit-Limit` | Requests allowed in the window you exceeded. |
| `X-RateLimit-Remaining` | Requests left in that window. |
| `X-RateLimit-Reset` | When the window resets, in Unix epoch seconds. |
| `X-RateLimit-Scope` | `user` or `ip`: whether you hit the per-user or the per-IP limit. |

The text-to-speech model endpoints return `Retry-After` only. Wait at least `Retry-After` seconds, then retry with exponential backoff.


# Prompt to Video
Source: https://heygen-1fa696a7.mintlify.app/docs/video-agent

Create AI avatar videos from a single text prompt with the HeyGen Video Agent API. The agent picks the avatar, voice, and style, then renders in minutes.

<img alt="" />

<Note>
  This is the **one-shot** workflow — send a prompt, get a video. For multi-turn collaboration with the agent, see [Interactive Sessions](/docs/interactive-sessions).
</Note>

<Info>
  **API reference:** [Create Session](/reference/create-video-agent-session) · [Get Session](/reference/get-video-agent-session) · [List Sessions](/reference/list-video-agent-sessions) · [Stop Session](/reference/stop-video-agent-session) · [Get Video](/reference/get-video) · [List Videos](/reference/list-videos) · [Delete Video](/reference/delete-video)
</Info>

<Frame>
  <video>
    <source type="video/mp4" />
  </video>
</Frame>

[`POST /v3/video-agents`](/reference/create-video-agent-session)

Send a text prompt describing the video you want. The agent handles scripting, avatar selection, scene composition, and rendering. The video is generated asynchronously — use the returned `session_id` to track progress and retrieve the `video_id` once rendering begins.

## Powered by Hyperframes

Video Agent composes and renders its graphics with [Hyperframes](/hyperframes-overview), HeyGen's open-source HTML-to-video framework ([GitHub](https://github.com/heygen-com/hyperframes)). Every animated stat, chart, caption treatment, and scene transition in a generated video is a Hyperframes composition the agent authors to your direction. Because scenes are built in code rather than assembled from a fixed template set, the agent can produce any look you can describe — which is what makes the [style paragraph](/docs/prompting-guide#add-a-style-paragraph) in your prompt so effective. To render your own compositions through the same engine, see [Hyperframes Cloud Rendering](/hyperframes).

### Request body

| Parameter | Type | Required | Description |
| - | - | - | - |
| `prompt` | string | **Yes** | Text description of the video you want (1–10,000 characters). See the [Prompting Guide](/docs/prompting-guide). |
| `mode` | string | No | `"generate"` (default) — one-shot, fire-and-forget. `"chat"` — multi-turn; the agent pauses for review and supports revisions. See [Interactive Sessions](/docs/interactive-sessions). |
| `avatar_id` | string | No | Specific avatar look ID. Omit to let the agent choose automatically. |
| `voice_id` | string | No | Specific voice ID for narration. Omit to let the agent choose automatically. |
| `style_id` | string | No | Style ID from [`GET /v3/video-agents/styles`](/reference/list-video-agent-styles). Applies a curated visual template. See [Styles & References](/docs/styles-and-references). |
| `brand_kit_id` | string | No | [Brand kit](/docs/brand-kits) ID from [`GET /v3/brand-kits`](/reference/list-brand-kits). Applies your brand colors, fonts, and logo to everything the agent builds. |
| `brand_glossary_id` | string | No | [Brand glossary](/docs/brand-glossary) ID from [`GET /v3/brand-glossaries`](/reference/list-brand-glossaries). Sets how your custom terms are pronounced in the narration; captions and subtitles keep the original spelling. |
| `orientation` | string | No | `"landscape"` or `"portrait"`. Auto-detected from content if omitted. |
| `files` | array | No | Up to 20 file attachments. See [File input formats](#file-input-formats) below. |
| `callback_url` | string | No | Webhook URL to receive a POST notification on completion or failure. |
| `callback_id` | string | No | Caller-defined ID echoed back in the webhook payload. |
| `incognito_mode` | boolean | No | When `true`, disables memory injection and extraction for this session. |

### File input formats

Each item in the `files` array uses a `type` discriminator to specify how the file is provided:

<CodeGroup>
  ```json URL theme={null}
  { "type": "url", "url": "https://example.com/slide-deck.pdf" }
  ```

  ```json Asset ID theme={null}
  { "type": "asset_id", "asset_id": "asset_abc123" }
  ```

  ```json Base64 theme={null}
  { "type": "base64", "media_type": "image/png", "data": "iVBORw0KGgo..." }
  ```
</CodeGroup>

Supported file types: image (png, jpeg), video (mp4, webm), audio (mp3, wav), and pdf. Upload files in advance via [`POST /v3/assets`](/reference/upload-asset) to get an `asset_id` — see [Upload Assets](/docs/upload-assets).

### Example request

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://api.heygen.com/v3/video-agents" \
    -H "X-Api-Key: $HEYGEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Create a 45-second explainer about our Q3 product launch. Use a friendly, upbeat tone. Include the attached slides as visual context.",
      "orientation": "landscape",
      "files": [
        { "type": "url", "url": "https://example.com/q3-launch-deck.pdf" }
      ]
    }'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://api.heygen.com/v3/video-agents",
      headers={"X-Api-Key": HEYGEN_API_KEY},
      json={
          "prompt": "Create a 45-second explainer about our Q3 product launch. Use a friendly, upbeat tone.",
          "orientation": "landscape",
          "files": [
              {"type": "url", "url": "https://example.com/q3-launch-deck.pdf"}
          ],
      },
  )
  data = resp.json()["data"]
  session_id = data["session_id"]
  ```

  ```javascript Node.js theme={null}
  const resp = await fetch("https://api.heygen.com/v3/video-agents", {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.HEYGEN_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      prompt: "Create a 45-second explainer about our Q3 product launch.",
      orientation: "landscape",
      files: [
        { type: "url", url: "https://example.com/q3-launch-deck.pdf" },
      ],
    }),
  });
  const { data } = await resp.json();
  const sessionId = data.session_id;
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "data": {
    "session_id": "sess_abc123",
    "status": "generating",
    "video_id": null,
    "created_at": 1711382400
  }
}
```

| Field | Type | Description |
| - | - | - |
| `session_id` | string | Primary identifier for this Video Agent session. Use to track progress. |
| `status` | string | Session status: `"thinking"`, `"generating"`, `"completed"`, or `"failed"`. |
| `video_id` | string \| null | Video ID for polling via [`GET /v3/videos/{video_id}`](/reference/get-video). `null` until rendering begins — poll [`GET /v3/video-agents/{session_id}`](/reference/get-video-agent-session) to get the `video_id` once it's assigned. |
| `created_at` | integer | Unix timestamp of session creation. |

## Poll for completion

Video generation is asynchronous — processing typically takes 5x–10x the final video length (a 1-minute video takes \~5–10 minutes; enterprise plans get priority queue access). Set poll intervals of 10–30 seconds, or skip polling entirely with a [webhook](#use-webhooks-instead-of-polling). If a video has been processing for more than 24 hours, contact [HeyGen Support](https://help.heygen.com) with your `video_id`.

First, poll the session to get the `video_id`, then poll the video for its final status:

* [`GET /v3/video-agents/{session_id}`](/reference/get-video-agent-session) — session status and assigned `video_id`
* [`GET /v3/videos/{video_id}`](/reference/get-video) — final render status and `video_url`

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.heygen.com/v3/videos/vid_xyz789" \
    -H "X-Api-Key: $HEYGEN_API_KEY"
  ```

  ```python Python theme={null}
  import time, requests

  # Step 1: wait for video_id to be assigned
  video_id = None
  while not video_id:
      sess = requests.get(
          f"https://api.heygen.com/v3/video-agents/{session_id}",
          headers={"X-Api-Key": HEYGEN_API_KEY},
      ).json()["data"]
      video_id = sess.get("video_id")
      if not video_id:
          time.sleep(5)

  # Step 2: poll video until complete
  while True:
      video = requests.get(
          f"https://api.heygen.com/v3/videos/{video_id}",
          headers={"X-Api-Key": HEYGEN_API_KEY},
      ).json()["data"]
      if video["status"] in ("completed", "failed"):
          break
      time.sleep(10)

  print(video["video_url"])
  ```
</CodeGroup>

### Response (completed)

```json theme={null}
{
  "data": {
    "id": "vid_xyz789",
    "title": "Q3 Product Launch Explainer",
    "status": "completed",
    "video_url": "https://files.heygen.ai/video/vid_xyz789.mp4",
    "thumbnail_url": "https://files.heygen.ai/thumb/vid_xyz789.jpg",
    "duration": 45.2,
    "created_at": 1711382400,
    "completed_at": 1711382680
  }
}
```

### Video status transitions

The `status` field progresses through these values:

| Status | Description |
| - | - |
| `pending` | Video creation request accepted, queued for processing. |
| `processing` | The agent is generating the video. |
| `completed` | Video is ready. `video_url` contains the download link. |
| `failed` | Generation failed. Check `failure_code` and `failure_message`. |

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique video identifier. |
| `title` | string \| null | Video title. |
| `status` | string | Current status: `pending`, `processing`, `completed`, or `failed`. |
| `video_url` | string \| null | Presigned download URL. Present when `completed`. |
| `thumbnail_url` | string \| null | Thumbnail image URL. |
| `gif_url` | string \| null | Animated GIF preview URL. |
| `captioned_video_url` | string \| null | Video with burned-in captions. |
| `subtitle_url` | string \| null | SRT subtitle file download URL. |
| `duration` | number \| null | Video duration in seconds. |
| `created_at` | integer \| null | Unix timestamp of creation. |
| `completed_at` | integer \| null | Unix timestamp when generation finished. |
| `failure_code` | string \| null | Machine-readable failure reason. Only when `failed`. |
| `failure_message` | string \| null | Human-readable failure description. Only when `failed`. |
| `video_page_url` | string \| null | Link to the video in the HeyGen app. |

## Use webhooks instead of polling

Pass a `callback_url` in the creation request to receive a POST notification when the video completes or fails, instead of polling:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/video-agents" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a short welcome video for new employees",
    "callback_url": "https://your-server.com/webhooks/heygen",
    "callback_id": "onboarding-video-001"
  }'
```

The `callback_id` is echoed back in the webhook payload so you can correlate notifications with requests.

## List videos

Retrieve all videos in your account with pagination. Full schema: [`GET /v3/videos`](/reference/list-videos).

| Parameter | Type | Default | Description |
| - | - | - | - |
| `limit` | integer | 10 | Results per page (1–100). |
| `token` | string | — | Opaque cursor from a previous response's `next_token`. |
| `folder_id` | string | — | Filter by folder ID. |
| `title` | string | — | Filter by title substring. |

```bash theme={null}
curl "https://api.heygen.com/v3/videos?limit=5" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

## Delete a video

Permanently remove a video. Full schema: [`DELETE /v3/videos/{video_id}`](/reference/delete-video).

```bash theme={null}
curl -X DELETE "https://api.heygen.com/v3/videos/vid_xyz789" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

```json Response theme={null}
{
  "data": {
    "id": "vid_xyz789",
    "deleted": true
  }
}
```

## Write a better prompt

The prompt is the whole interface — the agent makes every decision you leave open. Put the duration in the prompt, direct the look with a style paragraph, and paste a script for scene-by-scene control. The [Prompting Guide](/docs/prompting-guide) builds one real prompt step by step and shows the video it produced.


# Video Translation - Speed
Source: https://heygen-1fa696a7.mintlify.app/docs/video-translate

Translate videos into 175+ languages with the HeyGen Video Translation API. Preserves the speaker's voice, applies lipsync to the target language, and exports.

<img alt="" />

**Mode:** `"speed"` (default) Best for: fast turnaround, batch jobs, and workflows where time matters more than perfect lip-sync. For higher fidelity at the cost of latency, see [Precision mode](/docs/video-translation-precision). For dozens or hundreds of videos in one job, see [Video Translation batches](/batch-video-translations).

## How Lip Sync and Video Translation Relate

Both APIs sit on top of **one lip sync engine** that runs in two modes — **Speed** and **Precision** — trading latency for fidelity. What differs is what each API does *around* that engine:

* **[Lip Sync API](/lipsync-speed)** — the engine on its own. You bring the video *and* your own audio; the engine redraws the mouth to match. No translation, no audio generation — dialogue replacement only.
* **[Video Translation API](/docs/video-translate)** — translation, optionally followed by the engine. It has two output modes:
  * **Audio only** (`translate_audio_only: true`) — transcribe, translate, and generate the translated audio, then stop. No lip sync. The output is just the new audio track (or the original video with swapped audio and an untouched mouth).
  * **Video (audio + visual)** — the same translation pipeline, then runs the lip sync engine so the mouth matches the translated speech.

The short version:

* **Lip Sync API** = engine only — you bring the audio.
* **Video Translation API** = translation, optionally followed by the engine. Audio-only mode skips the engine entirely; video mode adds it back.

## Quick Start

### 1. List Supported Languages

Before translating, fetch the available target language codes via [`GET /v3/video-translations/languages`](/reference/list-supported-translation-languages):

```bash theme={null}
curl --request GET \
  --url 'https://api.heygen.com/v3/video-translations/languages' \
  --header 'accept: application/json' \
  --header 'x-api-key: <your-api-key>'
```

### 2. Submit a Translation (Single Language)

Full schema: [`POST /v3/video-translations`](/reference/create-video-translation).

```bash theme={null}
curl --request POST \
  --url 'https://api.heygen.com/v3/video-translations' \
  --header 'accept: application/json' \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "video": {
      "type": "url",
      "url": "<video_url>"
    },
    "output_languages": ["Spanish"],
    "mode": "speed",
    "title": "My Translated Video"
  }'
```

### Batch (Multiple Languages)

Translate into several languages in one request:

```bash theme={null}
curl --request POST \
  --url 'https://api.heygen.com/v3/video-translations' \
  --header 'accept: application/json' \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "video": {
      "type": "url",
      "url": "<video_url>"
    },
    "output_languages": ["English", "Spanish", "French"],
    "mode": "speed",
    "title": "Global Campaign"
  }'
```

Response returns one ID per language:

```json theme={null}
{
  "data": {
    "video_translation_ids": [
      "tr_abc123-en",
      "tr_abc123-es",
      "tr_abc123-fr"
    ]
  }
}
```

### 3. Poll for Status

Use [`GET /v3/video-translations/{video_translation_id}`](/reference/get-video-translation). Skip polling by passing `callback_url` — see [Webhooks](/docs/webhooks).

```bash theme={null}
curl --request GET \
  --url 'https://api.heygen.com/v3/video-translations/<video_translation_id>' \
  --header 'accept: application/json' \
  --header 'x-api-key: <your-api-key>'
```

| Status | Meaning |
| - | - |
| `pending` | Queued |
| `running` | In progress |
| `completed` | Done — `video_url` is available |
| `failed` | Check `failure_message` |

## Source Video Input

| Type | Example |
| - | - |
| URL | `{ "type": "url", "url": "https://example.com/video.mp4" }` |
| Asset ID | `{ "type": "asset_id", "asset_id": "<asset_id>" }` |

> The URL must be publicly accessible (test by opening in an incognito browser). To use an `asset_id`, upload first via [`POST /v3/assets`](/reference/upload-asset) — see the [Upload Assets guide](/docs/upload-assets).

## Speed Mode Options

These parameters are particularly relevant for Speed mode:

| Parameter | Default | Description |
| - | - | - |
| `mode` | `"speed"` | Set to `"speed"` for faster processing |
| `speaker_num` | auto | Number of speakers |
| `translate_audio_only` | `false` | When `true`, only audio is translated; original video is preserved |
| `enable_dynamic_duration` | `true` | Allows output duration to vary to match natural speech pacing. Billing is unaffected: translations are always charged on the source duration. |
| `disable_music_track` | `false` | Strips background music from output |
| `enable_speech_enhancement` | `false` | Improves speech audio quality |
| `brand_glossary_id` | — | Apply a [brand glossary](/docs/brand-glossary): its `do_not_translate_terms` stay untranslated and its `forced_translations` get their exact replacement, in every target language. See [Keep terminology intact](#keep-terminology-intact) |
| `brand_voice_id` | — | Deprecated. The former name for `brand_glossary_id`; both are accepted and resolve to the same glossary |
| `callback_url` | — | [Webhook](/docs/webhooks) URL notified on completion or failure |
| `callback_id` | — | Your own ID, echoed back in the webhook payload |

## Keep terminology intact

A [brand glossary](/docs/brand-glossary) tells the translator which terms to leave alone and which to replace with a fixed form. Create one with [`POST /v3/brand-glossaries`](/reference/create-brand-glossary):

```json Glossary create payload theme={null}
{
  "name": "Acme Translation Rules",
  "do_not_translate_terms": [{ "term": "HeyGen" }],
  "forced_translations": [{ "term": "CEO", "translation": "Geschäftsführer" }]
}
```

Then pass the returned `brand_glossary_id` at the top level of the translation request:

```json Translation request theme={null}
{
  "video": { "type": "url", "url": "<video_url>" },
  "output_languages": ["German"],
  "brand_glossary_id": "8c2d5e91a47b4f3c8d1e6a9b2f5c7d40"
}
```

Rules apply case-insensitively in every target language of the request. A `translation` is inserted verbatim, so pick a form that reads correctly without inflection. Glossaries created in the HeyGen app under **Brand Kit** carry the same rules and work the same way.

## Stock Voice (Enterprise)

Use a preset "stock" voice for the translation instead of recreating the original speaker's voice.

By default, Video Translation clones the original speaker, so the translated video sounds like them. With this option enabled, the translation is spoken by a natural, preset voice that's optimized for clear pronunciation and accent in the target language. The trade-off: the result won't sound like the original speaker.

<Note>
  This is an Enterprise feature, available for selected accounts and languages and turned on by request. To use it, contact your HeyGen account team.
</Note>

Pass `stock_voice_config` in the translation request:

| Field | Type | Default | Description |
| - | - | - | - |
| `use_stock_voice` | boolean | `false` | Set to `true` to use a preset stock voice instead of cloning the original speaker. |
| `preferred_stock_voice_ids` | string\[] | — | Optional. Pin specific stock voices to draw from. Each entry is a Gemini voice name (e.g. `Erinome`, `Vindemiatrix`), not a UUID. If omitted, the target language's default stock-voice pool is used. |

```bash theme={null}
curl --request POST \
  --url 'https://api.heygen.com/v3/video-translations' \
  --header 'accept: application/json' \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "video": {
      "type": "url",
      "url": "<video_url>"
    },
    "output_languages": ["Spanish"],
    "mode": "speed",
    "title": "My Translated Video",
    "stock_voice_config": {
      "use_stock_voice": true,
      "preferred_stock_voice_ids": ["Erinome"]
    }
  }'
```

## Captions

Captions are generated in SRT and VTT. A completed [`GET /v3/video-translations/{video_translation_id}`](/reference/get-video-translation) carries them as presigned download URLs alongside the video:

```json theme={null}
{
  "data": {
    "id": "vt_abc123",
    "status": "completed",
    "video_url": "https://files.heygen.ai/...",
    "srt_caption_url": "https://files.heygen.ai/...srt",
    "vtt_caption_url": "https://files.heygen.ai/...vtt"
  }
}
```

Each field appears once `status` is `completed` and that caption file is available. A field whose URL has not been produced is left out of the response entirely rather than returned as `null`, so read `srt_caption_url` and `vtt_caption_url` with a presence check before using them. The `enable_caption` request field is retained for compatibility and no longer changes anything, since whether captions are displayed is a download-side choice.

## Proofread Before Finalizing

Speed mode supports the proofread workflow — review and edit subtitles before spending credits on final generation. Reference: [Create](/reference/create-proofread-session) · [Get](/reference/get-proofread-session) · [Download SRT](/reference/download-proofread-srt) · [Upload SRT](/reference/upload-proofread-srt) · [Generate Final Video](/reference/generate-video-from-proofread).

### Step 1 — Create Proofread Session

Full schema: [`POST /v3/video-translations/proofreads`](/reference/create-proofread-session).

```bash theme={null}
curl --request POST \
  --url 'https://api.heygen.com/v3/video-translations/proofreads' \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "video": { "type": "url", "url": "<video_url>" },
    "output_languages": ["Spanish"],
    "title": "Review Before Publishing",
    "mode": "speed"
  }'
```

Returns `proofread_ids` — one per language.

### Step 2 — Poll Until `completed`

[`GET /v3/video-translations/proofreads/{proofread_id}`](/reference/get-proofread-session).

```bash theme={null}
curl --request GET \
  --url 'https://api.heygen.com/v3/video-translations/proofreads/<proofread_id>' \
  --header 'x-api-key: <your-api-key>'
```

### Step 3 — Download & Edit the SRT

Download via [`GET /v3/video-translations/proofreads/{proofread_id}/srt`](/reference/download-proofread-srt); upload the revised file via [Upload Proofread SRT](/reference/upload-proofread-srt).

```bash theme={null}
curl --request GET \
  --url 'https://api.heygen.com/v3/video-translations/proofreads/<proofread_id>/srt' \
  --header 'x-api-key: <your-api-key>'
```

Edit the returned `srt_url` file locally, then upload the revised version:

```bash theme={null}
curl --request PUT \
  --url 'https://api.heygen.com/v3/video-translations/proofreads/<proofread_id>/srt' \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{ "srt": { "type": "url", "url": "<your_edited_srt_url>" } }'
```

### Step 4 — Generate Final Video

[`POST /v3/video-translations/proofreads/{proofread_id}/generate`](/reference/generate-video-from-proofread).

```bash theme={null}
curl --request POST \
  --url 'https://api.heygen.com/v3/video-translations/proofreads/<proofread_id>/generate' \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{ "captions": true }'
```

Returns a `video_translation_id` to poll via [`GET /v3/video-translations/{video_translation_id}`](/reference/get-video-translation).

## Other Operations

### List All Translations

[`GET /v3/video-translations`](/reference/list-video-translations).

```bash theme={null}
curl --request GET \
  --url 'https://api.heygen.com/v3/video-translations?limit=10' \
  --header 'x-api-key: <your-api-key>'
```

Uses `has_more` + `next_token` for pagination.

### Delete a Translation

[`DELETE /v3/video-translations/{video_translation_id}`](/reference/delete-video-translation).

```bash theme={null}
curl --request DELETE \
  --url 'https://api.heygen.com/v3/video-translations/<video_translation_id>' \
  --header 'x-api-key: <your-api-key>'
```

## When to Use Speed vs. Precision

| | Speed | [Precision](/docs/video-translation-precision) |
| - | - | - |
| Processing Time | Faster | Slower |
| Translation | Adequate | Context- and Gender-Aware |
| Lip-Sync Quality | Standard | High |
| Best For | Faces with little movement, quick drafts | Faces with significant movement, side angles, or occlusions; final delivery videos |

For high-volume jobs across many source videos, see [Video Translation batches](/batch-video-translations).


# Video Translation - Precision
Source: https://heygen-1fa696a7.mintlify.app/docs/video-translation-precision

Use HeyGen Video Translation in precision mode for verbatim transcripts, terminology control, and proofread SRT inputs.

<img alt="" />

**Mode:** `"precision"` Best for: high-quality final delivery, talking-head videos, and content where accurate lip-sync is critical. For faster turnaround at lower fidelity, see [Speed mode](/docs/video-translate). For many videos in one job, see [Video Translation batches](/batch-video-translations).

## How Precision Mode Works

Precision mode uses avatar inference and multiple models to re-render the speaker's mouth movements to match the translated audio—producing significantly more realistic lip-sync than Speed mode. It requires longer processing time and is recommended for polished, client-facing, or broadcast-quality output.

## Quick Start

### 1. List Supported Languages

Fetch available target language codes via [`GET /v3/video-translations/languages`](/reference/list-supported-translation-languages):

```bash theme={null}
curl --request GET \
  --url 'https://api.heygen.com/v3/video-translations/languages' \
  --header 'accept: application/json' \
  --header 'x-api-key: <your-api-key>'
```

### 2. Submit a Translation (Single Language)

Full schema: [`POST /v3/video-translations`](/reference/create-video-translation).

```bash theme={null}
curl --request POST \
  --url 'https://api.heygen.com/v3/video-translations' \
  --header 'accept: application/json' \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "video": {
      "type": "url",
      "url": "<video_url>"
    },
    "output_languages": ["Spanish"],
    "mode": "precision",
    "title": "High Quality Translation"
  }'
```

### Batch (Multiple Languages)

```bash theme={null}
curl --request POST \
  --url 'https://api.heygen.com/v3/video-translations' \
  --header 'accept: application/json' \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "video": {
      "type": "url",
      "url": "<video_url>"
    },
    "output_languages": ["English", "Spanish", "French"],
    "mode": "precision",
    "title": "Global Campaign — High Quality"
  }'
```

Response returns one ID per language:

```json theme={null}
{
  "data": {
    "video_translation_ids": [
      "tr_abc123-en",
      "tr_abc123-es",
      "tr_abc123-fr"
    ]
  }
}
```

### 3. Poll for Status

Use [`GET /v3/video-translations/{video_translation_id}`](/reference/get-video-translation). Skip polling by passing `callback_url` — see [Webhooks](/docs/webhooks).

```bash theme={null}
curl --request GET \
  --url 'https://api.heygen.com/v3/video-translations/<video_translation_id>' \
  --header 'accept: application/json' \
  --header 'x-api-key: <your-api-key>'
```

| Status | Meaning |
| - | - |
| `pending` | Queued |
| `running` | Avatar inference in progress |
| `completed` | Done — `video_url` is available |
| `failed` | Check `failure_message` |

> Precision mode takes longer than Speed mode — plan polling intervals accordingly (e.g. every 30–60 seconds for longer videos).

## Source Video Input

| Type | Example |
| - | - |
| URL | `{ "type": "url", "url": "https://example.com/video.mp4" }` |
| Asset ID | `{ "type": "asset_id", "asset_id": "<asset_id>" }` |

> The URL must be publicly accessible (test by opening in an incognito browser). To use an `asset_id`, upload first via [`POST /v3/assets`](/reference/upload-asset) — see the [Upload Assets guide](/docs/upload-assets).

## Precision Mode Options

These parameters are particularly relevant for Precision mode:

| Parameter | Default | Description |
| - | - | - |
| `mode` | `"speed"` | **Set to `"precision"`** to enable avatar inference |
| `speaker_num` | auto | Number of speakers |
| `translate_audio_only` | `false` | When `true`, skips avatar inference and only dubs audio (negates precision benefit) |
| `enable_dynamic_duration` | `true` | Allows output duration to vary to match natural speech pacing. Billing is unaffected: translations are always charged on the source duration. |
| `disable_music_track` | `false` | Strips background music from output |
| `enable_speech_enhancement` | `false` | Improves speech audio quality |
| `brand_glossary_id` | — | Apply a [brand glossary](/docs/brand-glossary) so do-not-translate terms and forced translations are honored. `brand_voice_id` is the deprecated former name |
| `srt` | — | Custom subtitle file — **Enterprise plan only** |
| `srt_role` | — | `"input"` or `"output"` — which video the SRT applies to. Enterprise only |
| `callback_url` | — | [Webhook](/docs/webhooks) URL notified on completion or failure |
| `callback_id` | — | Your own ID, echoed back in the webhook payload |

> **Tip:** Setting `speaker_num` is especially important in Precision mode — accurate speaker separation directly improves the quality of avatar inference per speaker.

## Captions

Captions are generated in SRT and VTT. A completed [`GET /v3/video-translations/{video_translation_id}`](/reference/get-video-translation) carries them as presigned download URLs alongside the video:

```json theme={null}
{
  "data": {
    "id": "vt_abc123",
    "status": "completed",
    "video_url": "https://files.heygen.ai/...",
    "srt_caption_url": "https://files.heygen.ai/...srt",
    "vtt_caption_url": "https://files.heygen.ai/...vtt"
  }
}
```

Each field appears once `status` is `completed` and that caption file is available. A field whose URL has not been produced is left out of the response entirely rather than returned as `null`, so read `srt_caption_url` and `vtt_caption_url` with a presence check before using them. The `enable_caption` request field is retained for compatibility and no longer changes anything, since whether captions are displayed is a download-side choice.

## Proofread Before Finalizing

Precision mode fully supports the proofread workflow — review and edit subtitles before committing to the full avatar inference render. **This is especially valuable in Precision mode** since generation takes longer and costs more. Reference: [Create](/reference/create-proofread-session) · [Get](/reference/get-proofread-session) · [Download SRT](/reference/download-proofread-srt) · [Upload SRT](/reference/upload-proofread-srt) · [Generate Final Video](/reference/generate-video-from-proofread).

### Step 1 — Create Proofread Session

Full schema: [`POST /v3/video-translations/proofreads`](/reference/create-proofread-session).

```bash theme={null}
curl --request POST \
  --url 'https://api.heygen.com/v3/video-translations/proofreads' \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "video": { "type": "url", "url": "<video_url>" },
    "output_languages": ["Spanish"],
    "title": "Review Before Publishing",
    "mode": "precision"
  }'
```

Returns `proofread_ids` — one per language.

### Step 2 — Poll Until `completed`

[`GET /v3/video-translations/proofreads/{proofread_id}`](/reference/get-proofread-session).

```bash theme={null}
curl --request GET \
  --url 'https://api.heygen.com/v3/video-translations/proofreads/<proofread_id>' \
  --header 'x-api-key: <your-api-key>'
```

### Step 3 — Download & Edit the SRT

Download via [`GET /v3/video-translations/proofreads/{proofread_id}/srt`](/reference/download-proofread-srt); upload the revised file via [Upload Proofread SRT](/reference/upload-proofread-srt).

```bash theme={null}
curl --request GET \
  --url 'https://api.heygen.com/v3/video-translations/proofreads/<proofread_id>/srt' \
  --header 'x-api-key: <your-api-key>'
```

Edit the returned `srt_url` file locally, then upload the revised version:

```bash theme={null}
curl --request PUT \
  --url 'https://api.heygen.com/v3/video-translations/proofreads/<proofread_id>/srt' \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{ "srt": { "type": "url", "url": "<your_edited_srt_url>" } }'
```

### Step 4 — Generate Final Video

[`POST /v3/video-translations/proofreads/{proofread_id}/generate`](/reference/generate-video-from-proofread).

```bash theme={null}
curl --request POST \
  --url 'https://api.heygen.com/v3/video-translations/proofreads/<proofread_id>/generate' \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{ "captions": true }'
```

Returns a `video_translation_id` to poll via [`GET /v3/video-translations/{video_translation_id}`](/reference/get-video-translation).

## Other Operations

### List All Translations

[`GET /v3/video-translations`](/reference/list-video-translations).

```bash theme={null}
curl --request GET \
  --url 'https://api.heygen.com/v3/video-translations?limit=10' \
  --header 'x-api-key: <your-api-key>'
```

Uses `has_more` + `next_token` for pagination.

### Delete a Translation

[`DELETE /v3/video-translations/{video_translation_id}`](/reference/delete-video-translation).

```bash theme={null}
curl --request DELETE \
  --url 'https://api.heygen.com/v3/video-translations/<video_translation_id>' \
  --header 'x-api-key: <your-api-key>'
```

### List and Delete Proofread Sessions

[`GET /v3/video-translations/proofreads`](/reference/list-proofread-sessions) lists every proofread session in the workspace, newest first, paged with `has_more` and `next_token`. [`DELETE /v3/video-translations/proofreads/{proofread_id}`](/reference/delete-proofread-session) removes one; it needs a Creator role or higher and cannot be undone.

## When to Use Speed vs. Precision

| | [Speed](/docs/video-translate) | Precision |
| - | - | - |
| Processing Time | Faster | Slower |
| Translation | Adequate | Context- and Gender-Aware |
| Lip-Sync Quality | Standard | High |
| Best For | Faces with little movement, quick drafts | Faces with significant movement, side angles, or occlusions; final delivery videos |

For high-volume jobs across many source videos, see [Video Translation batches](/batch-video-translations).


# Design a Voice
Source: https://heygen-1fa696a7.mintlify.app/docs/voices/design-voices

Generate a brand new custom voice from a natural-language description using the HeyGen Design a Voice API. No source audio needed; describe the voice you want.

<img alt="" />

Full schema: [`POST /v3/voices`](/reference/design-a-voice). To browse the existing catalog instead, see [Browse Voices](/docs/voices/search-voices). To clone an existing speaker from audio, see [`POST /v3/voices/clone`](/reference/clone-a-voice).

## Quick Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://api.heygen.com/v3/voices" \
    -H "X-Api-Key: $HEYGEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "A warm, confident male voice with a slight British accent. Deep baritone, measured pace, suitable for tech product narration.",
      "gender": "male"
    }'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://api.heygen.com/v3/voices",
      headers={"X-Api-Key": HEYGEN_API_KEY},
      json={
          "prompt": "A warm, confident male voice with a slight British accent. Deep baritone, measured pace, suitable for tech product narration.",
          "gender": "male",
      },
  )
  result = resp.json()["data"]
  for v in result["voices"]:
      print(f"{v['voice_id']} — {v['name']}")
  ```

  ```javascript Node.js theme={null}
  const resp = await fetch("https://api.heygen.com/v3/voices", {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.HEYGEN_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      prompt: "A warm, confident male voice with a slight British accent. Deep baritone, measured pace, suitable for tech product narration.",
      gender: "male",
    }),
  });
  const { data } = await resp.json();
  data.voices.forEach((v) => console.log(`${v.voice_id} — ${v.name}`));
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": {
    "voices": [
      {
        "voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
        "name": "James",
        "language": "English",
        "gender": "male",
        "preview_audio_url": "https://files.heygen.ai/voice/preview/james.mp3",
        "support_pause": true,
        "support_locale": true,
        "type": "public"
      }
    ],
    "seed": 0
  }
}
```

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `prompt` | string | Yes | Text description of the desired voice. Max 1000 characters. |
| `gender` | string | No | Filter results by `"male"` or `"female"`. |
| `locale` | string | No | BCP-47 locale tag to filter by (e.g. `"en-US"`, `"pt-BR"`). |
| `seed` | integer | No | Controls which batch of results to return. `0` returns the top matches, `1` the next batch. Same prompt + seed always returns the same voices. |

## Response Fields

| Field | Type | Description |
| - | - | - |
| `voices` | array | Up to 3 matching voices, ordered by relevance. Each has the same shape as voices returned by [`GET /v3/voices`](/reference/list-voices). Use `voice_id` directly in [`POST /v3/voices/speech`](/reference/generate-speech) or video creation. |
| `seed` | integer | The seed used for this request. Increment to get a different batch of voices. |

## Getting Different Results

If the returned voices don't fit, increment `seed` to get the next batch — same prompt, different voices:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/voices" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A warm, confident male voice with a slight British accent.",
    "gender": "male",
    "seed": 1
  }'
```

<Tip>
  **Prompting tips:**

  * Specify gender and age (`"young woman in her 20s"`, `"mature male voice"`)
  * Describe the accent (`"American Midwest"`, `"slight French accent"`)
  * Set the tone (`"warm and friendly"`, `"authoritative"`, `"playful"`)
  * Mention pacing (`"measured and calm"`, `"energetic and fast"`)
  * Reference a use case (`"suitable for corporate training"`, `"good for storytelling"`)
</Tip>


# Instant Voice Clone
Source: https://heygen-1fa696a7.mintlify.app/docs/voices/heygen-voice-instant-clone

Clone a voice from one recording on the HeyGen Voice model with POST /v3/models/audio/voices, then generate completed or streaming speech.

<img alt="" />

One recording in, a voice out. [`POST /v3/models/audio/voices`](/reference/create-or-retrain-an-audio-voice) with `"mode": "instant"` returns a `voice_id` that is usually `ACTIVE` within seconds. No training and no voice clone slot.

1. [Create the voice](#1-create-the-voice)
2. [Wait until it is `ACTIVE`](#2-wait-until-it-is-active)
3. [Generate speech](#3-generate-speech)

## Set up with an agent

Not technical? Paste this into [Claude Code](https://claude.com/claude-code), [Codex](https://openai.com/codex/), or Cursor and it walks you through every step on this page in your own terminal.

```text Prompt for your agent wrap theme={null}
I want to make a HeyGen instant voice clone from one recording of my voice and hear it speak. I am not a developer, so run the commands for me where you can, explain each step in one plain sentence, and when I have to do something myself tell me exactly what and wait for me.

Read these first and follow them exactly:
- https://developers.heygen.com/docs/voices/heygen-voice-instant-clone.md
- https://developers.heygen.com/docs/upload-assets.md
- https://developers.heygen.com/docs/voices/heygen-voice-speech.md
- https://developers.heygen.com/docs/for-ai-agents.md (rules for agents)

Then take me through this, checking each step before the next:
1. API key. Look for HEYGEN_API_KEY in my environment. If it is missing, send me to https://platform.heygen.com/api-keys to create one and have me export it in my terminal myself. Never ask me to paste the key into this chat. Confirm it works with GET /v3/users/me.
2. Recording. Ask me for one audio file of my voice. Check it with ffprobe (install it if needed): only the first 3 minutes are used, so 1 to 3 minutes of clear speech is ideal. Warn me about long silence or background noise. Upload it with POST /v3/assets and keep the asset_id.
3. Clone. Ask me for a display name, then call POST /v3/models/audio/voices with mode instant, the asset_id and an Idempotency-Key. Poll GET /v3/models/audio/voices/{voice_id} until status is ACTIVE. If it is FAILED, explain failure_reason and what to change.
4. Speak. Ask me for a few sentences, then call POST /v3/models/audio/tts with model heygen-voice-1, the voice_id and text. Send language only if I told you the language; otherwise leave it out so HeyGen detects it. Download the WAV and open it so I can listen. Show me how to change the text and run it again. Never send seed, speed or pitch for an instant voice.

If a request fails, look the error code up in the Errors tables on those pages and tell me the fix. Never invent keys, IDs, or URLs; if something is missing, ask me for that one thing.
```

## 1. Create the voice

[Upload the recording](/docs/upload-assets) and pass its `asset_id`, or send a public HTTPS URL or base64 audio. The call returns `202 Accepted`.

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/models/audio/voices" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: customer-instant-voice-2026-10-09" \
  -d '{
    "mode": "instant",
    "name": "Customer narrator",
    "language": "en",
    "audio": [
      { "type": "asset_id", "asset_id": "'"$ASSET_ID"'" }
    ]
  }'
```

```json Response theme={null}
{
  "data": {
    "voice_id": "7c2a9e4f1b3d4e6a8f0c2d4e6a8b1234"
  }
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `mode` | string | Yes | `instant`, lowercase. |
| `name` | string | Yes | Display name, 1–64 characters. |
| `audio` | array | Yes | Exactly one recording: `{ "type": "asset_id", "asset_id" }`, `{ "type": "url", "url" }`, or `{ "type": "base64", "media_type", "data" }`. |
| `language` | string | No | Language code of the recording, such as `en`. See [Languages](#languages). Detected from the recording when omitted. |
| `similarity` | string | No | How closely the voice follows the recording: `medium`, `high`, `extra_high`, or `max`. Default `extra_high`. |
| `remove_background_noise` | boolean | No | Clean the recording before cloning. Default `true`. |
| `gender` | string | No | `male` or `female`. Detected when omitted. Leave out with `image`. |
| `age` | string | No | `young` or `old`. Detected when omitted. Leave out with `image`. |
| `image` | object | No | An image of the speaker in their setting, as JPEG, PNG, or WebP: `{ "type": "asset_id", "asset_id" }`, `{ "type": "url", "url" }`, or `{ "type": "base64", "media_type", "data" }`. The voice takes on the ambience of the image's background: a quiet room keeps it clean, and a busy street adds matching background sound. Cannot be combined with `gender` or `age`. |

Use MP3 or WAV for uploaded assets and inline base64, with `audio/mpeg` or `audio/wav` for inline data. OGG is supported through a public audio URL; `audio/ogg` inline data and OGG assets are not accepted.

About the recording: only its first 3 minutes are used. A file can be up to 100 MiB, or 16 MB after decoding for inline base64. A URL must point at the audio file itself and download within 30 seconds; HeyGen fetches it after returning `202`, and a fetch failure ends the voice `FAILED` with `INVALID_AUDIO`. A silent recording fails.

An instant voice cannot be retrained. To change it, create a new one.

`Idempotency-Key` is optional. Reusing a key within 24 hours returns the first response, and a duplicate that arrives while the first is still being accepted returns `409 request_in_progress`. Without the header, each retry creates a new voice.

## 2. Wait until it is ACTIVE

Poll [`GET /v3/models/audio/voices/{voice_id}`](/reference/get-an-audio-voice) until `status` is `ACTIVE` or `FAILED`.

```bash theme={null}
curl "https://api.heygen.com/v3/models/audio/voices/7c2a9e4f1b3d4e6a8f0c2d4e6a8b1234" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

```json Response theme={null}
{
  "data": {
    "voice_id": "7c2a9e4f1b3d4e6a8f0c2d4e6a8b1234",
    "mode": "instant",
    "name": "Customer narrator",
    "language": "en",
    "status": "ACTIVE",
    "created_at": 1791565200
  }
}
```

| Status | Meaning |
| - | - |
| `PENDING` | HeyGen is checking and cleaning the recording. |
| `ACTIVE` | The voice can speak. |
| `FAILED` | Final. `failure_reason` says why. |

| `failure_reason` | Meaning |
| - | - |
| `INVALID_AUDIO` | The recording could not be fetched or read. |
| `PREPROCESSING_FAILED` | The recording did not pass the checks. Without `language`, it can also mean the language could not be detected. Send `language` to rule that out. |
| `DESIGN_FAILED` | The recording passed the checks, but no voice could be made from it. |
| `INTERNAL_ERROR` | Something failed on HeyGen's side. Try again. |

A voice created without `language` has no `language` field until HeyGen detects it. A failed voice stays in the list as `FAILED` until you delete it.

Wait for `ACTIVE` before you generate speech. A speech request for a `PENDING` voice returns `409 voice_not_ready`: keep polling, and send it once the voice is `ACTIVE`.

## 3. Generate speech

Once the voice is `ACTIVE`, pass it to [Text to Speech](/docs/voices/heygen-voice-speech). [`POST /v3/models/audio/tts`](/reference/generate-model-speech) returns one 44.1 kHz WAV; [`POST /v3/models/audio/tts/stream`](/reference/stream-speech) streams audio parts over Server-Sent Events from the same body.

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/models/audio/tts" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen-voice-1",
    "voice_id": "7c2a9e4f1b3d4e6a8f0c2d4e6a8b1234",
    "text": "Hello from my instant voice.",
    "language": "en"
  }'
```

An instant voice takes `model`, `voice_id`, `text`, `language`, and `expressiveness_boost` (`0.0`–`1.0`, default `1.0`), plus `with_timestamps`. `seed`, `speed`, `pitch_shift`, `pitch_variance`, and `<break>` tags work with professional voices only and return `400 invalid_parameter` for an instant voice.

## Languages

Supported base language codes for cloning and speech are: `ar`, `be`, `bg`, `ca`, `cs`, `da`, `de`, `el`, `en`, `es`, `fa`, `fi`, `fr`, `he`, `hi`, `hr`, `hu`, `id`, `it`, `ja`, `ko`, `mk`, `ms`, `nl`, `pl`, `pt`, `ro`, `ru`, `sk`, `sl`, `sr`, `sv`, `ta`, `th`, `tl`, `tr`, `uk`, `vi`, `zh`. Speech also accepts regional tags such as `en-US` and `fr-CA`, which normalize to `en` and `fr`. A regional tag does not select a regional accent. Unsupported base languages, such as `xx`, return `400 invalid_parameter`.

## Manage voices

[`GET /v3/models/audio/voices`](/reference/list-audio-voices) lists the workspace's instant and professional voices, newest first; `mode` tells them apart. Set `limit` from 1 to 100 (default 10) and pass `next_token` as `token` while `has_more` is `true`. Add `type=public` to list HeyGen's public voices instead. Any workspace can read and speak a public voice, but not delete it; `type` defaults to `private`, the workspace's own voices.

Each `ACTIVE` voice in the list and in [`GET /v3/models/audio/voices/{voice_id}`](/reference/get-an-audio-voice) has a `preview_audio_url`: a WAV of the voice reading a short fixed preview script in its language, about 15 seconds. The URL can expire, so read the voice again rather than storing it. It is `null` while a voice is not `ACTIVE`.

[`DELETE /v3/models/audio/voices/{voice_id}`](/reference/delete-an-audio-voice) deletes a voice. Deleting an instant voice that is still `PENDING` cancels it.

```bash theme={null}
curl -X DELETE "https://api.heygen.com/v3/models/audio/voices/7c2a9e4f1b3d4e6a8f0c2d4e6a8b1234" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

## Errors

| HTTP status | Error code | Meaning |
| - | - | - |
| `400` | `invalid_parameter` | A missing, unknown, or invalid field, more than one `audio` item, an unsupported `language`, or `image` sent together with `gender` or `age`. |
| `403` | `resource_access_denied` | The workspace is not allowed to create voice clones. |
| `409` | `request_in_progress` | The same `Idempotency-Key` is still being accepted. Retry with backoff. |
| `429` | `rate_limit_exceeded` | Retry after the seconds in `Retry-After`. |

Speech errors are on [Text to Speech](/docs/voices/heygen-voice-speech#errors). The full catalog is in [Error Codes](/docs/error-codes).


# Text to Speech
Source: https://heygen-1fa696a7.mintlify.app/docs/voices/heygen-voice-speech

Generate completed or streaming speech from an instant or professional HeyGen Voice clone with POST /v3/models/audio/tts and POST /v3/models/audio/tts/stream.

<img alt="" />

<Warning>
  **Recommended settings for voice identity.** For the closest match to the original speaker's voice, set `similarity: "max"` when you [create the instant voice clone](/docs/voices/heygen-voice-instant-clone#1-create-the-voice) and `expressiveness_boost: 0.5` when you generate speech. These are the defaults HeyGen Studio uses.

  The API defaults are different: `similarity: "extra_high"` for voice cloning and `expressiveness_boost: 1.0` for speech. That configuration took first place on the Artificial Analysis Controlled Voice leaderboard.
</Warning>

The [HeyGen Voice](/docs/models/heygen-voice) model speaks two ways from the same request body:

* [`POST /v3/models/audio/tts`](/reference/generate-model-speech) waits for synthesis and returns one 44.1 kHz WAV URL.
* [`POST /v3/models/audio/tts/stream`](/reference/stream-speech) returns ordered audio parts as Server-Sent Events (SSE).

`voice_id` must be an `ACTIVE` HeyGen Voice clone in your workspace: an [instant voice](/docs/voices/heygen-voice-instant-clone) or a [professional clone](/docs/voices/professional-voice-clone). Each endpoint allows 30 requests per minute per workspace member.

## Generate speech with an agent

Not technical? Paste this into [Claude Code](https://claude.com/claude-code), [Codex](https://openai.com/codex/), or Cursor and it generates speech from your voice with you, in your own terminal. To make the voice first, start from the [Instant Clone](/docs/voices/heygen-voice-instant-clone#set-up-with-an-agent) or [Professional Clone](/docs/voices/professional-voice-clone#set-up-with-an-agent) prompt.

```text Prompt for your agent wrap theme={null}
I have a HeyGen Voice clone (instant or professional) and want to generate speech with it. I am not a developer, so run the commands for me where you can, explain each step in one plain sentence, and when I have to do something myself tell me exactly what and wait for me.

Read these first and follow them exactly:
- https://developers.heygen.com/docs/voices/heygen-voice-speech.md
- https://developers.heygen.com/docs/for-ai-agents.md (rules for agents)

Then take me through this, checking each step before the next:
1. API key. Look for HEYGEN_API_KEY in my environment. If it is missing, send me to https://platform.heygen.com/api-keys to create one and have me export it in my terminal myself. Never ask me to paste the key into this chat. Confirm it works with GET /v3/users/me.
2. Voice. List my voices with GET /v3/models/audio/voices, and HeyGen's public voices with GET /v3/models/audio/voices?type=public. Show me each name, mode and status. Use the one I pick; it must be ACTIVE.
3. Text. Ask me what I want the voice to say, up to 5,000 characters of plain prose, and its language if I know it.
4. Speak. Call POST /v3/models/audio/tts with model heygen-voice-1, the voice_id and text. Send language only if I told you the language; otherwise leave it out so HeyGen detects it. Download the WAV and open it so I can listen. Show me how to change the text and run it again. If the voice's mode is professional, also show me how to keep the delivery the same across runs with a seed. Omit seed, speed and pitch for an instant voice; these controls are ignored.

If a request fails, look the error code up in the Errors table on that page and tell me the fix. Never invent keys, IDs, or URLs; if something is missing, ask me for that one thing.
```

Successful completed and streaming responses include `X-Request-Id` and `Content-Language`. Use `X-Request-Id` to match usage records and any billing settlement. `Content-Language` names the language the speech was generated in.

## Request fields

| Field | Type | Required | Description |
| - | - | - | - |
| `model` | string | No | `heygen-voice-1` (default) speaks instant and professional voices. `heygen-voice-1-turbo` speaks instant voices at lower latency. `null` and other names return `400`. |
| `voice_id` | string | Yes | An `ACTIVE` instant or professional voice owned by the API key's workspace, or a HeyGen public voice from [`GET /v3/models/audio/voices?type=public`](/reference/list-audio-voices). |
| `text` | string | Yes | Plain prose to synthesize, 1–5,000 characters. |
| `language` | string | No | Language code of `text`, such as `en`. Regional tags normalize to the base language. Omit it to detect the language from `text`; see [Language](#language). See the [supported languages](/docs/voices/heygen-voice-instant-clone#languages). |
| `expressiveness_boost` | number | No | Instant voices only. `0.0`–`1.0`, default `1.0`. |
| `seed` | integer | No | Ignored for instant voices. For professional voices: best-effort deterministic seed, `0`–`4294967295`. |
| `speed` | number | No | Ignored for instant voices. For professional voices: speech speed multiplier from `0.75` to `1.25`. |
| `pitch_shift` | number | No | Ignored for instant voices. For professional voices: shifts pitch from `-4` to `+4` semitones. |
| `pitch_variance` | number | No | Ignored for instant voices. For professional voices: pitch variation from `0.5` to `2.0`; `1.0` keeps the default. |
| `with_timestamps` | boolean | No | Default `false`. On `/tts`, adds `original_characters` to the response; see [Character timestamps](#character-timestamps). On `/tts/stream`, adds character-alignment events. |

Unknown fields and invalid values return `400 invalid_parameter`, with `param` set to that field. Instant voices, including Turbo, accept and ignore valid `seed`, `speed`, `pitch_shift`, and `pitch_variance` values. Professional voices reject `expressiveness_boost`. Professional voices take `<break time="0.5s"/>` pauses of up to 5 seconds each; instant voices do not. Other SSML is not supported. Instant voices made before HeyGen Voice 1 must be cloned again before they can speak here.

### Language

Send `language` when you know it. HeyGen speaks `text` in the stated `language` as given and does not check it against the text, so a wrong one, such as `en` for Russian text, gives speech with that language's accent. If you are not sure, leave it out. When you omit it, HeyGen reads the language from `text` and uses the first of these that applies:

1. A confident reading of `text`. If HeyGen Voice does not speak that language, the request returns `400 invalid_parameter`.
2. The language the voice was created in, if `text` is written in that language's script.
3. A less certain reading, if a second reading of `text` agrees with it.
4. The usual language of the script `text` is written in, such as English for Latin letters.

If none of these is a language HeyGen Voice speaks, the request returns `400 invalid_parameter` with `param` set to `language`. Send `language` and try again. Every successful response names the language it used in the `Content-Language` header, so you can check the result and send `language` next time if it is not what you meant.

## Generate completed speech

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/models/audio/tts" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen-voice-1",
    "voice_id": "7c2a9e4f1b3d4e6a8f0c2d4e6a8b1234",
    "text": "Hello from my instant voice.",
    "language": "en",
    "expressiveness_boost": 0.8
  }'
```

```json Response theme={null}
{
  "data": {
    "audio_url": "https://files.heygen.ai/generated/model-speech.wav",
    "duration": 3.42
  }
}
```

The request stays open until the file is assembled, so no polling is needed. `audio_url` is one mono PCM16 WAV at 44.1 kHz; `duration` is in seconds.

### Character timestamps

Set `"with_timestamps": true` to get the time of each character, for captions or word highlighting. The response then also carries `original_characters`: one entry for each character of `text`, in order, with `text`, `start_time`, and `end_time` in seconds from the start of the audio.

```json Response theme={null}
{
  "data": {
    "audio_url": "https://files.heygen.ai/generated/model-speech.wav",
    "duration": 0.42,
    "original_characters": [
      {"text": "H", "start_time": 0.0, "end_time": 0.08},
      {"text": "i", "start_time": 0.08, "end_time": 0.21},
      {"text": "!", "start_time": 0.21, "end_time": 0.35}
    ]
  }
}
```

Timestamps don't change the price. Without `with_timestamps`, the response is the same as above.

For a professional voice, swap the instant-only control for the prosody controls:

```json theme={null}
{
  "model": "heygen-voice-1",
  "voice_id": "0f4e5d8c9a1b4d62a914938d06c31234",
  "text": "Hello from my professional voice. <break time=\"0.5s\"/> Let us begin.",
  "language": "en",
  "seed": 7,
  "speed": 1.1,
  "pitch_shift": -1.0,
  "pitch_variance": 1.2
}
```

## Stream speech

The stream is `text/event-stream`. Disable response buffering and handle each event as it arrives.

```bash theme={null}
curl -N --no-buffer -X POST "https://api.heygen.com/v3/models/audio/tts/stream" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "model": "heygen-voice-1",
    "voice_id": "7c2a9e4f1b3d4e6a8f0c2d4e6a8b1234",
    "text": "Hello from my instant voice.",
    "language": "en",
    "with_timestamps": true
  }'
```

**Audio events** carry base64-encoded standalone WAV parts. Play them in ascending `part_index` order; each part is a complete WAV container, so decode them individually rather than concatenating the bytes.

```text theme={null}
data: {"type":"audio","part_index":0,"audio":"UklGR..."}

data: {"type":"audio","part_index":1,"audio":"UklGR..."}
```

**Character-alignment events** appear when `with_timestamps` is `true`. `original_characters` follows the submitted text, while `normalized_characters` follows the text spoken after normalization. Each character carries `text`, `start_time`, and `end_time` in seconds.

```text theme={null}
data: {"type":"character_alignment","original_characters":[{"text":"H","start_time":0.0,"end_time":0.08}],"normalized_characters":[{"text":"H","start_time":0.0,"end_time":0.08}]}
```

A clean stream ends with `data: [DONE]`. If synthesis fails mid-stream, the stream ends with an error event instead and no `[DONE]`:

```text theme={null}
data: {"type":"error","detail":"Voice inference failed mid-stream"}
```

Errors before the first event use the standard JSON [error envelope](/docs/error-codes).

## Errors

| HTTP status | Error code | Meaning |
| - | - | - |
| `400` | `invalid_parameter` | Missing or unknown field, an invalid value, an unsupported `language` or `model`, `heygen-voice-1-turbo` sent for a professional voice (`param` is `model`), or, when `language` is omitted, a language that could not be detected from `text`. |
| `400` | `voice_expired` | The workspace is over its professional voice clone slot limit. [Add a slot](https://platform.heygen.com/usage) or delete another professional voice. |
| `402` | `insufficient_credit` | The API credit balance is empty. |
| `402` | `usage_limit_reached` | The member reached a workspace usage limit. Ask a workspace administrator to check the limit. |
| `403` | `forbidden` | The voice is a professional clone and the account is not enabled for professional voice cloning. Check the plan on the [Usage page](https://platform.heygen.com/usage). |
| `404` | `voice_not_found` | The voice is not in the caller's workspace. |
| `409` | `voice_not_ready` | The voice is still `PENDING`. Poll [`GET /v3/models/audio/voices/{voice_id}`](/reference/get-an-audio-voice) until `status` is `ACTIVE`, then send the request again. |
| `409` | `voice_training_failed` | The voice is `FAILED`. Read `failure_reason` on the voice. |
| `429` | `rate_limit_exceeded` | Retry after the seconds in `Retry-After`. |
| `503` | `service_unavailable` | Inference is busy; the request is safe to retry. |


# Voices
Source: https://heygen-1fa696a7.mintlify.app/docs/voices/overview

Browse, search, and use voices on HeyGen via the Voices API. Covers stock voices, custom voice design, voice cloning, and how to pair voices with avatars.

<img alt="" />

HeyGen provides 300+ pre-built voices across dozens of languages, plus the ability to generate custom AI voices from a text description, clone an existing speaker, or synthesize speech directly. This guide walks the full **browse → design → use** workflow; deeper guides for each step live at [Browse Voices](/docs/voices/search-voices), [Design Voices](/docs/voices/design-voices), and [Third Party Speech](/docs/voices/speech).

## Step 1: Browse Available Voices

Use [`GET /v3/voices`](/reference/list-voices) to list available voices with cursor-based pagination. Filter by language, gender, type, or engine.

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.heygen.com/v3/voices?language=English&gender=female" \
    -H "X-Api-Key: $HEYGEN_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  resp = requests.get(
      "https://api.heygen.com/v3/voices",
      headers={"X-Api-Key": HEYGEN_API_KEY},
      params={"language": "English", "gender": "female"},
  )
  data = resp.json()
  voices = data["data"]
  for v in voices[:5]:
      print(f"{v['voice_id']} — {v['name']} ({v['language']})")
  ```

  ```javascript Node.js theme={null}
  const resp = await fetch(
    "https://api.heygen.com/v3/voices?language=English&gender=female",
    { headers: { "X-Api-Key": process.env.HEYGEN_API_KEY } }
  );
  const { data } = await resp.json();
  data.slice(0, 5).forEach((v) =>
    console.log(`${v.voice_id} — ${v.name} (${v.language})`)
  );
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": [
    {
      "voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
      "name": "Sara",
      "language": "English",
      "gender": "female",
      "preview_audio_url": "https://files.heygen.ai/voice/preview/sara.mp3",
      "support_pause": true,
      "support_locale": true,
      "type": "public"
    }
  ],
  "has_more": true,
  "next_token": "eyJsYXN0X2lkIjoiMTIzIn0"
}
```

### Query Parameters

| Parameter | Type | Description |
| - | - | - |
| `type` | string | `"public"` for the shared library or `"private"` for your cloned voices. Defaults to `"public"`. |
| `engine` | string | Filter by speech engine: `"orca"` (HeyGen Voice), `"starfish"`, or `"elevenlabs"`. Only voices compatible with that engine are returned. |
| `language` | string | Filter by language name (e.g. `"English"`, `"Spanish"`, `"Japanese"`). |
| `gender` | string | Filter by `"male"` or `"female"`. |
| `limit` | integer | Results per page (1–100). Defaults to `20`. |
| `token` | string | Opaque cursor token for the next page. |

### Response Fields

| Field | Type | Description |
| - | - | - |
| `voice_id` | string | Pass this as `voice_id` to [`POST /v3/videos`](/reference/create-video) or [`POST /v3/video-agents`](/reference/create-video-agent-session). Inspect a single voice with [`GET /v3/voices/{voice_id}`](/reference/get-voice). |
| `name` | string | Display name of the voice. |
| `language` | string | Primary language. |
| `gender` | string | Gender of the voice. |
| `preview_audio_url` | string or null | URL to a short audio preview — play to audition the voice. |
| `support_pause` | boolean | Whether the voice supports `<break>` pause tags. |
| `support_locale` | boolean | Whether the voice supports locale variants. |
| `type` | string | `"public"` or `"private"`. |

<Tip>
  Each voice includes a `preview_audio_url` — play these to audition voices before using one in your video.
</Tip>

## Step 2: Design a Custom Voice (Optional)

If none of the pre-built voices fit, use [`POST /v3/voices`](/reference/design-a-voice) to generate up to 3 AI voice options from a text description. The endpoint returns a ranked list — pick the one that fits best. For more detail and prompting patterns, see [Design Voices](/docs/voices/design-voices). To clone an existing speaker instead, make an [Instant Voice Clone](/docs/voices/heygen-voice-instant-clone) from one recording, or a [Professional Voice Clone](/docs/voices/professional-voice-clone) trained on 20+ minutes of recordings. Both speak through [Text to Speech](/docs/voices/heygen-voice-speech).

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://api.heygen.com/v3/voices" \
    -H "X-Api-Key: $HEYGEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "A warm, confident male voice with a slight British accent. Deep baritone, measured pace, suitable for tech product narration.",
      "gender": "male"
    }'
  ```

  ```python Python theme={null}
  resp = requests.post(
      "https://api.heygen.com/v3/voices",
      headers={"X-Api-Key": HEYGEN_API_KEY},
      json={
          "prompt": "A warm, confident male voice with a slight British accent. Deep baritone, measured pace, suitable for tech product narration.",
          "gender": "male",
      },
  )
  result = resp.json()["data"]
  for v in result["voices"]:
      print(f"{v['voice_id']} — {v['name']}")
  ```

  ```javascript Node.js theme={null}
  const resp = await fetch("https://api.heygen.com/v3/voices", {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.HEYGEN_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      prompt: "A warm, confident male voice with a slight British accent. Deep baritone, measured pace, suitable for tech product narration.",
      gender: "male",
    }),
  });
  const { data } = await resp.json();
  data.voices.forEach((v) => console.log(`${v.voice_id} — ${v.name}`));
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": {
    "voices": [
      {
        "voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
        "name": "James",
        "language": "English",
        "gender": "male",
        "preview_audio_url": "https://files.heygen.ai/voice/preview/james.mp3",
        "support_pause": true,
        "support_locale": true,
        "type": "public"
      }
    ],
    "seed": 0
  }
}
```

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `prompt` | string | Yes | Text description of the desired voice — accent, tone, pace, gender, personality. Max 1000 characters. |
| `gender` | string | No | Filter results by `"male"` or `"female"`. |
| `locale` | string | No | BCP-47 locale tag to filter by (e.g. `"en-US"`, `"pt-BR"`). |
| `seed` | integer | No | Controls which batch of results to return. `0` returns the top matches, `1` the next batch, etc. Same prompt + seed always returns the same voices. |

<Info>
  **Prompting tips for voice design:**

  * Specify gender and approximate age (`"young woman in her 20s"`, `"mature male voice"`)
  * Describe the accent (`"American Midwest"`, `"slight French accent"`)
  * Set the tone (`"warm and friendly"`, `"authoritative"`, `"playful"`)
  * Mention pacing (`"measured and calm"`, `"energetic and fast"`)
  * Reference a use case (`"suitable for corporate training"`, `"good for storytelling"`)
</Info>

## Step 3: Use a Voice in Video Creation

Once you have a `voice_id`, pass it when creating a video. To render a catalog voice directly without an avatar, use [Third Party Speech](/docs/voices/speech) ([`POST /v3/voices/speech`](/reference/generate-speech)).

### With Video Agent

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/video-agents" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A 30-second explainer about cloud computing benefits",
    "voice_id": "1bd001e7e50f421d891986aad5c8bbd2"
  }'
```

### With Direct Video Creation

Set the voice alongside your avatar and script:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar",
    "avatar_id": "your_look_id",
    "voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
    "script": "Welcome to our platform. Today I will walk you through the key features."
  }'
```

### Voice Settings

When using [`POST /v3/videos`](/reference/create-video), you can fine-tune playback via `voice_settings`:

```json theme={null}
{
  "type": "avatar",
  "avatar_id": "your_look_id",
  "voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
  "script": "Welcome to our platform.",
  "voice_settings": {
    "speed": 1.1,
    "pitch": 0.0,
    "locale": "en-US"
  }
}
```

| Field | Type | Range | Description |
| - | - | - | - |
| `speed` | number | `0.5` – `1.5` | Playback speed multiplier. `1.0` is normal speed. |
| `pitch` | number | `-50` – `+50` | Pitch adjustment in semitones. |
| `locale` | string | BCP-47 | Locale/accent hint for multi-lingual voices. |


# Professional Voice Clone
Source: https://heygen-1fa696a7.mintlify.app/docs/voices/professional-voice-clone

Train a studio-grade professional voice clone from 20+ minutes of recordings on the HeyGen Voice model, then generate completed or streaming speech.

<img alt="" />

<Warning>
  Professional Voice Clone is a **paid feature**. Each voice occupies a purchased professional voice clone slot. Buy slots on the [Usage page](https://platform.heygen.com/usage) before creating a voice; a request with no free slot returns `400 resource_limit_reached`.
</Warning>

A professional clone trains a dedicated [HeyGen Voice](/docs/models/heygen-voice) adapter from one or more recordings of the same speaker. It is the highest-fidelity clone HeyGen offers. To make a voice from one short recording in seconds, use the [Instant Voice Clone](/docs/voices/heygen-voice-instant-clone) on the same endpoint with `"mode": "instant"`.

1. [Create a voice](#1-create-a-voice), or retrain an existing one with new recordings.
2. [Poll](#2-poll-training-status) until the voice is `ACTIVE`.
3. [Generate speech](#3-generate-speech), completed or streamed.

## Set up with an agent

Not technical? Let your coding agent do it with you. Paste this into [Claude Code](https://claude.com/claude-code), [Codex](https://openai.com/codex/), or Cursor and it walks you through every step on this page, one at a time, in your own terminal.

```text Prompt for your agent wrap theme={null}
I want to train a HeyGen Professional Voice Clone of my own voice and hear it speak. I am not a developer, so run the commands for me where you can, explain each step in one plain sentence, and when I have to do something myself tell me exactly what and wait for me.

Read these first and follow them exactly:
- https://developers.heygen.com/docs/voices/professional-voice-clone.md
- https://developers.heygen.com/docs/upload-assets.md
- https://developers.heygen.com/docs/voices/heygen-voice-speech.md
- https://developers.heygen.com/docs/for-ai-agents.md (rules for agents)

Then take me through this, checking each step before the next:
1. API key. Look for HEYGEN_API_KEY in my environment. If it is missing, send me to https://platform.heygen.com/api-keys to create one and have me export it in my terminal myself. Never ask me to paste the key into this chat. Confirm it works with GET /v3/users/me and tell me my username.
2. Slot. Ask whether I have bought a professional voice clone slot at https://platform.heygen.com/usage. 400 resource_limit_reached later means there is no free slot.
3. Recordings. Ask me for the folder with my recordings (1 to 10 files, one speaker, at least 20 minutes in total). Check the total duration with ffprobe (install it if needed) and warn me about files with long silence or background noise. Upload each file with POST /v3/assets; use the direct upload flow for any file over 32 MB. Keep the asset_id values.
4. Train. Ask me for a display name, and for the language of the recordings if I know it (otherwise leave language out; training detects it), then call POST /v3/models/audio/voices with mode professional and the asset_ids, using an Idempotency-Key. Poll GET /v3/models/audio/voices/{voice_id} with backoff until status is ACTIVE. If it is FAILED, explain failure_reason and what to change.
5. Speak. Ask me for a few sentences in my language, call POST /v3/models/audio/tts with the voice_id, download the WAV, and open it so I can listen. Then show me how to change the text and run it again.

If a request fails, look the error code up in the Errors tables on those pages and tell me the fix. Never invent keys, IDs, or URLs; if something is missing, ask me for that one thing.
```

## Before you start

### Slots and training allowance

* Voices belong to the workspace of the API key that created them. [Create the key](/docs/api-key) in the workspace that should own the voice.
* One purchased slot per voice. Retraining reuses the voice's slot.
* Each slot provides five pooled trainings per monthly billing period, initial training included. Failed trainings are free.
* If the workspace later exceeds its slot limit, for example when a slot add-on lapses, the surplus voices return `voice_expired` on synthesis until you add a slot or delete another professional voice. The voice and its data stay intact.

### Prepare the recordings

Provide 1–10 recordings of the same speaker totaling at least 20 minutes. Duration is measured including silence, so trim dead air, background noise, and overlapping speech. Upload local files with the [Assets API](/docs/upload-assets) and pass the returned `asset_id` values:

```bash theme={null}
ASSET_1=$(curl -sS -X POST "https://api.heygen.com/v3/assets" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -F "file=@./narrator-part-1.wav" | jq -er '.data.asset_id')
```

Size limits per recording: 32 MB for a public URL, 16 MB for inline base64 after decoding, 200 MB for a completed `asset_id`. For larger files use the [direct upload flow](/docs/upload-assets#upload-large-files-direct-upload).

## 1. Create a voice

`POST /v3/models/audio/voices` returns `202 Accepted` while training runs.

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/models/audio/voices" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: customer-voice-2026-08-22" \
  -d '{
    "mode": "professional",
    "name": "Customer narrator",
    "language": "en",
    "audio": [
      { "type": "asset_id", "asset_id": "'"$ASSET_1"'" },
      { "type": "asset_id", "asset_id": "'"$ASSET_2"'" }
    ]
  }'
```

```json Response theme={null}
{
  "data": {
    "voice_id": "0f4e5d8c9a1b4d62a914938d06c31234"
  }
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `mode` | string | Yes | `professional`. |
| `name` | string | New voices | Display name, up to 256 characters. |
| `language` | string | No | Primary language code of the recordings, such as `en`. Leave it out to detect the language of each recording during training; the voice's `language` is `null` until it is `ACTIVE`. |
| `audio` | array | Yes | 1–10 recordings, each `{ "type": "url", "url" }`, `{ "type": "asset_id", "asset_id" }`, or `{ "type": "base64", "media_type", "data" }`. |
| `voice_id` | string | Retraining | Existing `ACTIVE` voice to retrain. Omit when creating. |

Every recording is validated and staged before the voice is created, so undecodable audio, an unreachable URL, or fewer than 20 minutes in total returns `400 invalid_parameter` with no `voice_id`.

`Idempotency-Key` is optional. Reusing a key within 24 hours returns the original response; a duplicate that arrives while the original is still being accepted returns `409 request_in_progress`. Without the header, repeated requests create separate voices.

### Retrain a voice

Send `"mode": "professional"`, the existing `voice_id`, and replacement `audio`. The ID, name, and language are kept. The voice becomes `PENDING` until training completes, and a failed retraining restores the previously active voice.

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/models/audio/voices" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: customer-voice-retrain-2026-09-02" \
  -d '{
    "mode": "professional",
    "voice_id": "0f4e5d8c9a1b4d62a914938d06c31234",
    "audio": [
      { "type": "asset_id", "asset_id": "'"$ASSET_1"'" }
    ]
  }'
```

## 2. Poll training status

Poll `GET /v3/models/audio/voices/{voice_id}` with backoff until the status is terminal.

```bash theme={null}
curl "https://api.heygen.com/v3/models/audio/voices/0f4e5d8c9a1b4d62a914938d06c31234" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

```json Response theme={null}
{
  "data": {
    "voice_id": "0f4e5d8c9a1b4d62a914938d06c31234",
    "mode": "professional",
    "name": "Customer narrator",
    "language": "en",
    "status": "ACTIVE",
    "created_at": 1787405696
  }
}
```

| Status | Meaning |
| - | - |
| `PENDING` | Training is queued or running. |
| `ACTIVE` | Ready for speech generation. |
| `FAILED` | Training ended. `failure_reason` is one of `INVALID_AUDIO`, `INSUFFICIENT_AUDIO`, `PREPROCESSING_FAILED`, `TRAINING_FAILED`, `ARTIFACT_VALIDATION_FAILED`, `INTERNAL_ERROR`. |

`created_at` is a Unix timestamp in seconds.

## 3. Generate speech

Pass the `ACTIVE` voice to [Text to Speech](/docs/voices/heygen-voice-speech): `POST /v3/models/audio/tts` for one completed WAV, or `POST /v3/models/audio/tts/stream` for audio parts as they are generated.

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/models/audio/tts" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen-voice-1",
    "voice_id": "0f4e5d8c9a1b4d62a914938d06c31234",
    "text": "Hello from my professional voice clone.",
    "language": "en"
  }'
```

## Manage voices

`GET /v3/models/audio/voices` lists the workspace's instant and professional voices, newest first, with `mode` telling them apart, with `limit` (1–100, default 10) and cursor `token`. Pass the returned `next_token` while `has_more` is `true`. `type=public` lists HeyGen's public voices instead.

An `ACTIVE` professional voice has a `preview_audio_url`, a WAV of the voice reading a short preview script, made right after training. It can be `null` for a few minutes after a voice turns `ACTIVE`, and for a voice whose preview could not be made yet.

`DELETE /v3/models/audio/voices/{voice_id}` removes an `ACTIVE` or `FAILED` voice and frees its slot. Wait for a `PENDING` voice to finish training first.

```bash theme={null}
curl -X DELETE "https://api.heygen.com/v3/models/audio/voices/0f4e5d8c9a1b4d62a914938d06c31234" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

## Errors

| HTTP status | Error code | Meaning |
| - | - | - |
| `400` | `invalid_parameter` | Invalid request or audio input, or under 20 minutes of recordings. |
| `400` | `resource_limit_reached` | No free voice slot, or the monthly training allowance is used up. |
| `403` | `forbidden` | The account is not enabled for professional voice cloning. Check the plan on the [Usage page](https://platform.heygen.com/usage). |
| `409` | `request_in_progress` | The same `Idempotency-Key` is still being accepted. Retry with backoff. |
| `409` | `resource_not_ready` | The voice is `PENDING`: another training is running, or it was submitted for deletion. |
| `429` | `rate_limit_exceeded` | Retry after the seconds in `Retry-After`. |

Synthesis errors, including `voice_expired`, are listed on [Text to Speech](/docs/voices/heygen-voice-speech#errors). The full catalog is in [Error Codes](/docs/error-codes).


# Browse Voices
Source: https://heygen-1fa696a7.mintlify.app/docs/voices/search-voices

List and filter HeyGen voices by language, gender, accent, and age. Returns voice IDs ready to use in video generation requests across all HeyGen video APIs.

<img alt="" />

List voices via [`GET /v3/voices`](/reference/list-voices); inspect one via [`GET /v3/voices/{voice_id}`](/reference/get-voice). To create a new voice instead, see [Design Voices](/docs/voices/design-voices) or [Instant Voice Clone](/docs/voices/heygen-voice-instant-clone). For TTS on a catalog voice, see [Third Party Speech](/docs/voices/speech).

## Quick Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.heygen.com/v3/voices?language=English&gender=female&limit=5" \
    -H "X-Api-Key: $HEYGEN_API_KEY"
  ```

  ```json Response theme={null}
  {
    "data": [
      {
        "voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
        "name": "Sara",
        "language": "English",
        "gender": "female",
        "type": "public",
        "preview_audio_url": "https://files.heygen.ai/voice/preview_sara.mp3",
        "support_pause": true,
        "support_locale": true
      }
    ],
    "has_more": true,
    "next_token": "eyJsYXN0X2lkIjoiMTIzIn0"
  }
  ```
</CodeGroup>

## Query Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `type` | string | No | `"public"` | `"public"` for the shared library or `"private"` for your cloned voices. |
| `engine` | string | No | — | Filter by speech engine: `"orca"` (HeyGen Voice), `"starfish"`, or `"elevenlabs"`. Only compatible voices are returned. |
| `language` | string | No | — | Filter by language (e.g. `"English"`, `"Spanish"`). |
| `gender` | string | No | — | Filter by `"male"` or `"female"`. |
| `limit` | integer | No | `20` | Results per page (1–100). |
| `token` | string | No | — | Opaque cursor token for the next page (from a previous response's `next_token`). |

## Response Fields

Each voice object in the `data` array contains:

| Field | Type | Description |
| - | - | - |
| `voice_id` | string | Unique identifier. Pass this to [`POST /v3/voices/speech`](/reference/generate-speech), [`POST /v3/videos`](/reference/create-video), or [`POST /v3/video-agents`](/reference/create-video-agent-session). |
| `name` | string | Display name of the voice. |
| `language` | string | Primary language (e.g. `"English"`). |
| `gender` | string | `"male"` or `"female"`. |
| `type` | string | `"public"` (shared library) or `"private"` (your cloned voice). |
| `preview_audio_url` | string or null | URL to a short audio preview. |
| `support_pause` | boolean | Whether the voice supports `<break>` pause tags. |
| `support_locale` | boolean | Whether the voice supports locale variants (e.g. `en-US` vs `en-GB`). |

## Filtering Examples

### By Language

```bash curl theme={null}
curl -X GET "https://api.heygen.com/v3/voices?language=Spanish" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

### By Gender

```bash curl theme={null}
curl -X GET "https://api.heygen.com/v3/voices?gender=male" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

### Your Private (Cloned) Voices

```bash curl theme={null}
curl -X GET "https://api.heygen.com/v3/voices?type=private" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

### Voices for one engine

Every catalog voice works with [`POST /v3/voices/speech`](/reference/generate-speech). To list the voices a given [engine](/docs/voices/speech#engines) can speak, filter by it; each voice also reports `available_engines` and `default_engine`:

```bash curl theme={null}
curl -X GET "https://api.heygen.com/v3/voices?engine=elevenlabs" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

## Pagination

If `has_more` is `true`, pass the `next_token` value as the `token` query parameter to fetch the next page.

```bash curl theme={null}
curl -X GET "https://api.heygen.com/v3/voices?token=eyJsYXN0X2lkIjoiMTIzIn0" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```


# Third Party Speech
Source: https://heygen-1fa696a7.mintlify.app/docs/voices/speech

Convert text to audio with any catalog voice on the HeyGen Voice, Starfish, or ElevenLabs engine. HeyGen Voice clones speak through Text to Speech instead.

<img alt="" />

Full schema: [`POST /v3/voices/speech`](/reference/generate-speech).

This endpoint synthesizes any voice from the [voice catalog](/docs/voices/overview): stock voices and [designed voices](/docs/voices/design-voices). Most stock voices run on the HeyGen Voice engine. For a HeyGen Voice clone, [instant](/docs/voices/heygen-voice-instant-clone) or [professional](/docs/voices/professional-voice-clone), use [Text to Speech](/docs/voices/heygen-voice-speech) on `POST /v3/models/audio/tts` instead.

## Engines

Pick the engine per request with `engine`, or omit it to use the voice's saved default. The response's `engine` field reports which one ran.

| `engine` | Engine | Default for |
| - | - | - |
| `orca` | HeyGen Voice | Most public catalog voices |
| `starfish` | Starfish (HeyGen) | Voices without a saved engine |
| `elevenlabs` | ElevenLabs | Voices saved to ElevenLabs |

ElevenLabs models, set with `settings.model_id`: `eleven_v4`, `eleven_v3`, `eleven_multilingual_v2`, `eleven_flash_v2_5`, `eleven_flash_v2`, `eleven_turbo_v2_5`. Starfish takes `locale` (e.g. `zh-HK`); ElevenLabs takes `language`.

Each voice lists the engines it can use in `available_engines` and its saved default in `default_engine` on [`GET /v3/voices`](/reference/list-voices). Filter the catalog with `?engine=orca`, `?engine=starfish`, or `?engine=elevenlabs`.

## Quick example

Pick a voice with [`GET /v3/voices`](/reference/list-voices) (see [Browse Voices](/docs/voices/search-voices)), then pass its `voice_id`:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/voices/speech" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello from HeyGen!",
    "voice_id": "1bd001e7e50f421d891986aad5c8bbd2"
  }'
```

```json Response theme={null}
{
  "data": {
    "audio_url": "https://files.heygen.ai/audio/req_xyz789.mp3",
    "duration": 2.4,
    "engine": "orca",
    "request_id": "req_xyz789",
    "word_timestamps": [
      { "word": "Hello", "start": 0.0, "end": 0.45 },
      { "word": "from", "start": 0.45, "end": 0.72 },
      { "word": "HeyGen!", "start": 0.72, "end": 1.35 }
    ]
  }
}
```

## Choose an engine

Set `engine` for this request only. For ElevenLabs, add `settings.model_id`:

<CodeGroup>
  ```bash ElevenLabs v4 theme={null}
  curl -X POST "https://api.heygen.com/v3/voices/speech" \
    -H "X-Api-Key: $HEYGEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "Hello from HeyGen!",
      "voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
      "engine": "elevenlabs",
      "settings": { "model_id": "eleven_v4" }
    }'
  ```

  ```bash HeyGen Voice theme={null}
  curl -X POST "https://api.heygen.com/v3/voices/speech" \
    -H "X-Api-Key: $HEYGEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "Hello from HeyGen!",
      "voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
      "engine": "orca"
    }'
  ```

  ```bash Starfish theme={null}
  curl -X POST "https://api.heygen.com/v3/voices/speech" \
    -H "X-Api-Key: $HEYGEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "Hello from HeyGen!",
      "voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
      "engine": "starfish",
      "locale": "en-US"
    }'
  ```
</CodeGroup>

The engine you ask for is the engine that runs. A `400` means the voice, your plan, or the requested language can't use it; pick another from the voice's `available_engines`. A `403` `ai_vendor_access_restricted` means a workspace admin has blocked ElevenLabs. The older `engine: "elevenlabs_v3"` still works; new integrations pass `engine: "elevenlabs"` with `settings.model_id`.

`text` takes 1–5,000 characters. Optional fields: `speed` (0.5–2.0, default 1.0), `language` (base code such as `en`, auto-detected when omitted), `locale` (BCP-47 tag such as `pt-BR`, which overrides `language`), and `force_regenerate` (skip the speech cache for fresh audio). Keep `input_type` at its default `text`; `<break>` tags work directly in plain text.

## Adding pauses

Insert `<break>` where you want a pause, with the time in seconds:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/voices/speech" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Welcome to HeyGen. <break time=\"1s\"/> Let us get started.",
    "voice_id": "1bd001e7e50f421d891986aad5c8bbd2"
  }'
```

`<break>` is the only markup to include; wrapping the script in other tags such as `<speak>` can add spoken artifacts. Check `support_pause` on the voice in [`GET /v3/voices`](/reference/list-voices) first. The same tag works in `script` text passed to [`POST /v3/videos`](/reference/create-video).


# Webhook Events
Source: https://heygen-1fa696a7.mintlify.app/docs/webhook-events

Reference every HeyGen webhook event type with full payload schemas. Includes video.completed, video.failed, translation.completed, with example JSON.

<img alt="" />

HeyGen sends webhook events as POST requests to your registered endpoints. This page covers the available event types and how to browse delivered events.

## Authentication

| Header | Value |
| - | - |
| `X-Api-Key` | Your HeyGen API key |
| `Authorization` | `Bearer YOUR_ACCESS_TOKEN` (OAuth) |

## Event Types

Fetch the full list of supported event types and their descriptions:

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.heygen.com/v3/webhooks/event-types" \
    -H "X-Api-Key: $HEYGEN_API_KEY"
  ```

  ```json Response theme={null}
  {
    "data": [
      { "event_type": "avatar_video.success", "description": "Fired when an avatar video completes successfully." },
      { "event_type": "avatar_video.fail", "description": "Fired when an avatar video generation fails." },
      { "event_type": "video_agent.success", "description": "Fired when a Video Agent session completes successfully." },
      { "event_type": "video_agent.fail", "description": "Fired when a Video Agent session fails." }
    ],
    "has_more": false,
    "next_token": null
  }
  ```
</CodeGroup>

### Available Event Types

| Event Type | Description |
| - | - |
| `avatar_video.success` | Avatar video completed successfully. |
| `avatar_video.fail` | Avatar video generation failed. |
| `avatar_video_gif.success` | Avatar video GIF generation completed. |
| `avatar_video_gif.fail` | Avatar video GIF generation failed. |
| `avatar_video_caption.success` | Avatar video caption generation completed. |
| `avatar_video_caption.fail` | Avatar video caption generation failed. |
| `video_translate.success` | Video translation completed. |
| `video_translate.fail` | Video translation failed. |
| `video_agent.success` | Video Agent session completed. |
| `video_agent.fail` | Video Agent session failed. |
| `personalized_video` | Personalized video event. |
| `instant_avatar.success` | Instant avatar creation completed. |
| `instant_avatar.fail` | Instant avatar creation failed. |
| `photo_avatar_generation.success` | Photo avatar generation completed. |
| `photo_avatar_generation.fail` | Photo avatar generation failed. |
| `photo_avatar_train.success` | Photo avatar training completed. |
| `photo_avatar_train.fail` | Photo avatar training failed. |
| `photo_avatar_add_motion.success` | Photo avatar motion addition completed. |
| `photo_avatar_add_motion.fail` | Photo avatar motion addition failed. |
| `proofread_creation.success` | Proofread creation completed. |
| `proofread_creation.fail` | Proofread creation failed. |
| `live_avatar.success` | Live avatar session completed. |
| `live_avatar.fail` | Live avatar session failed. |

Digital twins use the `instant_avatar.*` events. Photo avatars use the `photo_avatar_*` events.

## Event Data Payloads

The `event_data` shape varies by event type. Below are the fields for `avatar_video.success`:

### `avatar_video.success`

| Field | Type | Description |
| - | - | - |
| `video_id` | string | Unique ID for the completed video. |
| `url` | string | Pre-signed download URL for the video file. |
| `gif_download_url` | string | Pre-signed download URL for the GIF preview. |
| `video_page_url` | string | URL to the video in the HeyGen app. |
| `video_share_page_url` | string | Shareable URL for the video. |
| `folder_id` | string \| null | Folder the video belongs to, or `null`. |
| `callback_id` | string \| null | Value of `callback_id` passed when creating the video, or `null`. |

<Info>
  The video download URL (`url`) is a pre-signed URL with a limited expiry window. Fetch and store the file promptly, or re-fetch the URL via `GET /v3/videos/{video_id}` if it expires.
</Info>

### Other event types

For other event types, treat the webhook as a completion signal and fetch the authoritative resource state from the API — the detail endpoints return the full, current set of fields for each resource:

| Event family | Fetch the result from |
| - | - |
| `avatar_video.*`, `avatar_video_caption.*` | [`GET /v3/videos/{video_id}`](/reference/get-video) |
| `video_agent.*` | [`GET /v3/video-agents/{session_id}`](/reference/get-video-agent-session) and [`GET /v3/video-agents/{session_id}/videos`](/reference/list-session-videos) |
| `video_translate.*` | [`GET /v3/video-translations/{video_translation_id}`](/reference/get-video-translation) |
| `photo_avatar_*`, `instant_avatar.*` | [`GET /v3/avatars/looks/{look_id}`](/reference/get-avatar-look) |

Fetching the video resource also lets you pick exactly the artifact you need — each completed video exposes `video_url` (the rendered video, with captions burned in only when you requested a caption `style`), `captioned_video_url` (the captioned render), `subtitle_url` (the SRT sidecar file), `thumbnail_url`, and `gif_url`. If a webhook hands you a URL with captions you didn't want, download `video_url` from [`GET /v3/videos/{video_id}`](/reference/get-video) instead.

## List Delivered Events

Browse events that have been delivered to your endpoints. Filter by event type or entity ID.

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.heygen.com/v3/webhooks/events?event_type=avatar_video.success&limit=5" \
    -H "X-Api-Key: $HEYGEN_API_KEY"
  ```

  ```json Response theme={null}
  {
    "data": [
      {
        "event_id": "evt_abc123",
        "event_type": "avatar_video.success",
        "event_data": {
          "video_id": "vid_xyz789",
          "url": "https://files.heygen.com/video/vid_xyz789.mp4",
          "gif_download_url": "https://resource.heygen.ai/video/vid_xyz789/gif.gif",
          "video_page_url": "https://app.heygen.com/videos/vid_xyz789",
          "video_share_page_url": "https://app.heygen.com/share/vid_xyz789",
          "folder_id": null,
          "callback_id": null
        },
        "created_at": "2026-03-25T12:05:00Z"
      }
    ],
    "has_more": false,
    "next_token": null
  }
  ```
</CodeGroup>

### Query Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `event_type` | string | No | all | Filter by a specific event type (e.g. `"avatar_video.success"`). |
| `entity_id` | string | No | — | Filter by entity ID (e.g. a video ID or session ID). |
| `limit` | integer | No | `10` | Results per page (1–100). |
| `token` | string | No | — | Opaque cursor for the next page. |

### Response Fields

Each event in the `data` array contains:

| Field | Type | Description |
| - | - | - |
| `event_id` | string | Unique identifier for this event delivery. |
| `event_type` | string | The event type (e.g. `"avatar_video.success"`). |
| `event_data` | object | The event payload. Contents vary by event type. |
| `created_at` | string | ISO 8601 timestamp when the event was created. |

## Subscribing to Events

When [creating a webhook endpoint](/docs/webhooks#create-an-endpoint), pass the event types you want to receive in the `events` array:

<CodeGroup>
  ```json "Subscribe to video events only" theme={null}
  {
    "url": "https://yourapp.com/webhooks/heygen",
    "events": [
      "avatar_video.success",
      "avatar_video.fail",
      "video_agent.success",
      "video_agent.fail"
    ]
  }
  ```

  ```json "Receive all events" theme={null}
  {
    "url": "https://yourapp.com/webhooks/heygen"
  }
  ```
</CodeGroup>

Omitting the `events` field (or setting it to `null`) subscribes the endpoint to all event types.

To change subscriptions later, use `PATCH /v3/webhooks/endpoints/{endpoint_id}` with an updated `events` array.

## Handling Events in Your Application

When an event is delivered, HeyGen sends a POST request to your endpoint URL with the event payload as JSON. A typical handler:

1. **Verify the signature** using your endpoint's signing secret.
2. **Parse `event_type`** to determine what happened.
3. **Process `event_data`** — for `avatar_video.success` events this includes `video_id`, `url` (the video download URL), `gif_download_url`, `video_page_url`, `video_share_page_url`, `folder_id`, and `callback_id`; for failures it includes error details.
4. **Return a 2xx response** promptly to acknowledge receipt.


# Webhooks
Source: https://heygen-1fa696a7.mintlify.app/docs/webhooks

Receive HeyGen API webhook events when videos finish rendering, translations complete, or errors occur. Includes endpoint setup, signature verification, and.

<img alt="" />

Instead of polling [`GET /v3/videos/{video_id}`](/reference/get-video) for status, you can register a webhook endpoint to receive a POST notification when a video completes, fails, or other events occur. See [Webhook Events](/docs/webhook-events) for the full event catalog and payload shapes.

* **Base path:** `https://api.heygen.com/v3/webhooks/endpoints`

## Authentication

Same as the rest of the v3 API — see the [API Key guide](/docs/api-key).

| Header | Value |
| - | - |
| `X-Api-Key` | Your HeyGen API key |
| `Authorization` | `Bearer YOUR_ACCESS_TOKEN` (OAuth) |

## Create an Endpoint

Register a URL to receive webhook events. The response includes a `secret` for verifying payloads — store it securely, as it will not be shown again. Full schema: [`POST /v3/webhooks/endpoints`](/reference/create-webhook-endpoint).

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://api.heygen.com/v3/webhooks/endpoints" \
    -H "X-Api-Key: $HEYGEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://yourapp.com/webhooks/heygen",
      "events": ["avatar_video.success", "avatar_video.fail"]
    }'
  ```

  ```json Response theme={null}
  {
    "data": {
      "endpoint_id": "ep_abc123",
      "url": "https://yourapp.com/webhooks/heygen",
      "events": ["avatar_video.success", "avatar_video.fail"],
      "status": "enabled",
      "created_at": "2026-03-25T12:00:00Z",
      "secret": "whsec_k7x9m2..."
    }
  }
  ```
</CodeGroup>

### Request Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `url` | string | Yes | Publicly accessible HTTPS URL that will receive webhook POST requests. |
| `events` | array | No | Event types to subscribe to. Omit or set to `null` to receive all events. See [Webhook Events](/docs/webhook-events) and [`GET /v3/webhooks/event-types`](/reference/list-webhook-event-types) for the full list. |
| `entity_id` | string | No | Scope this endpoint to a specific resource (e.g. a personalized video project). |

## List Endpoints

Retrieve all registered endpoints with pagination. Full schema: [`GET /v3/webhooks/endpoints`](/reference/list-webhook-endpoints).

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.heygen.com/v3/webhooks/endpoints?limit=10" \
    -H "X-Api-Key: $HEYGEN_API_KEY"
  ```

  ```json Response theme={null}
  {
    "data": [
      {
        "endpoint_id": "ep_abc123",
        "url": "https://yourapp.com/webhooks/heygen",
        "events": ["avatar_video.success", "avatar_video.fail"],
        "status": "enabled",
        "created_at": "2026-03-25T12:00:00Z",
        "secret": null
      }
    ],
    "has_more": false,
    "next_token": null
  }
  ```
</CodeGroup>

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `limit` | integer | No | `10` | Results per page (1–100). |
| `token` | string | No | — | Opaque cursor for the next page. |

<Info>
  The `secret` field is only returned when creating an endpoint or rotating the secret. It will be `null` in list responses.
</Info>

## Update an Endpoint

Change the URL and/or subscribed event types. The `events` array is fully replaced — include all event types you want to keep. Full schema: [`PATCH /v3/webhooks/endpoints/{endpoint_id}`](/reference/update-webhook-endpoint).

<CodeGroup>
  ```bash curl theme={null}
  curl -X PATCH "https://api.heygen.com/v3/webhooks/endpoints/ep_abc123" \
    -H "X-Api-Key: $HEYGEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://yourapp.com/webhooks/heygen-v2",
      "events": ["avatar_video.success", "avatar_video.fail", "video_agent.success"]
    }'
  ```

  ```json Response theme={null}
  {
    "data": {
      "endpoint_id": "ep_abc123",
      "url": "https://yourapp.com/webhooks/heygen-v2",
      "events": ["avatar_video.success", "avatar_video.fail", "video_agent.success"],
      "status": "enabled",
      "created_at": "2026-03-25T12:00:00Z",
      "secret": null
    }
  }
  ```
</CodeGroup>

Both fields are optional — include only what you want to change.

## Delete an Endpoint

Permanently remove an endpoint. Events will no longer be delivered to this URL. Full schema: [`DELETE /v3/webhooks/endpoints/{endpoint_id}`](/reference/delete-webhook-endpoint).

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE "https://api.heygen.com/v3/webhooks/endpoints/ep_abc123" \
    -H "X-Api-Key: $HEYGEN_API_KEY"
  ```

  ```json Response theme={null}
  {
    "data": {}
  }
  ```
</CodeGroup>

## Rotate Signing Secret

Generate a new signing secret for an endpoint. The old secret is invalidated immediately on rotation; deploy the new secret from the response to your verifier promptly. Expect a brief window of failed verifications during rollover — handle this gracefully on the receiver. Full schema: [`POST /v3/webhooks/endpoints/{endpoint_id}/rotate-secret`](/reference/rotate-webhook-signing-secret).

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://api.heygen.com/v3/webhooks/endpoints/ep_abc123/rotate-secret" \
    -H "X-Api-Key: $HEYGEN_API_KEY"
  ```

  ```json Response theme={null}
  {
    "data": {
      "endpoint_id": "ep_abc123",
      "secret": "whsec_n3w5ecr3t..."
    }
  }
  ```
</CodeGroup>

## Verifying Payloads

Every webhook delivery includes a signature header derived from your endpoint `secret`. **Always verify before trusting the payload** — without verification, anyone who learns your URL can forge events.

HeyGen signs the **raw request body** with HMAC-SHA256 using the endpoint `secret` returned by [Create Endpoint](/reference/create-webhook-endpoint) or [Rotate Secret](/reference/rotate-webhook-signing-secret). Compute the same digest on your side and compare in constant time.

| Header | Description |
| - | - |
| `signature` | Hex-encoded HMAC-SHA256 of the raw request body, computed with your endpoint `secret`. HTTP header names are case-insensitive, so `signature` and `Signature` refer to the same header. |

<CodeGroup>
  ```javascript Node.js theme={null}
  import crypto from "node:crypto";
  import express from "express";

  const app = express();
  // IMPORTANT: keep the raw body intact for signature verification.
  app.use("/webhooks/heygen", express.raw({ type: "application/json" }));

  const SECRET = process.env.HEYGEN_WEBHOOK_SECRET;

  app.post("/webhooks/heygen", (req, res) => {
    const signature = req.header("signature");

    if (!signature) return res.status(400).send("missing signature");

    const expected = crypto
      .createHmac("sha256", SECRET)
      .update(req.body) // raw Buffer, not parsed JSON
      .digest("hex");

    const sigBuf = Buffer.from(signature, "hex");
    const expBuf = Buffer.from(expected, "hex");
    if (sigBuf.length !== expBuf.length || !crypto.timingSafeEqual(sigBuf, expBuf)) {
      return res.status(401).send("bad signature");
    }

    const event = JSON.parse(req.body.toString("utf8"));
    // Handle event.event_type — see /docs/webhook-events for the catalog.
    res.status(200).send("ok");
  });
  ```

  ```python Python (Flask) theme={null}
  import hashlib
  import hmac
  import os
  from flask import Flask, abort, request

  app = Flask(__name__)
  SECRET = os.environ["HEYGEN_WEBHOOK_SECRET"].encode()

  @app.post("/webhooks/heygen")
  def heygen_webhook():
      signature = request.headers.get("signature", "")
      if not signature:
          abort(400, "missing signature")

      raw = request.get_data()  # bytes, before any JSON parsing
      expected = hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
      if not hmac.compare_digest(signature, expected):
          abort(401, "bad signature")

      event = request.get_json()
      # Handle event["event_type"] — see /docs/webhook-events for the catalog.
      return "", 200
  ```
</CodeGroup>

<Warning>
  Verify against the **raw body bytes**, not a re-serialized JSON object. Any whitespace or key-order change will break the HMAC. In Express, use `express.raw()`; in Flask, use `request.get_data()` before `request.get_json()`.
</Warning>

### Delivery, retries, and idempotency

* **Success criteria:** respond with `2xx` within 10 seconds. Slow handlers will be timed out and retried.
* **Retries:** failed deliveries are retried with exponential backoff for up to 24 hours.
* **Idempotency:** a single event can be delivered more than once (a retry after a transient failure). A retry resends the **same payload**, so de-duplicate on a stable field in the body. For avatar video events, use `event_data.video_id` together with `event_type`, or the `callback_id` you set when creating the video.

For the full list of event types and payload shapes, see [Webhook Events](/docs/webhook-events).

## Using Callbacks Instead

If you don't need a persistent webhook endpoint, pass a `callback_url` directly when creating a video — for example via [Create Video Agent Session](/reference/create-video-agent-session) or [Create Video Translation](/reference/create-video-translation). This sends a one-off notification for that specific request without registering an endpoint:

<CodeGroup>
  ```json "Video Agent with callback" theme={null}
  {
    "prompt": "A product demo for our new app",
    "callback_url": "https://yourapp.com/callbacks/heygen",
    "callback_id": "my-custom-id-123"
  }
  ```
</CodeGroup>

The `callback_id` is echoed back in the webhook payload so you can correlate the notification with your request.


# Endpoint Version Comparison
Source: https://heygen-1fa696a7.mintlify.app/endpoint-version-comparison

Compare HeyGen API v1, v2, and v3 endpoints and migrate existing integrations to v3.

## Deprecation Timeline

| Phase | Window | What to Expect |
| - | - | - |
| **Current** | Now — October 31, 2026 | v1/v2 endpoints remain fully operational. v3 is live and recommended for all new development. |
| **End of Life** | November 1, 2026 — end of support date. | v1/v2 endpoints will be retired. All traffic should be routed to v3 by this date. |

## Find your own legacy calls

Every v1 and v2 response tells you it is legacy and names its replacement, so you can inventory a codebase by running it rather than reading it. Responses carry `Deprecation: true` and a `Sunset` header of `Sat, 31 Oct 2026 00:00:00 GMT`, and the JSON body gains a `warning` object:

```json theme={null}
{
  "warning": {
    "message": "This v2 endpoint is Legacy and will be removed on 2026-10-31. Developers: migrate to POST /v3/videos. Documentation: https://developers.heygen.com/reference/create-video",
    "v3_endpoint": "POST /v3/videos",
    "docs_url": "https://developers.heygen.com/reference/create-video",
    "sunset_date": "2026-10-31"
  }
}
```

`v3_endpoint` is the exact operation to move to. Log it across a day of traffic and you have your migration list.

## Feature Comparison

| Feature | v1 | v2 | v3 |
| - | - | - | - |
| **Avatar Video Generation** | — | `POST /v2/video/generate` | [`POST /v3/videos`](/reference/create-video) |
| **Video Agent** | `POST /v1/video_agent/generate` | — | [`POST /v3/video-agents`](/reference/create-video-agent-session) |
| **Studio API (multi-scene)** | — | `POST /v2/video/generate` | [`POST /v3/videos`](/reference/create-video) with `type: "studio"` |
| **Template API (variables)** | — | `POST /v2/template/{id}/generate` | [`POST /v3/templates/{id}`](/reference/generate-video-from-template) |
| **List and Get Templates** | — | `GET /v2/templates`, `GET /v2/template/{id}` | [`GET /v3/templates`](/reference/list-templates), [`GET /v3/templates/{id}`](/reference/get-template) |
| **Poll Video Status** | `GET /v1/video_status.get` | `GET /v2/videos/{video_id}` | [`GET /v3/videos/{video_id}`](/reference/get-video) |
| **List Videos** | `GET /v1/video.list` | `GET /v2/videos` | [`GET /v3/videos`](/reference/list-videos) |
| **Delete a Video** | `DELETE /v1/video.delete` | `DELETE /v2/videos/{video_id}` | [`DELETE /v3/videos/{video_id}`](/reference/delete-video) |
| **Video Translation** | — | `POST /v2/video_translate` | [`POST /v3/video-translations`](/reference/create-video-translation) |
| **Translation Languages** | — | `GET /v2/video_translate/target_languages` | [`GET /v3/video-translations/languages`](/reference/list-supported-translation-languages) |
| **Translation Captions** | — | `GET /v2/video_translate/caption` | `srt_caption_url` and `vtt_caption_url` on [`GET /v3/video-translations/{id}`](/reference/get-video-translation) |
| **Proofread Workflow** | — | `POST /v2/video_translate/proofread` | [`POST /v3/video-translations/proofreads`](/reference/create-proofread-session) |
| **Text-to-Speech** | `POST /v1/audio/text_to_speech` | — | [`POST /v3/voices/speech`](/reference/generate-speech) |
| **List Voices** | `GET /v1/voice.list`, `GET /v1/audio/voices` | `GET /v2/voices` | [`GET /v3/voices`](/reference/list-voices) |
| **Voice Clone** | — | `POST /v2/voices/clone` | [`POST /v3/voices/clone`](/reference/clone-a-voice) |
| **List Avatars** | `GET /v1/avatar.list` | `GET /v2/avatars`, `GET /v2/avatar_group.list` | [`GET /v3/avatars`](/reference/list-avatar-groups) |
| **Photo Avatars** | — | `POST /v2/photo_avatar/*` | [`POST /v3/avatars`](/reference/create-avatar) with `type: "photo"` |
| **Webhook Management** | `/v1/webhook/endpoint.*` | — | [`/v3/webhooks/endpoints`](/reference/list-webhook-endpoints) with secret rotation and an event log |
| **Asset Management** | `GET /v1/asset/list`, `POST /v1/asset/{id}/delete` | — | [`POST /v3/assets`](/reference/upload-asset) and [`DELETE /v3/assets/{asset_id}`](/reference/delete-asset) |
| **Folders** | `POST /v1/folders/create` | — | [`POST /v3/folders`](/reference/create-folder) and [`GET /v3/folders/{folder_id}`](/reference/get-folder) |
| **Brand Glossary** | `GET /v1/brand_voice/list` | — | [`GET /v3/brand-glossaries`](/reference/list-brand-glossaries) |
| **Account Info** | `GET /v1/user/me` | `GET /v2/user/remaining_quota` | [`GET /v3/users/me`](/reference/get-current-user) |
| **Batch Creation** | — | — | [`POST /v3/videos/batches`](/reference/create-video-batch) |
| **Lipsync** | — | — | [`POST /v3/lipsyncs`](/reference/create-lipsync) |
| **Voice Design** | — | — | [`POST /v3/voices`](/reference/design-a-voice) |

On v3, avatar video generation selects a rendering engine per request, Avatar III, IV, or V, through the `engine` field. See [Models](/models).

## v3-Only Features (No Legacy Equivalent)

| Feature | Endpoint | Notes |
| - | - | - |
| Lipsync | [`POST /v3/lipsyncs`](/reference/create-lipsync) | Speed and precision modes |
| Voice Design | [`POST /v3/voices`](/reference/design-a-voice) | Design a voice from a text prompt |
| Avatar Creation | [`POST /v3/avatars`](/reference/create-avatar) | One endpoint for footage, photo, and prompt. See [Create Avatar](/docs/create-avatar) |
| Look Packs | [`POST /v3/avatars/looks`](/reference/create-avatar-looks) | Curated look sets for an avatar you own |
| Avatar Consent Flow | [`POST /v3/avatars/{group_id}/consent`](/reference/create-avatar-consent) | Required before a digital twin renders |
| HyperFrames | [`POST /v3/hyperframes/renders`](/reference/create-hyperframes-render) | Render HTML, CSS and JS projects to video |
| Background Removal | `POST /v3/background-removals` | Managed background-removal jobs |
| Audio Search | [`GET /v3/audio/sounds`](/reference/search-audio-music-or-sound-effects) | Background-music and sound-effects catalog |
| Batch Video Creation | [`POST /v3/videos/batches`](/reference/create-video-batch) | Submit up to 100 videos in one request |
| Cursor-based Pagination | All v3 list endpoints | Standard across every resource |
| Unified Asset Input | All v3 creation endpoints | `url`, `asset_id` or `base64` discriminated union |

## v3 Platform Improvements

| Capability | v1/v2 | v3 |
| - | - | - |
| Pagination | Offset-based or none | Cursor-based (all list endpoints) |
| Asset references | Varies by endpoint | Unified `url` / `asset_id` / `base64` union |
| Webhook delivery | `callback_url` param, plus v1 endpoint management | Managed endpoints, event types, signed payloads, secret rotation |
| Video request body | Flat object | Discriminated union (`type: "avatar"`, `"image"`, `"cinematic_avatar"` or `"studio"`) |
| Voice fallback | `voice_id` always required | Falls back to the avatar's default voice when omitted |

## Migration Checklist

* Inventory your v1/v2 calls by logging the `warning.v3_endpoint` field on legacy responses
* Replace `POST /v2/video/generate` with [`POST /v3/videos`](/reference/create-video), including multi-scene calls, which become `type: "studio"`
* Replace `GET /v1/video_status.get` with [`GET /v3/videos/{video_id}`](/reference/get-video)
* Replace `POST /v1/video_agent/generate` with [`POST /v3/video-agents`](/reference/create-video-agent-session)
* Replace avatar and voice listing calls with [`GET /v3/avatars`](/reference/list-avatar-groups) and [`GET /v3/voices`](/reference/list-voices)
* Replace `POST /v1/audio/text_to_speech` with [`POST /v3/voices/speech`](/reference/generate-speech)
* Replace `POST /v2/template/{id}/generate` with [`POST /v3/templates/{id}`](/reference/generate-video-from-template)
* Replace `POST /v2/video_translate` with [`POST /v3/video-translations`](/reference/create-video-translation), and read captions from the detail response instead of `GET /v2/video_translate/caption`
* Replace `GET /v1/user/me` and `GET /v2/user/remaining_quota` with [`GET /v3/users/me`](/reference/get-current-user)
* Move `/v1/webhook/endpoint.*` management to [`/v3/webhooks/endpoints`](/reference/list-webhook-endpoints)
* Update pagination logic to cursor-based where applicable
* Test all migrated endpoints in staging before October 31, 2026


# Examples
Source: https://heygen-1fa696a7.mintlify.app/examples

Browse example HeyGen CLI workflows from one-off video generation to multi-step automation. Each example shows the prompt, command, and resulting video.

## Create a Video with the Agent

Let the AI pick the avatar, voice, and layout from a text prompt:

```bash theme={null}
heygen video-agent create --prompt "A presenter explaining our product launch in 30 seconds"
```

```json Output theme={null}
{
  "data": {
    "session_id": "sess_abc123",
    "status": "generating",
    "video_id": "vid_xyz789",
    "created_at": 1711288320
  }
}
```

Block until the video is ready:

```bash theme={null}
heygen video-agent create --prompt "A presenter explaining our product launch in 30 seconds" --wait
```

Browse available styles first, then apply one:

```bash theme={null}
heygen video-agent styles list
heygen video-agent create --prompt "Product launch" --style-id <style-id> --wait
```

***

## Create a Video with Full Control

Skip the agent and specify every detail yourself using `-d`:

```bash theme={null}
heygen video create -d '{
  "type": "avatar",
  "avatar_id": "avt_angela_01",
  "script": "Welcome to our Q4 earnings call.",
  "voice_id": "1bd001e7e50f421d891986aad5e3e5d2",
  "aspect_ratio": "auto",
  "resolution": "1080p"
}' --wait
```

```json Output theme={null}
{
  "data": {
    "id": "vid_qr8821",
    "status": "completed",
    "video_url": "https://files.heygen.com/video/vid_qr8821.mp4",
    "duration": 12.4,
    "created_at": 1711288320,
    "completed_at": 1711288422
  }
}
```

Animate a custom image instead of a preset avatar:

```bash theme={null}
heygen video create -d '{
  "type": "image",
  "image": {"type": "url", "url": "https://example.com/photo.jpg"},
  "script": "Hello from HeyGen.",
  "voice_id": "1bd001e7e50f421d891986aad5e3e5d2"
}' --wait
```

Discover all available request fields:

```bash theme={null}
heygen video create --request-schema
```

***

## Download a Video

Download the video file once it's complete:

```bash theme={null}
heygen video download vid_qr8821 --output-path ./my-video.mp4
```

```json Output theme={null}
{
  "asset": "video",
  "message": "Downloaded video to ./my-video.mp4",
  "path": "./my-video.mp4"
}
```

Download the captioned version (requires `enable_caption` at creation time):

```bash theme={null}
heygen video download vid_qr8821 --asset captioned --output-path ./my-video-captioned.mp4
```

***

## Text to Speech

Generate standalone audio using the `voice speech create` command:

```bash theme={null}
heygen voice speech create \
  --text "Hello world, welcome to HeyGen." \
  --voice-id 1bd001e7e50f421d891986aad5e3e5d2
```

```json Output theme={null}
{
  "data": {
    "audio_url": "https://files.heygen.com/audio/req_abc123.mp3",
    "duration": 2.1,
    "request_id": "req_abc123"
  }
}
```

***

## Design a Voice

Find a voice by describing what you want:

```bash theme={null}
heygen voice create --prompt "warm, confident female narrator"
```

```json Output theme={null}
{
  "data": {
    "voices": [
      {
        "voice_id": "1bd001e7e50f421d891986aad5e3e5d2",
        "name": "Jenny",
        "language": "English",
        "gender": "female",
        "preview_audio_url": "https://files.heygen.com/voice/jenny_preview.mp3"
      }
    ],
    "seed": 0
  }
}
```

Increment `--seed` to get a different batch of results with the same prompt:

```bash theme={null}
heygen voice create --prompt "warm, confident female narrator" --seed 1
```

***

## List and Filter Voices

Browse voices available for TTS:

```bash theme={null}
heygen voice list --language English --gender female --limit 5
```

```json Output theme={null}
{
  "data": [
    {
      "voice_id": "1bd001e7e50f421d891986aad5e3e5d2",
      "name": "Jenny",
      "language": "English",
      "gender": "female",
      "type": "public",
      "preview_audio_url": "https://files.heygen.com/voice/jenny_preview.mp3"
    }
  ],
  "has_more": true,
  "next_token": "eyJsYXN0X2lkIjoiMWJkMDAxZTcifQ"
}
```

***

## Browse Avatar Looks

List all looks available for an avatar group:

```bash theme={null}
heygen avatar looks list --group-id avt_angela_01 --limit 5
```

```json Output theme={null}
{
  "data": [
    {
      "id": "angela_business_01",
      "name": "Business Suit",
      "avatar_type": "studio_avatar",
      "group_id": "avt_angela_01",
      "gender": "female",
      "tags": ["formal", "business"],
      "default_voice_id": "1bd001e7e50f421d891986aad5e3e5d2",
      "preview_image_url": "https://files.heygen.com/look/angela_business_01.jpg"
    }
  ],
  "has_more": false,
  "next_token": null
}
```

The `id` from a look is what you pass as `avatar_id` in `video create`. Get details for a specific look:

```bash theme={null}
heygen avatar looks get angela_business_01
```

***

## Upload an Asset

Upload a file to use as an avatar image, audio source, or attachment in video-agent:

```bash theme={null}
heygen asset create --file ./my-photo.jpg
```

```json Output theme={null}
{
  "data": {
    "asset_id": "ast_abc123",
    "url": "https://files.heygen.com/asset/ast_abc123.jpg",
    "mime_type": "image/jpeg",
    "size_bytes": 204800
  }
}
```

Use the returned `asset_id` anywhere the API accepts an asset input:

```bash theme={null}
heygen video create -d '{
  "type": "image",
  "image": {"type": "asset_id", "asset_id": "ast_abc123"},
  "script": "Hello from my photo.",
  "voice_id": "1bd001e7e50f421d891986aad5e3e5d2"
}' --wait
```

***

## Translate a Video

Dub and lip-sync an existing video into Spanish:

```bash theme={null}
heygen video-translate create \
  --output-languages es \
  --mode precision \
  --wait
```

For complex options (custom audio, SRT files), use `-d`:

```bash theme={null}
cat request.json | heygen video-translate create -d - --wait
```

Without `--wait`:

```json Output theme={null}
{
  "data": {
    "video_translation_ids": ["trl_55f"]
  }
}
```

<Info>
  `--wait` only supports single-language translations. For batch (multiple `output_languages`), poll each ID individually with `heygen video-translate get`.
</Info>

Manage existing translations:

```bash theme={null}
heygen video-translate list
heygen video-translate get trl_55f
heygen video-translate caption get trl_55f --format srt
heygen video-translate delete trl_55f --force
```

***

## Webhooks

Register an endpoint to receive event notifications:

```bash theme={null}
heygen webhook endpoints create \
  --url "https://example.com/webhook" \
  --events "avatar_video.success,avatar_video.fail"
```

```json Output theme={null}
{
  "data": {
    "endpoint_id": "ep_abc123",
    "url": "https://example.com/webhook",
    "events": ["avatar_video.success", "avatar_video.fail"],
    "status": "enabled",
    "created_at": "2025-03-24T14:32:00Z",
    "secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxx"
  }
}
```

<Info>
  Store the `secret` securely — it's used to verify webhook signatures and won't be shown again. Use `heygen webhook endpoints rotate-secret <endpoint-id>` to generate a new one.
</Info>

List all available event types:

```bash theme={null}
heygen webhook event-types list
```

Update or delete an endpoint:

```bash theme={null}
heygen webhook endpoints update ep_abc123 --events "avatar_video.success"
heygen webhook endpoints delete ep_abc123 --force
```

***

## Scripting and Agent Integration

Since JSON is the default output and all non-data output goes to stderr, piping into other tools works without any extra flags.

### Create a video and immediately open it in the browser

```bash theme={null}
VIDEO_ID=$(heygen video-agent create --prompt "Demo video" | jq -r '.data.video_id')
heygen video get "$VIDEO_ID" --wait | jq -r '.data.video_url' | xargs open
```

### Batch translate into multiple languages

```bash theme={null}
for lang in es fr de ja ko; do
  heygen video-translate create \
    --output-languages "$lang" \
    --mode precision \
    --wait --quiet
  echo "✓ $lang done"
done
```

### Create a video, wait, then download it

```bash theme={null}
RESULT=$(heygen video create -d '{
  "type": "avatar",
  "avatar_id": "avt_angela_01",
  "script": "Weekly update for the team.",
  "voice_id": "1bd001e7e50f421d891986aad5e3e5d2"
}' --wait)

STATUS=$(echo "$RESULT" | jq -r '.data.status')
VIDEO_ID=$(echo "$RESULT" | jq -r '.data.id')

if [ "$STATUS" = "completed" ]; then
  heygen video download "$VIDEO_ID" --output-path weekly-update.mp4
fi
```

### Pipe a JSON file into video create

```bash theme={null}
cat request.json | heygen video create -d - --wait
```

### Page through all your videos

```bash theme={null}
# Fetch first page
heygen video list --limit 50

# Fetch next page using the token from the previous response
heygen video list --limit 50 --token "eyJsYXN0X2lkIjoiYXZ0X21hcmN1c18wMiJ9"
```

### List all avatar names (human-readable)

```bash theme={null}
heygen avatar list --human
```

### Check your remaining credits

```bash theme={null}
heygen user me get | jq '.data.wallet'
```


# Features
Source: https://heygen-1fa696a7.mintlify.app/features

Configure the HeyGen CLI with shared flags for output mode, model selection, agent style, and verbose debugging. Use these flags across any CLI command.

## Common Flags

These flags are supported across commands where applicable.

| Flag | Description | Default |
| - | - | - |
| `--human` | Enable rich TUI output (tables, colorized values, readable timestamps) | Off (JSON) |
| `--wait` | Block until async operation completes, subject to `--timeout`. Exits with code `4` if timeout is reached. | Off |
| `--timeout <duration>` | Max wait time when using `--wait` (e.g. `10m`, `1h`) | `20m` |
| `--limit <n>` | Maximum items per page (1–100) | Endpoint-specific |
| `--token <cursor>` | Pagination cursor from a previous response's `next_token` | None |
| `--force` | Skip confirmation prompts for destructive operations | Off (prompt) |
| `-d, --data <json\|path\|->` | JSON request body (inline, file path, or `-` for stdin) | None |
| `--request-schema` | Print the API request body JSON schema and exit (no auth required) | Off |
| `--response-schema` | Print the API response JSON schema and exit (no auth required) | Off |

***

## Async Operations and `--wait`

Commands that create videos or translations return immediately by default with an ID and status. The operation continues in the background.

Add `--wait` to block until the operation completes:

```bash theme={null}
heygen video-agent create --prompt "Welcome to our Q4 earnings call." --wait
```

Without `--wait`, you get the initial response:

```json theme={null}
{
  "data": {
    "session_id": "sess_abc123",
    "status": "generating",
    "video_id": "vid_qr8821"
  }
}
```

With `--wait`, the CLI polls the status endpoint until completion and returns the full resource:

```json theme={null}
{
  "data": {
    "id": "vid_qr8821",
    "status": "completed",
    "video_url": "https://files.heygen.com/video/vid_qr8821.mp4",
    "duration": 12.4,
    "created_at": 1711288320,
    "completed_at": 1711288422
  }
}
```

The default timeout is 20 minutes. Override with `--timeout`:

```bash theme={null}
heygen video create -d '...' --wait --timeout 30m
```

If the timeout is reached, the CLI exits with code `4`. Stdout contains the last known resource state, and stderr contains a hint with the manual polling command:

```json theme={null}
{"error": {"code": "timeout", "message": "polling timed out after 20m0s", "hint": "heygen video get vid_qr8821"}}
```

If the operation reaches a terminal failure state, the CLI exits with code `1`. Stdout contains the failure response (which often includes error details) and stderr contains the error envelope.

`--wait` is supported on:

* `heygen video create`
* `heygen video-agent create`
* `heygen video-translate create`
* `heygen lipsync create`

***

## Complex Request Bodies (`-d` / `--data`)

Endpoints with nested inputs — discriminated unions, arrays of objects, nested configs — use `-d` for raw JSON instead of individual flags:

```bash theme={null}
# Inline JSON
heygen video create -d '{
  "type": "avatar",
  "avatar_id": "avt_angela_01",
  "script": "Hello world",
  "voice_id": "1bd001e7e50f421d891986aad5e3e5d2"
}'

# From a file
heygen video create -d request.json

# From stdin
cat request.json | heygen video create -d -
```

Flags and `-d` can be combined — **flags override matching fields in the JSON body**. This lets you keep a reusable JSON template and tweak individual fields per invocation:

```bash theme={null}
heygen video create -d base.json --wait
```

Use `--request-schema` to discover the expected JSON shape for any command — no auth required:

```bash theme={null}
heygen video create --request-schema
heygen lipsync create --request-schema
```

***

## Pagination

List commands return paginated results. Each response includes `has_more` and `next_token`:

```json theme={null}
{
  "data": [...],
  "has_more": true,
  "next_token": "eyJsYXN0X2lkIjoiYXZ0X21hcmN1c18wMiJ9"
}
```

### Manual pagination

Use `--token` to fetch the next page:

```bash theme={null}
heygen avatar list --limit 10
heygen avatar list --limit 10 --token "eyJsYXN0X2lkIjoiYXZ0X21hcmN1c18wMiJ9"
```

If an agent needs multiple pages, it should read `next_token` from the JSON response and pass it to the next call explicitly. The CLI does not auto-paginate — each page is a separate request.

***

## Stdin Support

Flags that accept long text support reading from stdin with `-`:

```bash theme={null}
# Pipe a script file into video create
cat script.json | heygen video create -d -

# Here-doc
heygen video create -d - <<EOF
{
  "type": "avatar",
  "avatar_id": "avt_angela_01",
  "script": "Welcome to our quarterly update.",
  "voice_id": "1bd001e7e50f421d891986aad5e3e5d2"
}
EOF
```

***

## Destructive Operations and `--force`

Commands that delete resources (`video delete`, `webhook endpoints delete`, `video-translate delete`, `lipsync delete`) prompt for confirmation interactively:

```text theme={null}
⚠ Delete video vid_xyz789? This cannot be undone. [y/N]
```

Use `--force` to skip the prompt — useful in scripts and CI:

```bash theme={null}
heygen video delete vid_xyz789 --force
```

***

## Error Handling

All errors use a consistent JSON envelope on stderr:

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Video not found",
    "hint": "Check ID with: heygen video list",
    "request_id": "req_abc123"
  }
}
```

* `code` — machine-readable error type
* `message` — human-readable description
* `hint` — suggested action to resolve the error
* `request_id` — included when the error comes from the API (from the `X-Request-ID` header). Omitted for local errors (bad flags, missing credentials, network failures).

### Exit Codes

| Code | Meaning | When |
| - | - | - |
| `0` | Success | Operation completed |
| `1` | General error | API 4xx/5xx, network failure, terminal job failure |
| `2` | Usage error | Bad flags, missing required args |
| `3` | Auth error | 401/403, missing or invalid API key |
| `4` | Timeout | Resource was created but polling timed out before completion |

Exit code `4` is distinct from `1` so agents can tell "the job exists but we don't know the final state" apart from a hard failure. Stdout will contain the last known resource state when exit `4` occurs.

### Rate Limiting

`429` responses are retried automatically with exponential backoff, respecting the `Retry-After` header. The error only surfaces if retries are exhausted. The default retry count is 2; override with the `HEYGEN_MAX_RETRIES` environment variable.

***

## Configuration

Persistent settings are managed with `heygen config`:

```bash theme={null}
heygen config set output human      # default to pretty output
heygen config set analytics false   # disable anonymous usage analytics
```

```bash theme={null}
heygen config get output            # read a single value
heygen config list                  # show all config values and their sources
```

Config values are stored locally at `~/.heygen/config.toml`.

### Config keys

| Key | Values | Description |
| - | - | - |
| `output` | `json`, `human` | Default output format (default: `json`) |
| `analytics` | `true`, `false` | Enable or disable anonymous usage analytics |

### Environment variable overrides

| Variable | Description |
| - | - |
| `HEYGEN_API_KEY` | API key (takes precedence over stored credentials) |
| `HEYGEN_OUTPUT` | Output format: `json` or `human` |
| `HEYGEN_NO_ANALYTICS` | Set to any non-empty value to disable analytics |
| `HEYGEN_MAX_RETRIES` | Max retry count for transient failures (default: `2`) |
| `HEYGEN_API_BASE` | Override the API base URL (internal/test use) |

***

## Self-Update

The CLI can update itself:

```bash theme={null}
heygen update                        # install the latest version
heygen update --version v0.1.0       # install a specific version
```

The version flag requires the `v` prefix. Dev builds track dev prereleases; stable builds track stable releases only.

***

## Analytics

The CLI collects anonymous usage analytics to inform product decisions. This includes command usage, error rates, CLI version, and platform. No API keys, scripts, prompts, or personally identifiable information are ever tracked.

Disable analytics at any time:

```bash theme={null}
heygen config set analytics false
```

Or via environment variable:

```bash theme={null}
export HEYGEN_NO_ANALYTICS=1
```

Analytics calls are non-blocking and never slow down the CLI.


# Filler word removal
Source: https://heygen-1fa696a7.mintlify.app/filler-word-removal

Remove filler words and overlong silences from a finished video with the HeyGen Filler Word Removal API — submit a video, get back one cleaned cut with removal statistics.

<img alt="" />

Submit a video and get back a cleaned version with the "um"s, "uh"s, and overlong silences cut out. The job transcribes the audio, detects filler words, removes them along with dead air, and renders one finished video — no review step, no edit decisions to make. It's built for recordings where a human spoke off the cuff: webinars, screen recordings, interviews, all-hands.

## Create a Removal Job

* Endpoint: [`POST /v3/filler-word-removals`](/reference/create-filler-word-removal)
* Purpose: Start a removal job for a source video. Returns a `filler_word_removal_id` to poll.

### Quick Example

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/filler-word-removals" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video": { "type": "url", "url": "https://example.com/webinar.mp4" },
    "title": "Q3 webinar — cleaned"
  }'
```

```json Response theme={null}
{
  "data": {
    "filler_word_removal_id": "b4f0c2a91de843f6a2d07c5e8a913f27"
  }
}
```

The endpoint returns `202 Accepted` immediately; the job runs asynchronously.

### Request Body

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `video` | object | Yes | — | Source video with a speech audio track. Provide as `{ "type": "url", "url": "https://..." }` or `{ "type": "asset_id", "asset_id": "..." }` (from [`POST /v3/assets`](/reference/upload-asset) — see [Upload Assets](/docs/upload-assets)). Sources up to 2 hours long are supported. |
| `title` | string | No | `Filler Removal` | Display title for the job. |
| `callback_url` | string | No | — | [Webhook](/docs/webhooks) URL — receives a POST when the job completes or fails (`filler_word_removal.success` / `filler_word_removal.fail`). |
| `callback_id` | string | No | — | Arbitrary ID echoed back in the webhook payload. |

### Idempotency

Pass an `Idempotency-Key` header to make retries safe — replaying the same key returns the original job instead of creating a duplicate.

## Get a Removal Job

* Endpoint: [`GET /v3/filler-word-removals/{filler_word_removal_id}`](/reference/get-filler-word-removal)
* Purpose: Fetch a job's live status and, once it completes, the cleaned video plus removal statistics.

### Quick Example

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/filler-word-removals/b4f0c2a91de843f6a2d07c5e8a913f27" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

### Path Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `filler_word_removal_id` | string | Yes | Unique job identifier returned by `POST /v3/filler-word-removals`. |

### Response

```json theme={null}
{
  "data": {
    "id": "b4f0c2a91de843f6a2d07c5e8a913f27",
    "title": "Q3 webinar — cleaned",
    "status": "completed",
    "progress": 100,
    "video_url": "https://files2.heygen.ai/filler-removal/.../output.mp4?Expires=...",
    "thumbnail_url": "https://resource2.heygen.ai/video/thumbnail/....webp",
    "original_duration": 512.6,
    "output_duration": 471.9,
    "num_cuts": 23,
    "reduction_pct": 7.9,
    "created_at": 1785650000
  }
}
```

### Response Fields

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique job identifier. |
| `title` | string or null | Display title for the job. |
| `status` | string | Job lifecycle status: `pending`, `running`, `completed`, or `failed`. |
| `progress` | integer | Approximate progress (0–100). `100` when completed. |
| `video_url` | string or null | Pre-signed MP4 download URL of the cleaned video. Present when status is `completed`. |
| `thumbnail_url` | string or null | Pre-signed thumbnail URL, when a thumbnail was generated. |
| `original_duration` | number or null | Duration of the source video in seconds. |
| `output_duration` | number or null | Duration of the cleaned video in seconds. |
| `num_cuts` | integer or null | Number of filler segments removed. Counts filler cuts only — a job that trimmed silences alone reports `num_cuts: 0` with a positive `reduction_pct`. |
| `reduction_pct` | number or null | Percentage of the source duration removed. |
| `callback_id` | string or null | Client-provided callback ID echoed from the create request. Only present when you supplied one. |
| `created_at` | integer | Unix timestamp (seconds) of job creation. |
| `failure_message` | string or null | Error description. Only present when status is `failed`. |

<Note>
  `video_url` is a pre-signed link with a limited lifetime. Download the file soon after the job completes, or re-fetch this endpoint for a fresh link.
</Note>

A completed job always carries a `video_url` — when the run finds nothing to cut, the output is a copy of the original video and the charge is automatically refunded, so your polling code never needs a special no-change branch.

## Polling Pattern

Removal jobs are processed asynchronously. Poll until status reaches `completed` or `failed`.

Status transitions: `pending` → `running` → `completed` | `failed`

```bash theme={null}
while true; do
  STATUS=$(curl -s "https://api.heygen.com/v3/filler-word-removals/$JOB_ID" \
    -H "X-Api-Key: $HEYGEN_API_KEY" | jq -r '.data.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] && break
  sleep 10
done
```

For long recordings, prefer a [`callback_url`](/docs/webhooks) over tight polling — HeyGen will POST you the finished job instead (`filler_word_removal.success` / `filler_word_removal.fail` [webhook events](/docs/webhook-events)). Treat the webhook as a completion signal and fetch the authoritative result from [`GET /v3/filler-word-removals/{filler_word_removal_id}`](/reference/get-filler-word-removal).

## Asset Inputs

The `video` field accepts two input formats:

**By URL** — any publicly accessible HTTPS link:

```json theme={null}
{ "type": "url", "url": "https://example.com/recording.mp4" }
```

**By asset ID** — reference a file previously uploaded via [`POST /v3/assets`](/reference/upload-asset) (see [Upload Assets](/docs/upload-assets)):

```json theme={null}
{ "type": "asset_id", "asset_id": "asset_xyz789" }
```

Either way, the source needs a speech audio track to transcribe and can be up to 2 hours long.

## Full Example

```python theme={null}
import time
import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://api.heygen.com"
HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}


def remove_fillers(video_url, title=None):
    """Start a removal job, wait for it, and return the finished job."""
    body = {"video": {"type": "url", "url": video_url}}
    if title:
        body["title"] = title

    job_id = requests.post(
        f"{BASE}/v3/filler-word-removals", headers=HEADERS, json=body
    ).json()["data"]["filler_word_removal_id"]

    while True:
        job = requests.get(
            f"{BASE}/v3/filler-word-removals/{job_id}", headers=HEADERS
        ).json()["data"]
        if job["status"] in ("completed", "failed"):
            break
        time.sleep(10)

    if job["status"] == "failed":
        raise RuntimeError(job.get("failure_message") or "removal job failed")
    return job


job = remove_fillers("https://example.com/webinar.mp4", title="Q3 webinar — cleaned")
print(f"{job['num_cuts']} cuts, {job['reduction_pct']}% shorter -> {job['video_url']}")
```

Cleaning a recording before repurposing it? Run filler removal first, then hand the cleaned video to [AI clipping](/ai-clipping) for highlights — and score the cuts with [background music](/background-music) and [sound effects](/sound-effects) from the same Tools suite.


# Folders
Source: https://heygen-1fa696a7.mintlify.app/folders

Create folders in your HeyGen workspace over the API and place generated videos and translations in them. Folders show up in the HeyGen web app.

<img alt="" />

Create a folder, then pass its `folder_id` when you generate. The output lands in that folder in the HeyGen web app.

| Endpoint | Scope |
| - | - |
| [`POST /v3/folders`](/reference/create-folder) | `videos:write` |
| [`GET /v3/folders/{folder_id}`](/reference/get-folder) | `videos:read` |

A key scoped only to `translations:write` can place translations in a folder, but cannot create or read one.

## Create a folder

```bash theme={null}
curl -X POST https://api.heygen.com/v3/folders \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: course-42-module-3" \
  -d '{
    "name": "Module 3 - Deploying to production",
    "parent_id": "a2b9e4c1d7f04e3a9c6b5d8e1f2a3b4c"
  }'
```

```json Response theme={null}
{
  "data": {
    "folder_id": "7c1f0b2e3d4a4f5e8a9b0c1d2e3f4a5b",
    "name": "Module 3 - Deploying to production",
    "parent_id": "a2b9e4c1d7f04e3a9c6b5d8e1f2a3b4c",
    "type": "mixed",
    "is_trash": false,
    "created_at": 1711929600,
    "updated_at": 1711929600,
    "creator_username": "e5f6a7b8c9d04e1f8a2b3c4d5e6f7a8b"
  }
}
```

| Field | Notes |
| - | - |
| `name` | Required, 1-256 characters. |
| `parent_id` | Folder to nest inside: must be in your workspace and not in the trash. Assets library folders (`type: "asset"`) can't be a parent, since they don't hold other folders. Omit, `null`, or `""` for the workspace root, where the response has no `parent_id`. |
| `type` | `mixed` (default), `video`, or `video_translate`. All three accept videos and translations. |

## Put content in it

Pass `folder_id` on any of these:

* [`POST /v3/videos`](/reference/create-video)
* [`POST /v3/video-translations`](/reference/create-video-translation)
* [`POST /v3/video-translations/proofreads`](/reference/create-proofread-session)
* [`POST /v3/lipsyncs`](/reference/create-lipsync)
* [`POST /v3/templates/{template_id}`](/reference/generate-video-from-template)

```json theme={null}
{
  "type": "avatar",
  "avatar_id": "...",
  "script": "...",
  "folder_id": "7c1f0b2e3d4a4f5e8a9b0c1d2e3f4a5b"
}
```

The folder must be in your workspace, not in the trash, and writable by you. Otherwise the request returns `404` before anything is created.

Existing folders from the HeyGen app's Assets library are also accepted as a `folder_id`, and come back from `GET /v3/folders/{folder_id}` with `type: "asset"`. The Assets library view lists only assets, so a video or translation placed there may not show up in it. `POST /v3/folders` cannot create these folders, and they cannot hold other folders, so they are never a valid `parent_id`.

## Check a folder

[`GET /v3/folders/{folder_id}`](/reference/get-folder) confirms a stored id still exists. Trashed folders return `is_trash: true`. Any other id (deleted, another workspace's, or not a folder) returns `404`.

<Tip>
  Folder names can repeat, and the API never matches by name. Store the ids you get back, and send an `Idempotency-Key` so a retry returns the same folder.
</Tip>


# Digital Twin
Source: https://heygen-1fa696a7.mintlify.app/generate-avatar-video

Generate AI avatar video from a script with the HeyGen API. Pick an avatar, voice, and background; HeyGen handles rendering, captions, and final export.

<img alt="" />

## Prerequisites

<Check>
  A Digital Twin `avatar_id` (type: `digital_twin`). Use `GET /v3/avatars/looks?avatar_type=digital_twin` to find yours.
</Check>

<Check>
  A `voice_id` for the voice you want. Use `GET /v3/voices` to browse available voices.
</Check>

## Step 1 — Find your Digital Twin

List your private Digital Twin looks to get the `avatar_id`:

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/avatars/looks?avatar_type=digital_twin&ownership=private" \
  -H "x-api-key: YOUR_API_KEY"
```

From the response, copy the `id` field of the look you want. This is your `avatar_id`.

## Step 2 — Choose a rendering engine

HeyGen v3 supports three rendering engines for Digital Twins. You select the engine via the `engine` object in your video creation request.

| Engine | Key | Default? | Quality |
| - | - | - | - |
| Avatar IV | `avatar_iv` | Yes — used when `engine` is omitted | Standard, widely supported |
| Avatar V | `avatar_v` | No — must be explicitly requested | Higher quality, cross-reference-driven animation |
| Avatar III | `avatar_iii` | No — must be explicitly requested | Dedicated photo-to-video pipeline |

<Note>
  Before requesting an engine, check the `supported_api_engines` array on the avatar look via `GET /v3/avatars/looks/{look_id}` — it lists which of `avatar_iii`, `avatar_iv`, and `avatar_v` the look accepts, and requesting an engine that isn't listed will be rejected. See [Models](/models) for full details on each engine.
</Note>

## Step 3 — Create the video

Send a `POST` request to `/v3/videos` with `type: "avatar"`, your Digital Twin ID, a script, and a voice.

A `type: "avatar"` request renders one scene, so its script or audio must stay within **30 minutes**. For a longer piece, compose it as a [studio video](/studio-videos) with several scenes — see [Usage Limits](/docs/usage-limits#output-video-specifications).

### Using Avatar IV (default)

Omit the `engine` field or pass `{"type": "avatar_iv"}` — Avatar IV is the default:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar",
    "avatar_id": "YOUR_DIGITAL_TWIN_LOOK_ID",
    "script": "Hello! I am your Digital Twin. This video was generated entirely through the HeyGen API.",
    "voice_id": "YOUR_VOICE_ID",
    "title": "My First Digital Twin Video",
    "resolution": "1080p",
    "aspect_ratio": "auto"
  }'
```

### Using Avatar V (higher quality)

Pass `{"type": "avatar_v"}` in the `engine` field to request cross-reference-driven animation:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar",
    "avatar_id": "YOUR_DIGITAL_TWIN_LOOK_ID",
    "script": "Hello! I am your Digital Twin.",
    "voice_id": "YOUR_VOICE_ID",
    "title": "My Digital Twin — Avatar V",
    "resolution": "1080p",
    "aspect_ratio": "auto",
    "engine": { "type": "avatar_v" }
  }'
```

<Note>
  `motion_prompt` is supported on both Avatar IV and Avatar V — pass a natural-language prompt to control body motion and hand gestures.

  `expressiveness` remains an Avatar IV-only parameter. Do not include it when using Avatar V — it will cause a validation error.
</Note>

## Step 4 — Poll for completion

Video generation is asynchronous. Poll `GET /v3/videos/{video_id}` until `status` is `completed`:

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/videos/YOUR_VIDEO_ID" \
  -H "x-api-key: YOUR_API_KEY"
```

### Status values

| Status | Meaning |
| - | - |
| `pending` | Queued for processing |
| `processing` | Video is being generated |
| `completed` | Ready — `video_url` is available |
| `failed` | Something went wrong — check `failure_message` |

Once completed, the response includes everything you need to download and display the result:

| Field | What it is |
| - | - |
| `video_url` | The rendered video. Captions are burned in only when you request a caption `style` — otherwise this is always the clean render. |
| `captioned_video_url` | The video with captions burned in, when caption burn-in was requested. |
| `subtitle_url` | The SRT subtitle sidecar file, when captions were requested. |
| `thumbnail_url` | Still thumbnail image. |
| `gif_url` | Animated GIF preview. |
| `duration` | Video length in seconds. |

These are presigned URLs with a limited expiry window — download promptly, or call `GET /v3/videos/{video_id}` again to get fresh URLs. When `status` is `failed`, the response includes a machine-readable `failure_code` alongside the human-readable `failure_message`.

## Full example

```python theme={null}
import requests
import time

API_KEY = "YOUR_API_KEY"
BASE = "https://api.heygen.com"
HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}

# 1. Create the video (Avatar V — swap engine for {"type": "avatar_iv"} or omit for default)
resp = requests.post(f"{BASE}/v3/videos", headers=HEADERS, json={
    "type": "avatar",
    "avatar_id": "YOUR_DIGITAL_TWIN_LOOK_ID",
    "script": "Welcome to our product demo. Let me walk you through the new features.",
    "voice_id": "YOUR_VOICE_ID",
    "resolution": "1080p",
    "aspect_ratio": "auto",
    "engine": {"type": "avatar_v"}  # omit entirely to use Avatar IV (default)
})
video_id = resp.json()["data"]["video_id"]
print(f"Video created: {video_id}")

# 2. Poll until done
while True:
    status_resp = requests.get(f"{BASE}/v3/videos/{video_id}", headers=HEADERS)
    data = status_resp.json()["data"]
    print(f"Status: {data['status']}")
    if data["status"] == "completed":
        print(f"Download: {data['video_url']}")
        break
    elif data["status"] == "failed":
        print(f"Error: {data.get('failure_message')}")
        break
    time.sleep(10)
```

## Optional parameters

| Parameter | Type | Engine | Description |
| - | - | - | - |
| `title` | string | Both | Display name in the HeyGen dashboard |
| `resolution` | string | Both | `1080p` (recommended) or `720p`. `4k` is available on Avatar III |
| `aspect_ratio` | string | Both | `auto` (recommended — matches the source, falling back to `16:9`), `16:9`, `9:16`, `4:5`, `5:4`, or `1:1` |
| `engine` | object | — | `{"type": "avatar_iv"}`, `{"type": "avatar_v"}`, or `{"type": "avatar_iii"}`. Defaults to Avatar IV when omitted |
| `remove_background` | boolean | Both | Removes the avatar background (supported by default on new digital twins) |
| `background` | object | Both | Set a solid color or image background |
| `voice_settings` | object | Both | Adjust `speed` (0.5–1.5), `pitch` (-50 to +50), and `locale` |
| `motion_prompt` | string | Both | Natural-language prompt controlling avatar body motion and hand gestures |
| `expressiveness` | string | IV only | `high`, `medium`, or `low`. Defaults to `low` |
| `output_format` | string | Both | `mp4` (default) or `webm` (transparent background / alpha channel) |
| `caption` | object | Both | Caption settings — see [Captions and subtitles](#captions-and-subtitles) |
| `callback_url` | string | Both | Webhook URL — receive a POST when the video is ready |

## Captions and subtitles

Captions are off by default — omit `caption` and `video_url` is a clean render with no subtitles. To generate captions, pass a `caption` object:

```json theme={null}
{
  "caption": { "file_format": "srt" }
}
```

This returns a sidecar subtitle file via `subtitle_url` in the status response, while the video itself stays clean — you control how subtitles display in your own player. To additionally burn captions into the rendered video, set a `style`:

```json theme={null}
{
  "caption": { "file_format": "srt", "style": "default" }
}
```

<Note>
  `caption` is an object on `/v3/videos`. Boolean-style fields like `caption: true` or `enable_caption` (used by the v2 API and by the [template endpoint](/templates)) fail `/v3/videos` validation with `invalid_parameter` ("Extra inputs are not permitted"). Use the object form above.
</Note>

If a downloaded video shows captions you didn't ask for, you most likely grabbed `captioned_video_url` (or the `url` from a webhook payload that points at the captioned render). Fetch [`GET /v3/videos/{video_id}`](/reference/get-video) and download `video_url` for the caption-free file.

## Using webhooks instead of polling

Instead of polling, pass a `callback_url` when creating the video. HeyGen will send a POST request to that URL when the video completes or fails.

```json theme={null}
{
  "type": "avatar",
  "avatar_id": "YOUR_DIGITAL_TWIN_LOOK_ID",
  "script": "This video uses a webhook callback.",
  "voice_id": "YOUR_VOICE_ID",
  "callback_url": "https://your-server.com/webhooks/heygen"
}
```

<Note>
  Register a webhook endpoint via `POST /v3/webhooks/endpoints` and subscribe to `avatar_video.success` and `avatar_video.fail` events for production use.
</Note>


# Hyperframes Cloud Rendering
Source: https://heygen-1fa696a7.mintlify.app/hyperframes

Render programmatic, code-driven video with the HeyGen Hyperframes API. Upload an HTML project bundle, inject runtime variables, and HeyGen renders it to MP4, WebM, or MOV.

<img alt="" />

Hyperframes turns a self-contained HTML/CSS/JS project into a rendered video. You package your composition as a `.zip`, upload it, and HeyGen runs it through a headless renderer — ideal for motion graphics, data-driven visuals, and templated pipelines. For worked examples, see the [Hyperframes cookbook](/motion-graphics).

If you work from a terminal, [`hyperframes cloud render`](https://hyperframes.heygen.com/deploy/cloud) in the Hyperframes CLI wraps this entire flow — it zips your project, uploads it, submits the render, polls, and downloads the finished video in one command. This page documents the underlying API so you can build the same pipeline into your own application.

## Prerequisites

<Check>
  A project `.zip` containing an `index.html` at the root (or at the path you set in `composition`), plus any CSS, JS, fonts, and assets it needs. The bundle must render standalone in a browser.
</Check>

<Check>
  The zip available as a `url`, an uploaded `asset_id`, or `base64`. Use [Assets](/assets) to upload a file and get an `asset_id`.
</Check>

When zipping, include only what the composition needs — leave out `.git`, `node_modules`, and build output like `dist`. A lean bundle uploads faster, and `asset_id` uploads accept larger projects than the `url` and `base64` caps (see [`hyperframes_project_too_large`](/docs/error-codes#hyperframes-project-too-large)).

## How a render flows

A render is three API calls end to end — upload the bundle, submit the render, then poll (or [take a webhook](#using-webhooks-instead-of-polling)) until the video is ready:

```
 Your app                              HeyGen cloud
┌─────────────────────────┐          ┌─────────────────────────────────┐
│ zip the project         │ ──POST──▶│ /v3/assets                      │
│                         │  upload  │  → asset_id                     │
│                         │          │                                 │
│                         │ ──POST──▶│ /v3/hyperframes/renders         │
│                         │  submit  │  → render_id (queued)           │
│                         │          │  Chromium + FFmpeg render       │
│ poll GET /renders/{id}  │ ◀────────│  queued → rendering → completed │
│ download the video      │ ◀────────│  presigned video_url            │
└─────────────────────────┘          └─────────────────────────────────┘
```

1. **Upload** the project zip to `POST /v3/assets` and note the `asset_id`. (For small or already-hosted bundles, skip this step and pass the project as `url` or `base64` instead.)
2. **Submit** the render to `POST /v3/hyperframes/renders`, which returns a `render_id` immediately.
3. **Poll** `GET /v3/hyperframes/renders/{render_id}` until the status is `completed`, then download the video from the presigned `video_url`.

The sections below walk through each call.

## Step 1 — Build your composition

Author an HTML page that renders your scene. Hyperframes compositions are standard, self-contained web pages — for the composition framework, component APIs, and local preview and render tooling, see the [Hyperframes developer docs](https://hyperframes.heygen.com/packages/core). To explore, remix, and learn from community-built compositions, browse the [Community Playground](https://www.hyperframes.dev).

To make a render data-driven, read values from `data-composition-variables` on the document — HeyGen overrides these with the `variables` object you send at render time, so one bundle can produce many videos (see [Upload once, render many](#upload-once-render-many) below). The renderer validates the bundle when the render starts; a zip without a usable entry file fails with [`hyperframes_project_invalid`](/docs/error-codes#hyperframes-project-invalid), so preview the project locally (or run it through the Hyperframes CLI) before submitting.

## Step 2 — Create a render

`POST /v3/hyperframes/renders` with your project bundle. The call returns `202 Accepted` with a `render_id`:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/hyperframes/renders" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": { "type": "asset_id", "asset_id": "YOUR_PROJECT_ZIP_ASSET_ID" },
    "fps": 30,
    "quality": "standard",
    "format": "mp4",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "composition": "index.html",
    "variables": { "headline": "Q2 Revenue", "value": "$1.2M" },
    "title": "Q2 revenue motion graphic"
  }'
```

```json theme={null}
{
  "data": {
    "render_id": "hfr_abc123"
  }
}
```

## Step 3 — Poll for completion

Poll `GET /v3/hyperframes/renders/{render_id}` until `status` is `completed`:

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/hyperframes/renders/YOUR_RENDER_ID" \
  -H "x-api-key: YOUR_API_KEY"
```

| Status | Meaning |
| - | - |
| `queued` | Accepted and waiting for a renderer |
| `rendering` | Render in progress |
| `completed` | Ready — `video_url` and `thumbnail_url` are available |
| `failed` | Something went wrong — check `failure_message` |

A completed render returns the full `HyperframesRenderDetail`, including `video_url`, `thumbnail_url`, `duration`, and the settings the render used.

<Note>
  `video_url` and `thumbnail_url` are short-lived presigned URLs. Download the video promptly, and when you need a fresh link later, re-fetch the render with `GET /v3/hyperframes/renders/{render_id}` rather than storing the URL.
</Note>

## Upload once, render many

The idiomatic template workflow: upload the project zip to [Assets](/assets) once, then submit as many renders as you need against the same `asset_id`, each with different `variables` — no re-zip, no re-upload:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/hyperframes/renders" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": { "type": "asset_id", "asset_id": "YOUR_PROJECT_ZIP_ASSET_ID" },
    "variables": { "name": "Ada", "theme": "dark" }
  }'

curl -X POST "https://api.heygen.com/v3/hyperframes/renders" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": { "type": "asset_id", "asset_id": "YOUR_PROJECT_ZIP_ASSET_ID" },
    "variables": { "name": "Linus", "theme": "light" }
  }'
```

Declare the variables (and their types) in the composition's `data-composition-variables`; the renderer validates the `variables` you send against that schema when the render runs.

## Managing renders

List your renders (paginated) with `GET /v3/hyperframes/renders`, or remove one with `DELETE /v3/hyperframes/renders/{render_id}`:

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/hyperframes/renders" \
  -H "x-api-key: YOUR_API_KEY"

curl -X DELETE "https://api.heygen.com/v3/hyperframes/renders/YOUR_RENDER_ID" \
  -H "x-api-key: YOUR_API_KEY"
```

## Full example

```python theme={null}
import requests
import time

API_KEY = "YOUR_API_KEY"
BASE = "https://api.heygen.com"
HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}

# 1. Submit the render
resp = requests.post(f"{BASE}/v3/hyperframes/renders", headers=HEADERS, json={
    "project": {"type": "asset_id", "asset_id": "YOUR_PROJECT_ZIP_ASSET_ID"},
    "fps": 30,
    "quality": "standard",
    "format": "mp4",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "variables": {"headline": "Q2 Revenue", "value": "$1.2M"},
})
render_id = resp.json()["data"]["render_id"]
print(f"Render queued: {render_id}")

# 2. Poll until done
while True:
    status_resp = requests.get(f"{BASE}/v3/hyperframes/renders/{render_id}", headers=HEADERS)
    data = status_resp.json()["data"]
    print(f"Status: {data['status']}")
    if data["status"] == "completed":
        print(f"Download: {data['video_url']}")
        break
    elif data["status"] == "failed":
        print(f"Error: {data.get('failure_message')}")
        break
    time.sleep(10)
```

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `project` | object | Yes | The project `.zip` as a `url`, `asset_id`, or `base64` input |
| `fps` | integer | No | Frames per second, 1–240. Default `30` |
| `quality` | string | No | `draft`, `standard` (default), or `high` |
| `format` | string | No | `mp4` (default), `webm`, or `mov`. `webm` and `mov` carry an alpha channel for transparent overlays |
| `resolution` | string | No | `1080p` (default) or `4k` |
| `aspect_ratio` | string | No | `16:9` (default), `9:16`, or `1:1` |
| `composition` | string | No | Entry HTML path inside the zip. Default `index.html` |
| `variables` | object | No | Key–value overrides for `data-composition-variables` |
| `title` | string | No | Display name, ≤500 characters |
| `callback_id` | string | No | Your own correlation ID, ≤256 characters, echoed back in the webhook |
| `callback_url` | string | No | Webhook URL — receive a POST when the render finishes |

<Note>
  Render `4k` as `mp4`; the 4k supersampling pipeline produces opaque frames. For transparent output, render `webm` or `mov` at `1080p`.
</Note>

## Safe retries

Both `POST /v3/assets` and `POST /v3/hyperframes/renders` accept an `Idempotency-Key` header, so a network failure or timeout never leaves you guessing whether the upload or render went through — retry with the same key and the API replays the original response instead of creating (and billing) a duplicate:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/hyperframes/renders" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{ "project": { "type": "asset_id", "asset_id": "YOUR_PROJECT_ZIP_ASSET_ID" } }'
```

Keys are 1–255 characters from `[A-Za-z0-9_:.-]` — a UUID is a safe default. Replays work for 24 hours, and a retry that arrives while the original is still processing gets a `409` [`request_in_progress`](/docs/error-codes#request-in-progress). Idempotency is scoped per endpoint, so reusing one key for an upload and its follow-up render is safe.

## Using webhooks instead of polling

Pass a `callback_url` (and optionally a `callback_id` to correlate the response) when you submit the render. HeyGen posts to it whether or not anything is polling, so you can submit the render and walk away — true fire-and-forget. Register an endpoint via `POST /v3/webhooks/endpoints` and subscribe to the `hyperframes_video.success` and `hyperframes_video.fail` events described in [Webhook Events](/docs/webhook-events).


# Hyperframes Use Cases
Source: https://heygen-1fa696a7.mintlify.app/hyperframes-heygen

Combine a HeyGen avatar video with background music, sound effects, and Hyperframes graphics into one finished, produced video — all through the HeyGen API.

<img alt="" />

The HeyGen API gives you the pieces — a talking [avatar](/generate-avatar-video), [background music](/background-music), and [sound effects](/sound-effects). **Hyperframes composites them into one video**: drop the avatar clip into a designed scene, add graphics, score it, and render to a single MP4.

This guide wires all four APIs into one pipeline:

<Steps>
  <Step title="Generate the avatar video">
    Create the talking-head clip with [`POST /v3/videos`](/reference/create-video). Pick an engine — [Avatar IV](/avatar-iv) (default), [Avatar V](/avatar-v) (highest fidelity), or [Avatar III](/avatar-iii) — then poll until it's `completed` and keep the `video_url`.

    ```bash theme={null}
    curl -X POST "https://api.heygen.com/v3/videos" \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "avatar",
        "avatar_id": "YOUR_LOOK_ID",
        "script": "Here are our Q2 results.",
        "voice_id": "YOUR_VOICE_ID",
        "resolution": "1080p",
        "engine": { "type": "avatar_v" }
      }'
    ```

    Poll `GET /v3/videos/{video_id}` until `status` is `completed`, then read `video_url`. See the [Digital Twin guide](/generate-avatar-video) for the full request-and-poll flow.
  </Step>

  <Step title="Find background music">
    Search the music catalog with a plain-language description and take the top track's `audio_url` ([Background music](/background-music)).

    ```bash theme={null}
    curl -X GET "https://api.heygen.com/v3/audio/sounds?query=upbeat%20corporate%20background&limit=1" \
      -H "x-api-key: YOUR_API_KEY"
    ```
  </Step>

  <Step title="Find sound effects">
    Same endpoint, with `type=sound_effects` — grab a whoosh for your title reveal or a chime for a stat pop ([Sound effects](/sound-effects)).

    ```bash theme={null}
    curl -X GET "https://api.heygen.com/v3/audio/sounds?query=whoosh%20for%20a%20scene%20change&type=sound_effects&limit=1" \
      -H "x-api-key: YOUR_API_KEY"
    ```

    <Note>
      Each `audio_url` is a short-lived pre-signed link. Feed it straight into the render step below rather than caching it.
    </Note>
  </Step>

  <Step title="Compose the scene in Hyperframes">
    Build a composition that arranges the avatar clip and audio inside a designed frame. Expose each asset URL as a [composition variable](/hyperframes-overview#core-concepts) so you can inject the URLs from steps 1–3 at render time — the same bundle then works for any avatar clip and any track.

    ```html index.html theme={null}
    <body
      data-composition-variables='{
        "avatarUrl": "",
        "musicUrl": "",
        "sfxUrl": ""
      }'
    >
      <!-- The avatar clip, placed into your branded scene -->
      <video data-hf-src="avatarUrl" class="avatar"></video>

      <!-- Lower third, titles, charts — your motion graphics go here -->
      <div class="lower-third">Q2 Revenue · $1.2M</div>

      <!-- Score + one-shot sound effect, layered over the scene -->
      <audio data-hf-src="musicUrl" data-hf-volume="0.3"></audio>
      <audio data-hf-src="sfxUrl" data-hf-start="0.5"></audio>
    </body>
    ```

    <Note>
      The exact media, timing, and audio APIs live in the [Hyperframes developer docs](https://hyperframes.heygen.com/packages/core) — the snippet above is illustrative. For design patterns, see the [Hyperframes cookbook](/motion-graphics).
    </Note>
  </Step>

  <Step title="Render the finished video">
    Package the composition as a `.zip`, then submit it to [`POST /v3/hyperframes/renders`](/hyperframes), passing the URLs from the earlier steps as `variables`. HeyGen renders the composed scene — avatar, graphics, music, and SFX baked into one file.

    ```bash theme={null}
    curl -X POST "https://api.heygen.com/v3/hyperframes/renders" \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "project": { "type": "asset_id", "asset_id": "YOUR_PROJECT_ZIP_ASSET_ID" },
        "format": "mp4",
        "resolution": "1080p",
        "aspect_ratio": "16:9",
        "variables": {
          "avatarUrl": "https://.../avatar-video.mp4",
          "musicUrl": "https://.../background-music.wav",
          "sfxUrl": "https://.../whoosh.wav"
        },
        "title": "Q2 results — composed"
      }'
    ```

    Poll `GET /v3/hyperframes/renders/{render_id}` until `status` is `completed` and download the final `video_url`. Full render options are in [Hyperframes Cloud Rendering](/hyperframes).
  </Step>
</Steps>

## End-to-end example

```python theme={null}
import requests, time

API_KEY = "YOUR_API_KEY"
BASE = "https://api.heygen.com"
HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}


def poll(url, done="completed", key="status"):
    while True:
        data = requests.get(url, headers=HEADERS).json()["data"]
        if data[key] == done:
            return data
        if data[key] == "failed":
            raise RuntimeError(data.get("failure_message", "job failed"))
        time.sleep(10)


# 1. Avatar video
vid = requests.post(f"{BASE}/v3/videos", headers=HEADERS, json={
    "type": "avatar",
    "avatar_id": "YOUR_LOOK_ID",
    "script": "Here are our Q2 results.",
    "voice_id": "YOUR_VOICE_ID",
    "resolution": "1080p",
    "engine": {"type": "avatar_v"},
}).json()["data"]
avatar_url = poll(f"{BASE}/v3/videos/{vid['video_id']}")["video_url"]

# 2 + 3. Music and a sound effect (same endpoint, different type)
music_url = requests.get(
    f"{BASE}/v3/audio/sounds?query=upbeat corporate background&limit=1",
    headers=HEADERS).json()["data"][0]["audio_url"]
sfx_url = requests.get(
    f"{BASE}/v3/audio/sounds?query=whoosh for a scene change&type=sound_effects&limit=1",
    headers=HEADERS).json()["data"][0]["audio_url"]

# 4 + 5. Compose everything in Hyperframes and render
render = requests.post(f"{BASE}/v3/hyperframes/renders", headers=HEADERS, json={
    "project": {"type": "asset_id", "asset_id": "YOUR_PROJECT_ZIP_ASSET_ID"},
    "format": "mp4",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "variables": {
        "avatarUrl": avatar_url,
        "musicUrl": music_url,
        "sfxUrl": sfx_url,
    },
    "title": "Q2 results — composed",
}).json()["data"]
final = poll(f"{BASE}/v3/hyperframes/renders/{render['render_id']}")
print("Final video:", final["video_url"])
```

<Tip>
  Every step here is also available through the [HeyGen MCP](/mcp/overview), so an agent can run the whole avatar → audio → compose → render pipeline on its own.
</Tip>

## Related

* [Introduction to Hyperframes](/hyperframes-overview) — what the framework is and how compositions work
* [Hyperframes Cloud Rendering](/hyperframes) — the full render API, parameters, and webhooks
* [Generate Avatar Video](/generate-avatar-video) · [Background music](/background-music) · [Sound effects](/sound-effects)


# Introduction to Hyperframes
Source: https://heygen-1fa696a7.mintlify.app/hyperframes-overview

Hyperframes turns HTML compositions into rendered video — a code-driven, deterministic video framework built for agents and developers. Write HTML, render video.

<img alt="" />

**Hyperframes is a video framework that turns an HTML composition into a rendered video.** You author a scene as a self-contained HTML/CSS/JS page, and Hyperframes plays its timeline through a headless browser and encodes the result to a video file. The tagline says it best: **write HTML, render video — built for agents.**

<Frame>
  <video>
    <source type="video/mp4" />
  </video>
</Frame>

If you can build a web page, you can build a video. And because the whole composition is code, it's trivial for an AI agent or a backend pipeline to generate, parameterize, and render thousands of variations without ever opening a video editor.

<Note>
  This page introduces the framework and its concepts. When you're ready to render on HeyGen's infrastructure via the API, go to [Hyperframes Cloud Rendering](/hyperframes).
</Note>

## Why Hyperframes

* **HTML is the timeline.** Compositions are ordinary web pages — HTML, CSS, JavaScript, [GSAP](https://gsap.com/) animations, WebGL shaders. No proprietary editor format to learn.
* **Deterministic rendering.** Same input, identical output, every time. A composition renders frame-for-frame identically whether it runs on your laptop or HeyGen's cloud — essential for reproducible, automated pipelines.
* **Parameterized by design.** Read runtime values from the document and override them at render time, so one bundle produces many videos (see [Variables](#core-concepts) below).
* **Built for agents and pipelines.** Programmatic authoring and rendering means an LLM or a service can produce finished video end to end.
* **A rich component library.** 150+ prebuilt blocks and components — code animations, data visualizations, social cards, lower thirds, shader transitions, device mockups, and more.

## See what you can build

Every clip below is a catalog block — pure HTML/CSS/JS, rendered to video by Hyperframes. Click any preview to open its source in the [catalog](https://hyperframes.heygen.com/catalog).

## How it works

<Steps>
  <Step title="Author a composition">
    Build a scene as a self-contained HTML page — layout in CSS, motion in GSAP or your animation runtime of choice, timing driven by Hyperframes data attributes.
  </Step>

  <Step title="Preview and iterate">
    Render and preview locally with the Hyperframes tooling while you design, or explore community compositions to remix.
  </Step>

  <Step title="Render to video">
    Render to MP4, MOV, WebM, GIF, or a PNG sequence — locally, or on HeyGen's hosted cloud via the [Cloud Rendering API](/hyperframes).
  </Step>
</Steps>

## Core concepts

| Concept | What it is |
| - | - |
| **Composition** | The fundamental building block — a video scene defined in HTML. |
| **Data attributes** | The `data-*` hooks that control timing and playback behavior for elements in a composition. |
| **Variables** | Values you parameterize a composition with (via `data-composition-variables`), overridden at render time to produce many videos from one bundle. |
| **Frame adapters** | Integration points for custom animation runtimes beyond the defaults. |
| **Deterministic rendering** | The guarantee that identical inputs produce byte-for-byte identical frames across machines. |

## Ways to render

<CardGroup>
  <Card title="Local & self-hosted" icon="laptop-code" href="https://hyperframes.heygen.com/packages/core">
    Render on your own machine or your own cloud (AWS Lambda, Google Cloud Run) with the Hyperframes developer tooling. Best while authoring and iterating.
  </Card>

  <Card title="HeyGen Cloud Rendering" icon="cloud" href="/hyperframes">
    Upload your project bundle and let HeyGen render it — no infrastructure to run. This is the path documented in these API docs.
  </Card>
</CardGroup>

## Where to go next

* Render a composition on HeyGen's infrastructure → [Hyperframes Cloud Rendering](/hyperframes)
* Combine a HeyGen avatar video with music, sound effects, and Hyperframes graphics into one finished video → [Hyperframes + HeyGen](/hyperframes-heygen)
* The composition framework, component APIs, and local tooling → [Hyperframes developer docs](https://hyperframes.heygen.com/packages/core)
* Explore and remix community-built compositions → [Community Playground](https://www.hyperframes.dev)


# Image to Video
Source: https://heygen-1fa696a7.mintlify.app/image-to-video

Animate a still image into video with the HeyGen Image to Video API — add motion, effects, and avatar-led narration.

<img alt="" />

<Tip>
  This page animates a person in your image with a script. To generate a whole scene from a prompt, with the image as its first frame, use [HeyGen Video](/docs/models/heygen-video) with `mode: "image_to_video"`.
</Tip>

## Prerequisites

<Check>
  An image of a person (PNG or JPEG) — accessible via a public URL or uploaded as an asset
</Check>

<Check>
  A `voice_id` for the voice you want. Use `GET /v3/voices` to browse options.
</Check>

## Step 1 — Generate the video

Use `POST /v3/videos` with `type: "image"` and an `image` object instead of `avatar_id`:

<Tabs>
  <Tab title="From image URL">
    ```bash theme={null}
    curl -X POST "https://api.heygen.com/v3/videos" \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "image",
        "image": {
          "type": "url",
          "url": "https://example.com/person.jpg"
        },
        "script": "Hello! This video was generated directly from a photo, with no avatar setup needed.",
        "voice_id": "YOUR_VOICE_ID",
        "title": "Image to Video Demo",
        "resolution": "1080p",
        "aspect_ratio": "auto"
      }'
    ```
  </Tab>

  <Tab title="From uploaded asset">
    First upload via `POST /v3/assets`, then reference the returned `asset_id`:

    ```bash theme={null}
    # Upload the image
    curl -X POST "https://api.heygen.com/v3/assets" \
      -H "x-api-key: YOUR_API_KEY" \
      -F "file=@person.jpg"

    # Generate the video
    curl -X POST "https://api.heygen.com/v3/videos" \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "image",
        "image": {
          "type": "asset_id",
          "asset_id": "RETURNED_ASSET_ID"
        },
        "script": "This video was created from an uploaded image asset.",
        "voice_id": "YOUR_VOICE_ID",
        "title": "Image to Video Demo"
      }'
    ```
  </Tab>
</Tabs>

<Note>
  `type: "image"` and `type: "avatar"` are mutually exclusive — use exactly one.
</Note>

## Step 2 — Poll for completion

Video generation is asynchronous. Poll `GET /v3/videos/{video_id}` until the status reaches `completed`:

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/videos/YOUR_VIDEO_ID" \
  -H "x-api-key: YOUR_API_KEY"
```

| Status | Meaning |
| - | - |
| `pending` | Queued for processing |
| `processing` | Video is being generated |
| `completed` | Ready — `video_url` is available |
| `failed` | Something went wrong |

## Full example

```python theme={null}
import requests
import time

API_KEY = "YOUR_API_KEY"
BASE = "https://api.heygen.com"
HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}

# 1. Generate video from an image URL
resp = requests.post(f"{BASE}/v3/videos", headers=HEADERS, json={
    "type": "image",
    "image": {
        "type": "url",
        "url": "https://example.com/person.jpg"
    },
    "script": "Welcome! This entire video was created from a single photograph.",
    "voice_id": "YOUR_VOICE_ID",
    "title": "Image-to-Video Example",
    "resolution": "1080p",
    "aspect_ratio": "auto"
})
video_id = resp.json()["data"]["video_id"]
print(f"Video created: {video_id}")

# 2. Poll until done
while True:
    status_resp = requests.get(f"{BASE}/v3/videos/{video_id}", headers=HEADERS)
    data = status_resp.json()["data"]
    print(f"Status: {data['status']}")
    if data["status"] == "completed":
        print(f"Download: {data['video_url']}")
        break
    elif data["status"] == "failed":
        print(f"Error: {data.get('failure_message')}")
        break
    time.sleep(10)
```

## Using audio instead of a script

You can lip-sync to a custom audio file instead of generating speech from text. Pass `audio_url` or `audio_asset_id` instead of `script` + `voice_id`:

```json theme={null}
{
  "type": "image",
  "image": {
    "type": "url",
    "url": "https://example.com/person.jpg"
  },
  "audio_url": "https://example.com/narration.mp3",
  "title": "Image-to-Video with custom audio"
}
```

<Warning>
  `script` and `audio_url`/`audio_asset_id` are mutually exclusive. If you provide a `script`, you must also provide a `voice_id`.
</Warning>

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `title` | string | Display name in the HeyGen dashboard |
| `resolution` | string | `1080p` (recommended) or `720p` |
| `aspect_ratio` | string | `auto` (recommended — matches the source image, falling back to `16:9`), `16:9`, `9:16`, `4:5`, `5:4`, or `1:1` |
| `remove_background` | boolean | Remove the image background from the video |
| `background` | object | Set a solid color or image background |
| `voice_settings` | object | Adjust `speed` (0.5–1.5), `pitch` (-50 to +50), `locale` |
| `callback_url` | string | Webhook URL for completion notification |
| `callback_id` | string | Your own ID echoed back in the webhook payload |

## Image-to-video vs. Photo Avatar

| Criteria | Image-to-Video | Photo Avatar |
| - | - | - |
| **Setup** | None — use `type: "image"` and go | Requires `POST /v3/avatars` first |
| **Reusability** | One-off per request | Reusable across many videos via `avatar_id` |
| **Motion prompt** | Not supported | Supported |
| **Expressiveness** | Not supported | `high` / `medium` / `low` |
| **Best for** | Quick tests, one-off content | Recurring brand content |

<Tip>
  If you plan to generate multiple videos with the same person, create a Photo Avatar once and reuse its `avatar_id`. This saves processing time and unlocks motion and expressiveness controls.
</Tip>


# Lipsync - Precision
Source: https://heygen-1fa696a7.mintlify.app/lipsync-precision

Run the HeyGen Lipsync API in precision mode for frame-accurate mouth movements on long-form video. Best for cinematic content where fidelity matters.

<img alt="" />

* Endpoint: [`POST /v3/lipsyncs`](/reference/create-lipsync)
* Purpose: Dub or replace audio on a video with high-accuracy lip-sync. The job runs asynchronously — poll via [Get Lipsync](/reference/get-lipsync) or use a `callback_url` ([Webhooks](/docs/webhooks)).
* For faster, lower-fidelity lipsync, see [Speed mode](/lipsync-speed). For many videos in one job, see [Lipsync batches](/batch-lipsyncs).

### Quick Example

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/lipsyncs" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video": { "type": "url", "url": "https://example.com/source.mp4" },
    "audio": { "type": "url", "url": "https://example.com/new-audio.mp3" },
    "mode": "precision"
  }'
```

### Request Body

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `video` | object | Yes | — | Source video. Provide as `{ "type": "url", "url": "https://..." }` or `{ "type": "asset_id", "asset_id": "..." }` (from [`POST /v3/assets`](/reference/upload-asset) — see [Upload Assets](/docs/upload-assets)). |
| `audio` | object | Yes | — | Replacement audio. Same format options as `video`. |
| `mode` | string | No | — | Set to `"precision"` for avatar-inference lip-sync. |
| `title` | string | No | — | Display title for the lipsync in the HeyGen dashboard. |
| `enable_caption` | boolean | No | `false` | Generate captions for the output video. |
| `enable_dynamic_duration` | boolean | No | `true` | Allow output duration to adjust to match the new audio length. |
| `disable_music_track` | boolean | No | `false` | Strip background music from the source video. |
| `enable_speech_enhancement` | boolean | No | `false` | Enhance speech quality in the output. |
| `enable_watermark` | boolean | No | `false` | Add a watermark to the output. |
| `start_time` | number | No | — | Start time in seconds for partial lipsync. |
| `end_time` | number | No | — | End time in seconds for partial lipsync. |
| `keep_the_same_format` | boolean | No | — | Preserve the source video's resolution and bitrate. |
| `fps_mode` | string | No | — | Frame rate mode: `"vfr"`, `"cfr"`, or `"passthrough"`. |
| `callback_url` | string | No | — | [Webhook](/docs/webhooks) URL — receives a POST when the job completes or fails. |
| `callback_id` | string | No | — | Arbitrary ID echoed back in the webhook payload. |
| `folder_id` | string | No | — | Organize the lipsync into a specific project folder. |

### Response

```json theme={null}
{
  "data": {
    "lipsync_id": "ls_abc123"
  }
}
```

| Field | Type | Description |
| - | - | - |
| `lipsync_id` | string | Unique identifier. Use with [`GET /v3/lipsyncs/{lipsync_id}`](/reference/get-lipsync) to poll status. |

## Get Lipsync Details

* Endpoint: [`GET /v3/lipsyncs/{lipsync_id}`](/reference/get-lipsync)
* Purpose: Get detailed information about a lipsync including status, download URL, and metadata.

### Quick Example

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/lipsyncs/ls_abc123" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

### Path Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `lipsync_id` | string | Yes | Unique lipsync identifier. |

### Response

```json theme={null}
{
  "data": {
    "id": "ls_abc123",
    "title": "My Lipsync",
    "status": "completed",
    "duration": 42.5,
    "video_url": "https://files.heygen.ai/...",
    "callback_id": null,
    "created_at": 1717000000,
    "failure_message": null
  }
}
```

### Response Fields

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique lipsync identifier. |
| `title` | string or null | Display title. |
| `status` | string | Current status: `"pending"`, `"running"`, `"completed"`, or `"failed"`. |
| `duration` | number or null | Video duration in seconds. Present when completed. |
| `video_url` | string or null | Presigned download URL for the output video. Only present when status is `"completed"`. |
| `callback_id` | string or null | Client-provided callback ID. |
| `created_at` | integer or null | Unix timestamp of creation. |
| `failure_message` | string or null | Error description. Only present when status is `"failed"`. |

## List Lipsyncs

* Endpoint: [`GET /v3/lipsyncs`](/reference/list-lipsyncs)
* Purpose: List lipsyncs with cursor-based pagination.

### Quick Example

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/lipsyncs?limit=10" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

### Query Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `limit` | integer | No | `10` | Results per page (1–100). |
| `token` | string | No | — | Opaque cursor token for the next page. |

### Response

```json theme={null}
{
  "data": [
    {
      "id": "ls_abc123",
      "title": "My Lipsync",
      "status": "completed",
      "duration": 42.5,
      "video_url": "https://files.heygen.ai/...",
      "created_at": 1717000000
    }
  ],
  "has_more": false,
  "next_token": null
}
```

## Update Lipsync

* Endpoint: [`PATCH /v3/lipsyncs/{lipsync_id}`](/reference/update-lipsync)
* Purpose: Update a lipsync's title.

### Quick Example

```bash theme={null}
curl -X PATCH "https://api.heygen.com/v3/lipsyncs/ls_abc123" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated Title" }'
```

### Request Body

| Parameter | Type | Required | Description |
| - | - | - | - |
| `title` | string | Yes | New title for the lipsync. |

## Delete Lipsync

* Endpoint: [`DELETE /v3/lipsyncs/{lipsync_id}`](/reference/delete-lipsync)
* Purpose: Permanently delete a lipsync.

### Quick Example

```bash theme={null}
curl -X DELETE "https://api.heygen.com/v3/lipsyncs/ls_abc123" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

### Response

```json theme={null}
{
  "data": {
    "id": "ls_abc123"
  }
}
```

## CLI Usage

```bash theme={null}
# Create with precision mode
heygen lipsync create -d '{
  "video": {"type": "url", "url": "https://example.com/source.mp4"},
  "audio": {"type": "url", "url": "https://example.com/new-audio.mp3"},
  "mode": "precision"
}' --wait

# Poll status manually
heygen lipsync get <lipsync-id>

# List lipsyncs
heygen lipsync list --limit 10

# Update title
heygen lipsync update <lipsync-id> --title "Updated Title"

# Delete
heygen lipsync delete <lipsync-id> --force
```

Use `--request-schema` to see all available request fields without needing auth:

```bash theme={null}
heygen lipsync create --request-schema
```

## Polling Pattern

Lipsyncs are processed asynchronously. Poll until status reaches `"completed"` or `"failed"`.

Status transitions: `pending` → `running` → `completed` | `failed`

```bash theme={null}
while true; do
  STATUS=$(curl -s "https://api.heygen.com/v3/lipsyncs/ls_abc123" \
    -H "X-Api-Key: $HEYGEN_API_KEY" | jq -r '.data.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] && break
  sleep 10
done
```

Or let the CLI handle polling for you:

```bash theme={null}
heygen lipsync create -d '...' --wait --timeout 30m
```

## Asset Inputs

Both `video` and `audio` fields accept two input formats:

**By URL** — any publicly accessible HTTPS link:

```json theme={null}
{ "type": "url", "url": "https://example.com/file.mp4" }
```

**By asset ID** — reference a file previously uploaded via [`POST /v3/assets`](/reference/upload-asset) (see [Upload Assets](/docs/upload-assets)):

```json theme={null}
{ "type": "asset_id", "asset_id": "asset_xyz789" }
```


# Lipsync - Speed
Source: https://heygen-1fa696a7.mintlify.app/lipsync-speed

Run the HeyGen Lipsync API in speed mode for rapid lipsync drafts. Ideal for previewing edits, batch processing, and iterating on content before final render.

<img alt="" />

* Endpoint: [`POST /v3/lipsyncs`](/reference/create-lipsync)
* Purpose: Dub or replace audio on a video. The job runs asynchronously — poll via [Get Lipsync](/reference/get-lipsync) or use a `callback_url` ([Webhooks](/docs/webhooks)).
* For higher fidelity, see [Precision mode](/lipsync-precision). For many videos in one job, see [Lipsync batches](/batch-lipsyncs).

### How Lip Sync and Video Translation Relate

Both APIs sit on top of **one lip sync engine** that runs in two modes — **Speed** and **Precision** — trading latency for fidelity. What differs is what each API does *around* that engine:

* **[Lip Sync API](/lipsync-speed)** — the engine on its own. You bring the video *and* your own audio; the engine redraws the mouth to match. No translation, no audio generation — dialogue replacement only.
* **[Video Translation API](/docs/video-translate)** — translation, optionally followed by the engine. It has two output modes:
  * **Audio only** (`translate_audio_only: true`) — transcribe, translate, and generate the translated audio, then stop. No lip sync. The output is just the new audio track (or the original video with swapped audio and an untouched mouth).
  * **Video (audio + visual)** — the same translation pipeline, then runs the lip sync engine so the mouth matches the translated speech.

The short version:

* **Lip Sync API** = engine only — you bring the audio.
* **Video Translation API** = translation, optionally followed by the engine. Audio-only mode skips the engine entirely; video mode adds it back.

### Quick Example

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/lipsyncs" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video": { "type": "url", "url": "https://example.com/source.mp4" },
    "audio": { "type": "url", "url": "https://example.com/new-audio.mp3" },
    "mode": "speed"
  }'
```

### Request Body

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `video` | object | Yes | — | Source video. Provide as `{ "type": "url", "url": "https://..." }` or `{ "type": "asset_id", "asset_id": "..." }` (from [`POST /v3/assets`](/reference/upload-asset) — see [Upload Assets](/docs/upload-assets)). |
| `audio` | object | Yes | — | Replacement audio. Same format options as `video`. |
| `mode` | string | No | — | Set to `"speed"` for fast audio-only resync. |
| `title` | string | No | — | Display title for the lipsync in the HeyGen dashboard. |
| `enable_caption` | boolean | No | `false` | Generate captions for the output video. |
| `enable_dynamic_duration` | boolean | No | `true` | Allow output duration to adjust to match the new audio length. |
| `disable_music_track` | boolean | No | `false` | Strip background music from the source video. |
| `enable_speech_enhancement` | boolean | No | `false` | Enhance speech quality in the output. |
| `enable_watermark` | boolean | No | `false` | Add a watermark to the output. |
| `start_time` | number | No | — | Start time in seconds for partial lipsync. |
| `end_time` | number | No | — | End time in seconds for partial lipsync. |
| `keep_the_same_format` | boolean | No | — | Preserve the source video's resolution and bitrate. |
| `fps_mode` | string | No | — | Frame rate mode: `"vfr"`, `"cfr"`, or `"passthrough"`. |
| `callback_url` | string | No | — | [Webhook](/docs/webhooks) URL — receives a POST when the job completes or fails. |
| `callback_id` | string | No | — | Arbitrary ID echoed back in the webhook payload. |
| `folder_id` | string | No | — | Organize the lipsync into a specific project folder. |

### Response

```json theme={null}
{
  "data": {
    "lipsync_id": "ls_abc123"
  }
}
```

| Field | Type | Description |
| - | - | - |
| `lipsync_id` | string | Unique identifier. Use with [`GET /v3/lipsyncs/{lipsync_id}`](/reference/get-lipsync) to poll status. |

## Get Lipsync Details

* Endpoint: [`GET /v3/lipsyncs/{lipsync_id}`](/reference/get-lipsync)
* Purpose: Get detailed information about a lipsync including status, download URL, and metadata.

### Quick Example

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/lipsyncs/ls_abc123" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

### Path Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `lipsync_id` | string | Yes | Unique lipsync identifier. |

### Response

```json theme={null}
{
  "data": {
    "id": "ls_abc123",
    "title": "My Lipsync",
    "status": "completed",
    "duration": 42.5,
    "video_url": "https://files.heygen.ai/...",
    "callback_id": null,
    "created_at": 1717000000,
    "failure_message": null
  }
}
```

### Response Fields

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique lipsync identifier. |
| `title` | string or null | Display title. |
| `status` | string | Current status: `"pending"`, `"running"`, `"completed"`, or `"failed"`. |
| `duration` | number or null | Video duration in seconds. Present when completed. |
| `video_url` | string or null | Presigned download URL for the output video. Only present when status is `"completed"`. |
| `callback_id` | string or null | Client-provided callback ID. |
| `created_at` | integer or null | Unix timestamp of creation. |
| `failure_message` | string or null | Error description. Only present when status is `"failed"`. |

## List Lipsyncs

* Endpoint: [`GET /v3/lipsyncs`](/reference/list-lipsyncs)
* Purpose: List lipsyncs with cursor-based pagination.

### Quick Example

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/lipsyncs?limit=10" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

### Query Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `limit` | integer | No | `10` | Results per page (1–100). |
| `token` | string | No | — | Opaque cursor token for the next page. |

### Response

```json theme={null}
{
  "data": [
    {
      "id": "ls_abc123",
      "title": "My Lipsync",
      "status": "completed",
      "duration": 42.5,
      "video_url": "https://files.heygen.ai/...",
      "created_at": 1717000000
    }
  ],
  "has_more": false,
  "next_token": null
}
```

## Update Lipsync

* Endpoint: [`PATCH /v3/lipsyncs/{lipsync_id}`](/reference/update-lipsync)
* Purpose: Update a lipsync's title.

### Quick Example

```bash theme={null}
curl -X PATCH "https://api.heygen.com/v3/lipsyncs/ls_abc123" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated Title" }'
```

### Request Body

| Parameter | Type | Required | Description |
| - | - | - | - |
| `title` | string | Yes | New title for the lipsync. |

## Delete Lipsync

* Endpoint: [`DELETE /v3/lipsyncs/{lipsync_id}`](/reference/delete-lipsync)
* Purpose: Permanently delete a lipsync.

### Quick Example

```bash theme={null}
curl -X DELETE "https://api.heygen.com/v3/lipsyncs/ls_abc123" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

### Response

```json theme={null}
{
  "data": {
    "id": "ls_abc123"
  }
}
```

## CLI Usage

```bash theme={null}
# Create with speed mode
heygen lipsync create -d '{
  "video": {"type": "url", "url": "https://example.com/source.mp4"},
  "audio": {"type": "url", "url": "https://example.com/new-audio.mp3"},
  "mode": "speed"
}' --wait

# Poll status manually
heygen lipsync get <lipsync-id>

# List lipsyncs
heygen lipsync list --limit 10

# Update title
heygen lipsync update <lipsync-id> --title "Updated Title"

# Delete
heygen lipsync delete <lipsync-id> --force
```

Use `--request-schema` to see all available request fields without needing auth:

```bash theme={null}
heygen lipsync create --request-schema
```

## Polling Pattern

Lipsyncs are processed asynchronously. Poll until status reaches `"completed"` or `"failed"`.

Status transitions: `pending` → `running` → `completed` | `failed`

```bash theme={null}
while true; do
  STATUS=$(curl -s "https://api.heygen.com/v3/lipsyncs/ls_abc123" \
    -H "X-Api-Key: $HEYGEN_API_KEY" | jq -r '.data.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] && break
  sleep 10
done
```

Or let the CLI handle polling for you:

```bash theme={null}
heygen lipsync create -d '...' --wait --timeout 30m
```

## Asset Inputs

Both `video` and `audio` fields accept two input formats:

**By URL** — any publicly accessible HTTPS link:

```json theme={null}
{ "type": "url", "url": "https://example.com/file.mp4" }
```

**By asset ID** — reference a file previously uploaded via [`POST /v3/assets`](/reference/upload-asset) (see [Upload Assets](/docs/upload-assets)):

```json theme={null}
{ "type": "asset_id", "asset_id": "asset_xyz789" }
```


# Live Avatar
Source: https://heygen-1fa696a7.mintlify.app/live-avatar

Build real-time, conversational avatars with the LiveAvatar API. Full documentation lives at docs.liveavatar.com.

<img alt="" />

**LiveAvatar** powers real-time, **conversational** avatars: listening, understanding, and responding with a live avatar. It ships in two modes so you can choose how much of that loop HeyGen handles:

* **FULL mode** — HeyGen manages the end-to-end conversation (STT, LLM, TTS, turn-taking, memory, and contexts). Bring a prompt and a voice agent and you have a talking, listening avatar.
* **LITE mode** — you keep your own agent/LLM and use LiveAvatar for the avatar layer, wiring in integrations like the ElevenLabs Agent plugin.

LiveAvatar has its own API, guides, and concepts, documented on a dedicated site. Each link below opens the relevant page on **docs.liveavatar.com**.

## Start here

<CardGroup>
  <Card title="LiveAvatar Overview" icon="book-open" href="https://docs.liveavatar.com/">
    What LiveAvatar is, how it works, and how to get set up.
  </Card>

  <Card title="Building with Agents" icon="robot" href="https://docs.liveavatar.com/docs/agent-skills">
    Agent skills that assess your stack and build the integration end to end.
  </Card>

  <Card title="Sandbox Mode" icon="flask" href="https://docs.liveavatar.com/docs/sandbox-mode">
    Try LiveAvatar without wiring up production credentials.
  </Card>

  <Card title="API Reference" icon="code" href="https://docs.liveavatar.com/">
    25+ endpoints for sessions, avatars, voices, contexts, LLM configs, and secrets.
  </Card>
</CardGroup>

## Choose a mode

<CardGroup>
  <Card title="FULL Mode" icon="microphone-lines" href="https://docs.liveavatar.com/docs/full-mode/overview">
    HeyGen runs the full loop — lifecycle, voice settings, push-to-talk, custom LLM/TTS, and events.
  </Card>

  <Card title="LITE Mode" icon="plug" href="https://docs.liveavatar.com/docs/lite-mode/overview">
    Bring your own agent — configuration, events, integrations, and the ElevenLabs Agent plugin.
  </Card>
</CardGroup>

## Core concepts

<CardGroup>
  <Card title="Avatars" icon="user" href="https://docs.liveavatar.com/docs/core-concepts/avatars">
    Pick and configure the avatar that fronts your conversation.
  </Card>

  <Card title="Voice Agents" icon="headset" href="https://docs.liveavatar.com/docs/core-concepts/voice-agents">
    Define the agent that listens and responds in real time.
  </Card>

  <Card title="Voices" icon="waveform-lines" href="https://docs.liveavatar.com/docs/core-concepts/voices">
    Choose and tune the voice your avatar speaks with.
  </Card>

  <Card title="Contexts" icon="layer-group" href="https://docs.liveavatar.com/docs/core-concepts/contexts">
    Ground the conversation in the knowledge it needs.
  </Card>

  <Card title="Memory" icon="brain" href="https://docs.liveavatar.com/docs/core-concepts/memory">
    Persist state across turns and sessions.
  </Card>

  <Card title="Secrets & Integrations" icon="key" href="https://docs.liveavatar.com/docs/core-concepts/secrets">
    Connect external services and manage credentials.
  </Card>
</CardGroup>

<Card title="Open the full LiveAvatar Documentation" icon="comments" href="https://docs.liveavatar.com/">
  API reference, guides, changelog, and OpenAPI specs → docs.liveavatar.com
</Card>


# Claude Code
Source: https://heygen-1fa696a7.mintlify.app/mcp/claude-code

Connect HeyGen to Claude Code and make AI avatar videos from your terminal.

Make HeyGen videos from Claude Code with a plain-language prompt.

<Steps>
  <Step title="Add the server">
    Run this in your terminal:

    ```bash theme={null}
    claude mcp add --transport http -s user heygen https://mcp.heygen.com/mcp/v1/
    ```

    `-s user` adds HeyGen to every project. Leave it out to add HeyGen to the current project only.
  </Step>

  <Step title="Connect your HeyGen account">
    Inside Claude Code, run `/mcp`, choose `heygen`, and approve access in the browser. HeyGen shows as `connected` when you're set.
  </Step>

  <Step title="Ask for a video">
    ```text theme={null}
    Make a 60-second HeyGen explainer about our new API endpoints.
    ```

    Claude Code writes the script, picks the avatar, and renders the video. Finished videos also appear in **Projects** in HeyGen.
  </Step>
</Steps>

<Tip>
  For sharper scripts and scene structure, add [HeyGen Skills](/skills/install) to Claude Code.
</Tip>


# Claude Web
Source: https://heygen-1fa696a7.mintlify.app/mcp/claude-web

Connect HeyGen to Claude and make AI avatar videos from a chat.

Make HeyGen videos from a Claude chat. Requires a paid Claude plan; a HeyGen Creator plan or above is recommended.

<Steps>
  <Step title="Add the connector">
    <div>
      <div>
        In Claude, go to **+** → **Connectors** → **Manage connectors** → **+ Add custom connector**. Name it `HeyGen` and paste this URL:

        ```text wrap theme={null}
        https://mcp.heygen.com/mcp/v1/
        ```
      </div>

      <div>
        <Frame>
          <img alt="Connectors and Manage connectors in the Claude + menu" />
        </Frame>

        <Frame>
          <img alt="Add custom connector in the Connectors panel" />
        </Frame>

        <Frame>
          <img alt="Add custom connector dialog with Name and Remote MCP server URL fields" />
        </Frame>
      </div>
    </div>
  </Step>

  <Step title="Connect your HeyGen account">
    <div>
      <div>
        Click **Connect** and approve access on HeyGen.
      </div>

      <div>
        <Frame>
          <img alt="Connect button on the HeyGen connector" />
        </Frame>

        <Frame>
          <img alt="HeyGen authorization page" />
        </Frame>
      </div>
    </div>
  </Step>

  <Step title="Ask for a video">
    <div>
      <div>
        ```text wrap theme={null}
        Generate a video using HeyGen MCP about the difference between Skills and MCP.
        ```

        Claude picks the avatar, writes the script, and renders the video. Finished videos also appear in **Projects** in HeyGen.
      </div>

      <div>
        <Frame>
          <img alt="HeyGen video prompt in Claude" />
        </Frame>

        <Frame>
          <img alt="HeyGen video rendering in Claude" />
        </Frame>
      </div>
    </div>
  </Step>
</Steps>

<Tip>
  Set the HeyGen connector to **Always Allow** to skip permission prompts.
</Tip>


# Codex CLI
Source: https://heygen-1fa696a7.mintlify.app/mcp/codex-cli

Connect HeyGen to Codex CLI and make AI avatar videos from your terminal.

Make HeyGen videos from Codex CLI with a plain-language prompt. Using ChatGPT instead? See [OpenAI](/mcp/open-ai).

<Steps>
  <Step title="Add the server">
    Run this in your terminal:

    ```bash theme={null}
    codex mcp add heygen --url https://mcp.heygen.com/mcp/v1
    ```

    Keep `--url` and leave off the trailing slash: Codex needs both to find HeyGen's sign-in.
  </Step>

  <Step title="Connect your HeyGen account">
    Codex opens HeyGen in your browser. Approve access and you're set. To sign in again later, run `codex mcp login heygen`.
  </Step>

  <Step title="Ask for a video">
    ```text theme={null}
    Make a 60-second HeyGen explainer about our new API endpoints.
    ```

    Codex writes the script, picks the avatar, and renders the video. Finished videos also appear in **Projects** in HeyGen.
  </Step>
</Steps>

<Tip>
  For sharper scripts and scene structure, add [HeyGen Skills](/skills/install) to Codex.
</Tip>

<Accordion title="Troubleshooting">
  * **`No authorization support detected`**: the URL has a trailing slash. Run `codex mcp remove heygen`, then add it again with the command above.
  * **`OAuth login is only supported for streamable HTTP servers`**: the server was added without `--url`. Remove it and add it again with the command above.
  * **Tools missing after sign-in**: restart Codex CLI.
</Accordion>


# Cursor
Source: https://heygen-1fa696a7.mintlify.app/mcp/cursor

Add HeyGen to Cursor in one click and make AI avatar videos from your editor.

Make HeyGen videos from Cursor's chat with a plain-language prompt.

<Steps>
  <Step title="Add HeyGen from the marketplace">
    Open [cursor.com/marketplace/heygen](https://cursor.com/marketplace/heygen), click **Add**, and confirm in Cursor.
  </Step>

  <Step title="Connect your HeyGen account">
    The first time Cursor uses HeyGen, approve access in your browser.
  </Step>

  <Step title="Ask for a video">
    ```text theme={null}
    Make a 60-second HeyGen explainer about our new API release.
    ```

    Cursor writes the script, picks the avatar, and renders the video. Finished videos also appear in **Projects** in HeyGen.
  </Step>
</Steps>

<Accordion title="Add HeyGen manually instead">
  Add this to `~/.cursor/mcp.json`, next to any servers you already have:

  ```json theme={null}
  {
    "mcpServers": {
      "heygen": {
        "url": "https://mcp.heygen.com/mcp/v1/"
      }
    }
  }
  ```
</Accordion>


# Gemini CLI
Source: https://heygen-1fa696a7.mintlify.app/mcp/gemini-cli

Connect HeyGen to Gemini CLI and make AI avatar videos from your terminal.

Make HeyGen videos from Gemini CLI with a plain-language prompt. Install the CLI first with `npm install -g @google/gemini-cli@latest`.

<Steps>
  <Step title="Add the server">
    Add HeyGen to `~/.gemini/settings.json`, next to any servers you already have. Use `.gemini/settings.json` in a project folder to add it to that project only.

    ```json theme={null}
    {
      "mcpServers": {
        "heygen": {
          "httpUrl": "https://mcp.heygen.com/mcp/v1/"
        }
      }
    }
    ```

    Restart Gemini CLI.
  </Step>

  <Step title="Connect your HeyGen account">
    The first time Gemini uses HeyGen, approve access in your browser. Run `/mcp` to see `heygen` connected.
  </Step>

  <Step title="Ask for a video">
    ```text theme={null}
    Make a 60-second HeyGen explainer about our new API release.
    ```

    Gemini writes the script, picks the avatar, and renders the video. Finished videos also appear in **Projects** in HeyGen.
  </Step>
</Steps>

<Tip>
  For sharper scripts and scene structure, add [HeyGen Skills](/skills/install) to Gemini CLI.
</Tip>


# Grok
Source: https://heygen-1fa696a7.mintlify.app/mcp/grok

Connect HeyGen and HyperFrames to Grok and make videos from the chat.

Add **HeyGen** for avatar videos and **HyperFrames by HeyGen** for motion graphics. Custom connectors need a paid Grok plan.

## HeyGen

<Steps>
  <Step title="Add the connector">
    In the prompt bar, click **+** → **Add connector** → **Custom**. Name it `HeyGen`, paste this URL, and click **Add Connector**:

    ```text theme={null}
    https://mcp.heygen.com/mcp/v1/
    ```
  </Step>

  <Step title="Connect your HeyGen account">
    Click **Connect** and approve access on HeyGen.
  </Step>

  <Step title="Ask for a video">
    ```text theme={null}
    Make a 30-second product explainer with HeyGen.
    ```

    Finished videos also appear in **Projects** in HeyGen.
  </Step>
</Steps>

## HyperFrames

<Steps>
  <Step title="Find HyperFrames">
    Click **+** → **Add connector**, search `hyp`, and select **HyperFrames by HeyGen**.
  </Step>

  <Step title="Connect your HeyGen account">
    Click **Connect** and approve access on HeyGen.
  </Step>

  <Step title="Ask for a video">
    ```text theme={null}
    Use HyperFrames to render a motion graphic of our Q2 revenue.
    ```

    See [HyperFrames](/hyperframes) for what it can make.
  </Step>
</Steps>


# Lovable
Source: https://heygen-1fa696a7.mintlify.app/mcp/lovable

Connect HeyGen to Lovable and make AI avatar videos while you build.

Make HeyGen videos from Lovable's chat while you build.

<Steps>
  <Step title="Add the connector">
    Go to **Connectors** → **Chat connectors** → **Add custom MCP server**. Name it `HeyGen` and paste this URL:

    ```text theme={null}
    https://mcp.heygen.com/mcp/v1/
    ```
  </Step>

  <Step title="Connect your HeyGen account">
    Save, connect, and approve access on HeyGen.
  </Step>

  <Step title="Ask for a video">
    ```text theme={null}
    Make a short HeyGen walkthrough video for this app.
    ```

    Lovable writes the script, picks the avatar, and renders the video. Finished videos also appear in **Projects** in HeyGen.
  </Step>
</Steps>

<Note>
  The connector is personal to you and stays in Lovable's chat; your deployed app ships without it.
</Note>


# Manus
Source: https://heygen-1fa696a7.mintlify.app/mcp/manus

Connect HeyGen to Manus and let agents make AI avatar videos, on a schedule or on demand.

Let Manus agents make HeyGen videos, once or on a schedule.

<Steps>
  <Step title="Connect HeyGen">
    <div>
      <div>
        In [Manus](https://manus.im/app), click **Connect your tools to Manus**, search `HeyGen`, click **Connect**, and approve access.
      </div>

      <div>
        <Frame>
          <img alt="Connect your tools to Manus link" />
        </Frame>

        <Frame>
          <img alt="HeyGen in the Manus connectors search" />
        </Frame>

        <Frame>
          <img alt="HeyGen connector Connect button" />
        </Frame>

        <Frame>
          <img alt="HeyGen authorization page" />
        </Frame>
      </div>
    </div>
  </Step>

  <Step title="Turn on HeyGen for your agent">
    <div>
      <div>
        In a chat, open the tools menu and switch **HeyGen** on.
      </div>

      <div>
        <Frame>
          <img alt="HeyGen toggled on in the Manus tools menu" />
        </Frame>
      </div>
    </div>
  </Step>

  <Step title="Ask for videos">
    <div>
      <div>
        ```text wrap theme={null}
        Every morning at 7 AM Pacific, make three 60-second videos on the top
        tech stories and send them to me. Use HeyGen Video Agent, and read the
        HeyGen skills at https://github.com/heygen-com/skills first.
        ```
      </div>

      <div>
        <Frame>
          <img alt="Manus reading HeyGen Skills before scheduling" />
        </Frame>
      </div>
    </div>
  </Step>
</Steps>

<Tip>
  For sharper scripts and scene structure, add [HeyGen Skills](/skills/install) to your Manus agent instructions.
</Tip>


# OpenAI
Source: https://heygen-1fa696a7.mintlify.app/mcp/open-ai

Install the HeyGen plugin in ChatGPT and make AI avatar videos from the chat.

Make HeyGen videos from a ChatGPT chat.

<div>
  <a href="https://chatgpt.com/plugins/plugin_asdk_app_69418aad55e08191aa5e437b649ca2e4">
    Install the HeyGen plugin on ChatGPT
    <span>→</span>
  </a>

  <span>
    Opens the HeyGen listing in the ChatGPT plugin directory.
  </span>
</div>

<Steps>
  <Step title="Find HeyGen in ChatGPT">
    <div>
      <div>
        In [ChatGPT](https://chatgpt.com), open the [**Apps**](https://chatgpt.com/plugins) directory and search **HeyGen**.
      </div>

      <div>
        <Frame>
          <img alt="ChatGPT home" />
        </Frame>

        <Frame>
          <img alt="ChatGPT Apps directory" />
        </Frame>

        <Frame>
          <img alt="HeyGen in the ChatGPT Apps directory" />
        </Frame>
      </div>
    </div>
  </Step>

  <Step title="Connect your HeyGen account">
    <div>
      <div>
        Click **Connect HeyGen** and approve access. New to HeyGen? You can create an account during this step.
      </div>

      <div>
        <Frame>
          <img alt="Connect HeyGen button" />
        </Frame>

        <Frame>
          <img alt="HeyGen authorization page" />
        </Frame>
      </div>
    </div>
  </Step>

  <Step title="Ask for a video">
    <div>
      <div>
        ```text wrap theme={null}
        Use HeyGen to make a 60-second product explainer with a professional
        female avatar, a short intro, and a call to action.
        ```

        The video appears right in the chat.
      </div>

      <div>
        <Frame>
          <img alt="HeyGen video prompt in ChatGPT" />
        </Frame>
      </div>
    </div>
  </Step>
</Steps>


# Overview
Source: https://heygen-1fa696a7.mintlify.app/mcp/overview

Connect any MCP-compatible AI agent to HeyGen video generation in a few clicks. No API key, no local server — add the connector, authenticate with OAuth, and start creating.

Add HeyGen as a connector in your AI agent and start generating videos in a few clicks — no API key and nothing to install. Usage draws on your existing HeyGen plan's credits.

## Add HeyGen to Your Agent

<Steps>
  <Step title="Open your agent's connector settings">
    In your MCP-compatible agent (Claude, Cursor, Gemini CLI, Manus, and others), open the **Connectors** or **MCP servers** settings and choose **Add custom connector**.
  </Step>

  <Step title="Paste the HeyGen MCP endpoint">
    Name the connector `HeyGen` and enter the remote MCP server URL:

    ```text theme={null}
    https://mcp.heygen.com/mcp/v1/
    ```
  </Step>

  <Step title="Authenticate with OAuth">
    Click **Connect** and sign in to HeyGen to approve access. This one-time OAuth flow links the connector to your account — no API key required.
  </Step>

  <Step title="Start creating">
    Ask your agent to generate a video — for example, *"Make a 30-second product explainer with HeyGen."* It calls HeyGen's tools directly and bills against your existing plan.
  </Step>
</Steps>

<Tip>
  Menu names vary slightly by agent. For click-by-click instructions, see the per-product setup guides below.
</Tip>

## What You Can Do

Once connected, your AI agent has access to the following tools:

### Video Agent

| Tool Name | Description |
| - | - |
| `list_video_agent_sessions` | Returns a paginated list of video agent sessions for the authenticated user, sorted newest-first. |
| `create_video_agent` | One-shot video generation from a prompt — agent handles scripting, avatar selection, scene composition, and rendering. Supports generate (fire-and-forget) and chat (multi-turn) modes. |
| `list_video_agent_styles` | Returns curated visual style templates available for Video Agent sessions. Each style controls scene composition, pacing, and aesthetics. Supports tag filtering (e.g. 'cinematic', 'retro-tech'). |
| `get_video_agent_session` | Returns the current status, progress, video\_id, and recent chat messages for a session. |
| `send_video_agent_message` | Sends a follow-up turn to a session created in either `generate` or `chat` mode; follow-up turns preserve the session mode. Send a `message`, a scene `edit_plan` built from `GET /v3/videos/{video_id}/scenes`, or both. Items may reference different scene snapshots from this session; none identifies the output draft. `edit_version` is not a document lock, so two edits from one version may both be accepted. Returns the current working draft in `video_id`. Poll `GET /v3/videos/{video_id}` for status. For a failed video, inspect `failure_code` and `failure_message`; the session endpoint also exposes known stop reasons in `error`. |
| `get_video_agent_resource` | Returns a single session resource (image, video, draft, avatar, voice, etc.) by its resource\_id. |
| `stop_video_agent_session` | Halts an active agent run at its next checkpoint. Partial results are preserved. |
| `list_video_agent_session_videos` | Returns all videos produced within a Video Agent session, sorted newest-first. |

### Videos

| Tool Name | Description |
| - | - |
| `list_videos` | Returns a paginated list of all videos in the account. Filterable by folder\_id or title substring. |
| `create_video` | Creates an avatar video: a HeyGen avatar or an image speaks your script or audio with lip-sync. Choose Avatar III, IV or V with `engine` (Avatar IV by default). To generate a whole scene from a prompt instead, use `POST /v3/models/videos`. |
| `get_video` | Returns details for a video including status, video\_url, thumbnail\_url, duration, and failure info if applicable. |
| `delete_video` | Permanently deletes a video and its associated files. This action cannot be undone. |
| `get_video_scenes` | Returns a video's scenes as it stands now, with the `edit_version` to send when editing. Each scene has a `background`, placed `elements` and a `script`. Skip element types you do not recognize. Geometry, text content, animations and background music are not described. A video whose editor document is still being prepared returns `409 resource_not_ready`; retry after it advances. |

### Templates

| Tool Name | Description |
| - | - |
| `list_templates` | Returns a paginated list of API-ready templates in the workspace. Templates are created and edited in the HeyGen web editor; only templates with variables defined are listed. |
| `create_template` | Creates a private template from one of your videos, copying its scenes, avatars, script and media. URL-to-Video and older editor videos return `template_source_unsupported`. The template starts with no variables; declare them with `PUT /v3/templates/{template_id}/variables`. |
| `get_template` | Returns template details including its variable schema (with current default values) and scenes. Variable defaults are returned in the same shape the generate request accepts, so a response can be edited and posted back. Only draft version 4 templates (the current editor format) are supported. |
| `generate_from_template` | Generates a video from a template by filling its variables. Use `scene_ids` to select, reorder or repeat the template's existing scenes. Poll `GET /v3/videos/{video_id}` or use webhooks for completion. An idempotent replay returns the original response, not the video's current state. |
| `update_template` | Renames a template. Other properties are edited in the HeyGen editor or through `PUT /v3/templates/{template_id}/variables`. Returns the template detail. |
| `delete_template` | Soft-deletes a template. It disappears from the list and can no longer be used to generate videos; videos already generated from it are unaffected. Templates managed by another HeyGen product cannot be deleted here. |
| `set_template_variables` | Replaces a template's full set of variables: any variable you omit is removed. Media, character and voice variables bind to a node by `element_id`, listed under `composition` in `GET /v3/templates/{template_id}`. A text variable with `match` turns that text into a `{{name}}` placeholder. |

### Voices

| Tool Name | Description |
| - | - |
| `list_voices` | Returns a paginated list of voices, filterable by type, engine, language, and gender. Speech generation supports Starfish, HeyGen Voice, and ElevenLabs. Each voice includes its speech default and available speech engines. |
| `design_voice` | Returns up to 3 voices matching a natural language description (e.g. 'warm, confident female narrator'). Use the seed parameter to get different batches of results. |
| `clone_voice` | Creates a voice clone from an audio file. Returns a voice\_clone\_id that can be polled via `GET /v3/voices/{voice_clone_id}` until the status is 'complete'. The resulting voice can be used with `POST /v3/voices/speech` and `POST /v3/videos`. |
| `create_speech` | Synthesizes speech from text with a catalog voice and returns an audio URL, its duration and optional word timestamps. Omit engine to use the voice's saved default and settings, or set it per request; choose an ElevenLabs model with settings: \{model\_id: 'eleven\_v4'}. Requests that omit engine use HeyGen Voice for most public catalog voices. Set engine: 'heygen\_voice' to explicitly request HeyGen Voice, or 'starfish' for Starfish. The legacy 'orca' input remains accepted; response engine values retain 'orca' for compatibility. A professional HeyGen Voice clone is synthesized by `POST /v3/models/audio/tts` instead. HTTP 400: the saved default or explicit engine is unsupported, not allowed on your plan, or incompatible with the requested locale or language. HTTP 403 (ai\_vendor\_access\_restricted): workspace vendor policy blocks ElevenLabs and all of its model variants. |
| `get_voice` | Returns details for a specific voice, including clone workflow status when available. Use this to poll a voice clone until its status is 'complete'. |
| `delete_voice` | Deletes a voice clone you own and frees its place in your clone limit. A voice used by a template cannot be deleted. An unknown or already-deleted voice returns 404 `voice_not_found`; treat that as success in delete-then-list flows. |

### Audio

| Tool Name | Description |
| - | - |
| `search_audio_sounds` | Searches the music or sound-effects catalog by natural-language description (`type=music` by default, or `sound_effects`). Returns tracks ranked by similarity, each with a download URL, paginated by cursor. |

### Video Translate

| Tool Name | Description |
| - | - |
| `list_video_translations` | Returns a paginated list of all video translation jobs in the account. |
| `create_video_translation` | Translates a video into one or more target languages with voice cloning and lip-sync. Returns one video\_translation\_id per language. Use mode: 'speed' (default) for fast turnaround or 'precision' for higher lip-sync quality. |
| `list_video_translation_languages` | Returns all supported target language names for video translation. |
| `get_video_translation` | Returns details for a translation job including status, output language, video\_url, and failure info if applicable. |
| `update_video_translation` | Updates the display title of a video translation job. |
| `delete_video_translation` | Permanently deletes a video translation and its associated files. This action cannot be undone. |

### AI Clipping

| Tool Name | Description |
| - | - |
| `list_ai_clipping` | Returns a cursor-paginated list of AI clip jobs in the authenticated user's workspace, newest first. |
| `create_ai_clipping` | Submit a source video and return a job id immediately. The job runs asynchronously and produces one or more short clips per the requested output\_settings. Poll `GET /v3/ai-clipping/{id}` or subscribe to ai\_clipping.success / ai\_clipping.fail webhooks. |
| `get_ai_clipping` | Returns the full job resource including produced clips, statuses, and presigned download URLs. |
| `delete_ai_clipping` | Soft-deletes an AI clip job and its clips. |

### Batches

| Tool Name | Description |
| - | - |
| `create_video_batch` | Submit up to 100 video creation payloads in one request and return a batch id immediately. Videos are created asynchronously; poll `GET /v3/videos/batches/{batch_id}` for per-item video ids and statuses. |
| `get_video_batch` | Returns batch aggregate status and one page of items with their video ids and statuses. Item statuses are one of queued, processing, completed, or failed. |
| `bulk_video_statuses` | Returns statuses for up to 100 videos in one request, addressed by comma-separated video\_ids and/or batch\_ids query params. Statuses are one of queued, processing, completed, or failed, plus not\_found for unknown or unowned ids. |

### Video Translation Batches

| Tool Name | Description |
| - | - |
| `create_video_translation_batch` | Submits up to 100 translation payloads, each shaped like `POST /v3/video-translations`, as one batch. A payload with several `output_languages` becomes one item per language, and items run independently. Returns 202 with a `batch_id` to poll. Send an Idempotency-Key to make retries safe. |
| `get_video_translation_batch` | Returns batch aggregate status and one page of items with their ids and statuses. Item statuses are one of queued, processing, completed, or failed. The per-item id is returned as video\_id (the batch read model is shared with the videos batch API). |
| `bulk_video_translation_statuses` | Returns statuses for up to 100 video translations by `video_translation_ids` and/or `batch_ids`: `queued`, `processing`, `completed`, `failed`, or `not_found`. Each entry's id is in `video_id`. |

### Lipsync Batches

| Tool Name | Description |
| - | - |
| `create_lipsync_batch` | Submits up to 100 lipsync payloads as one batch, and items run independently. Returns 202 with a `batch_id`; poll `GET /v3/lipsyncs/batches/{batch_id}`. Send an Idempotency-Key to make retries safe. |
| `get_lipsync_batch` | Returns batch aggregate status and one page of items with their ids and statuses. Item statuses are one of queued, processing, completed, or failed. The per-item id is returned as video\_id (the batch read model is shared with the videos batch API). |
| `bulk_lipsync_statuses` | Returns statuses for up to 100 lipsyncs by `lipsync_ids` and/or `batch_ids`: `queued`, `processing`, `completed`, `failed`, or `not_found`. Each entry's id is in `video_id`. |

### Asset Batches

| Tool Name | Description |
| - | - |
| `get_asset_batch` | Returns batch aggregate status and one page of items with their ids and statuses. Item statuses are one of queued, processing, completed, or failed. The per-item id is returned as video\_id (the batch read model is shared with the videos batch API); for asset batches it holds the asset\_id. |
| `complete_asset_batch` | Finalizes every uploaded file in a batch once all PUTs return 200. Files are ingested independently. Returns 202 with the `batch_id`; poll `GET /v3/assets/batches/{batch_id}` for progress. Safe to repeat. |
| `create_asset_upload_batch` | Returns up to 100 presigned upload URLs in one call. PUT each file to its `upload_url` with the returned headers, then call `POST /v3/assets/complete/batches`. Send an Idempotency-Key to make retries safe. |
| `bulk_asset_statuses` | Returns statuses for up to 100 assets by `asset_ids` and/or `batch_ids`: `queued`, `processing`, `completed`, `failed`, or `not_found`. Each entry's id is in `video_id`. |

### User

| Tool Name | Description |
| - | - |
| `get_current_user` | Returns the authenticated user's profile, remaining credits or balance, and billing details. |

### Avatars

| Tool Name | Description |
| - | - |
| `list_avatar_groups` | Returns a paginated list of avatar groups (characters). Each group contains one or more looks. Filterable by ownership. |
| `create_avatar` | Creates a new avatar from an image, video footage, or a text prompt. Supports photo, digital\_twin, and prompt types. Avatar training is asynchronous. |
| `list_look_templates` | Lists the look templates and Look Packs your workspace can apply with `POST /v3/avatars/looks`. Send an item's `id` as `template_id` and its `type` as `type`. Filter by `gender` to match your avatar. |
| `list_avatar_looks` | Returns a paginated list of avatar looks (outfits, poses, styles). Filterable by group\_id, avatar\_type, and ownership. The look id is the avatar\_id to pass when creating a video. |
| `create_avatar_looks` | Generates new looks for an existing avatar from `reference_look_id`. `type: look_pack` applies a Look Pack; `type: template` applies one look template and produces two looks. Billing happens when the request is accepted: an API key is charged 1 API credit per look, and a connected integration (OAuth, including MCP) the method's standard price from workspace credits. Free-tier MCP access cannot use this endpoint. Poll `GET /v3/avatars/looks/{id}` until each look finishes. |
| `get_avatar_look` | Returns details for a specific avatar look including supported engines, preferred orientation, preview URLs, and training status. |
| `update_avatar_look` | Updates the display name of an avatar look. Only supported for photo avatar and digital twin look types. |
| `delete_avatar_look` | Deletes an avatar look. Photo avatar, digital twin and kit-based looks can be deleted; studio avatars cannot. Deleting the last look in a group also deletes the group. |
| `get_avatar_group` | Returns details for a specific avatar group including name, gender, preview URLs, looks count, and training status. |
| `update_avatar_group` | Updates an avatar group you own. Currently sets `default_voice_id`, the voice this avatar uses by default; any voice in your workspace works, including clones. Public avatars cannot be updated. |
| `delete_avatar_group` | Permanently deletes an avatar group and all its associated looks. Cannot delete public or community groups. |
| `create_avatar_consent` | Starts the consent flow for an avatar group and returns a URL where the subject approves in their browser. Required before a private avatar can generate video. The link expires after 24 hours and accepts one submission. |

### Assets

| Tool Name | Description |
| - | - |
| `list_assets` | **Beta**: may change with a few days' notice. Lists a workspace member's uploaded assets, newest first, with cursor pagination. `username` is required during the beta. Pass `folder_id` to narrow to one folder, or an empty value for the root. |
| `create_asset_upload` | Begin a direct-to-S3 upload. Returns an asset\_id and a presigned upload\_url; PUT the file bytes to upload\_url, then call `POST /v3/assets/{asset_id}/complete`. Unlike `POST /v3/assets` (which proxies the bytes), this never sends the file through the API. |
| `get_asset` | Returns metadata for an asset in the caller's workspace — including owner, upload timestamp, file type, and a publicly accessible URL. |
| `delete_asset` | Permanently deletes an asset. The asset must belong to the caller's workspace and not already be deleted. |
| `complete_asset_upload` | Finalize a direct-to-S3 upload into a reusable asset. Call after the upload PUT returns 200. Idempotent: repeated calls return the same finalized asset. |

### Folders

| Tool Name | Description |
| - | - |
| `create_folder` | Creates a folder at the root or inside `parent_id`. Pass its `folder_id` to `POST /v3/videos` or `POST /v3/video-translations` to file output there. Names need not be unique, so store the ids you receive. Send an Idempotency-Key to make retries safe. |
| `get_folder` | Returns one folder in your workspace, including one in the trash (`is_trash`). Use it to check that a stored `folder_id` still exists. Deleted folders and folders in other workspaces return 404. |

### Lipsync

| Tool Name | Description |
| - | - |
| `list_lipsyncs` | Returns a paginated list of all lipsync jobs in the account. |
| `create_lipsync` | Replaces the audio on an existing video and re-animates the speaker's lip movements to match the new audio. Use mode: 'speed' for fast output or 'precision' for high-quality lip-sync. |
| `get_lipsync` | Returns details for a lipsync job including status, video\_url, caption\_url, and failure info if applicable. |
| `update_lipsync` | Updates the display title of a lipsync job. |
| `delete_lipsync` | Permanently deletes a lipsync job and its associated files. This action cannot be undone. |

### Brand

| Tool Name | Description |
| - | - |
| `list_brand_glossaries` | Lists the brand glossaries in your workspace. A glossary sets how terms are pronounced in generated speech and how they are handled in translation. Pass a `brand_glossary_id` when creating a video or translation to apply it. |
| `create_brand_glossary` | Creates a brand glossary. Pass the returned `brand_glossary_id` when creating a video or translation to apply it. `name` must be unique in the workspace, ignoring case; a duplicate returns 409. Term lists are optional and can be added later with PATCH. |
| `get_brand_glossary` | Returns one brand glossary with its full term list. Pronunciations affect generated audio only, not captions. Translation rules (`do_not_translate_terms`, `forced_translations`) apply only to translation features; a list is omitted from the response when it is empty. Tone settings are not returned here. |
| `update_brand_glossary` | Updates a brand glossary. A field you omit is left untouched, a list you send replaces the existing list in full, and an empty array removes every entry. A name already used in the workspace returns 409. Tone settings are never modified by this endpoint. |
| `delete_brand_glossary` | Deletes a brand glossary. This cannot be undone. Its pronunciation terms and translation rules stop applying to anything generated afterwards; videos already generated are unaffected, and requests that still reference it keep working. |
| `list_brand_kits` | Returns brand kits available in the authenticated user's workspace. Each brand kit contains colors, fonts, and logos that can be applied to Video Agent sessions. Use the returned brand\_kit\_id with `POST /v3/video-agents` to generate on-brand videos. |
| `create_brand_kit` | Creates a brand kit by importing logos, colors and fonts from a public website; by calling it you confirm you have the rights to use those assets. The kit assembles in the background: poll `GET /v3/brand-kits/{brand_kit_id}` until status is `completed`. Send an Idempotency-Key to make retries safe. |
| `get_brand_kit` | Returns one brand kit with its colors, logos and fonts and the role each plays. While status is `loading` these are provisional; poll every 2 to 5 seconds until status is `completed`. |
| `update_brand_kit` | Updates a brand kit's name or role assignments: color roles, main logo, heading and body fonts. Omitted fields are unchanged and `null` is rejected. Each role object you send replaces the existing one in full; `{}` clears a role and it stays cleared. Role edits return 409 until the kit is `completed`; shared kits return 403. |
| `delete_brand_kit` | Deletes a brand kit and its colors, logos and fonts. This cannot be undone. Videos already rendered with it are unaffected. A kit shared from another workspace cannot be deleted and returns 403. |

### Models

| Tool Name | Description |
| - | - |
| `generate_model_speech` | Generate speech from the voice identified by `voice_id`. The request stays open until speech generation finishes. The response contains a URL to a 44.1 kHz mono WAV file. ### Voice and settings Use an `ACTIVE` HeyGen Voice clone in your workspace. `heygen-voice-1-turbo` speaks instant clones at lower latency and refuses professional clones. API-key billing accumulates fractional usage. OAuth requests, including MCP calls, are rounded up per request to whole billing units, so their effective cost can be higher. `seed`, `speed`, `pitch_shift`, and `pitch_variance` apply only to professional clones. Instant clones, including Turbo, accept and ignore these controls. ### Language Set `language` to the language of `text`. If you omit it, the language is detected from `text`. Successful responses include `Content-Language`, the language the speech was generated in. ### Limits and request ID The rate limit is 30 requests per minute per workspace member. Successful responses include `X-Request-Id`. Use this ID when you contact support about the request. |
| `list_model_audio_voices` | Returns model-backed audio voices, ordered newest first. With the default `type=private`, these are the voices in the caller's workspace, professional and instant; `mode` tells them apart. With `type=public`, these are the voices HeyGen provides to every workspace. Use `limit` and `token` to retrieve additional pages. |
| `create_model_audio_voice` | Creates an instant voice with `mode: instant` from one recording, or a professional voice with `mode: professional`. Instant voices do not support retraining. Use `POST /v3/models/audio/tts/stream` for streaming speech; model defaults to heygen-voice-1. Instant voices ignore seed, speed and pitch controls. Mode is required for both creation and retraining. Retrains a professional voice when `voice_id` is set. The voice is `PENDING` while training; poll `GET /v3/models/audio/voices/{voice_id}` until it is `ACTIVE` or `FAILED`. A new voice in professional mode needs a free professional-voice slot; each purchased slot provides five pooled trainings per monthly billing period, including the first, and failed trainings do not count. Send an Idempotency-Key to make retries safe. |
| `get_model_audio_voice` | Returns one model-backed audio voice, owned by the caller's workspace or public, and its current lifecycle state. `PENDING` covers queued and running work, `ACTIVE` is ready for inference, and `FAILED` is terminal. An instant voice is `ACTIVE` as soon as it can speak. |
| `delete_model_audio_voice` | Deletes the caller-owned model-backed audio voice. The voice is removed from subsequent reads. A professional voice cannot be deleted while its status is `PENDING`: wait for training to finish and retry. Deleting an instant voice that is still being created cancels it. Repeating a successful deletion returns the same successful response. |
| `create_image_generation` | Generate one to five portraits with identity\_remix, the default and only supported mode. Provide one to five identity\_images and exactly one item in reference\_images. The output preserves the identity while following the reference image's clothing, pose, composition, and background. Returns a generation\_id to poll. The job completes when all requested images are available; partial results are not returned. |
| `get_image_generation` | Return the generation job status and ordered images with fresh download URLs once the entire job completes. |
| `create_model_video` | Generates a scene with its sound from a prompt using HeyGen Video (`heygen-video-1`). Set `mode` to `text_to_video`, `image_to_video` or `reference_to_video`; reference-to-video takes up to twelve references in total, and reference videos must be between 1:4 and 4:1. Returns 202 with a `video_id`; poll `GET /v3/models/videos/{video_id}`. Send an Idempotency-Key to retry safely; without one, each submission creates a new generation. To have an avatar speak a script, use `POST /v3/videos`. |
| `get_model_video` | Returns a HeyGen Video generation: `pending`, `processing`, `completed`, `failed` or `cancelled`. Completed results include a fresh `video_url`, duration and dimensions; failed results include `failure_code` and `failure_message`. Poll again to refresh an expired URL. |

### Filler Word Removal

| Tool Name | Description |
| - | - |
| `create_filler_word_removal` | Submits a video for filler-word removal and returns a job id. The job cuts filler words and long silences and renders one cleaned video; if nothing changes, the charge is refunded. \$0.30 per source minute, 1-minute minimum. Poll `GET /v3/filler-word-removals/{id}` or use webhooks. |
| `get_filler_word_removal` | Returns the job resource: lifecycle status, progress, and — once completed — the presigned download URL of the cleaned video plus removal statistics (num\_cuts, reduction\_pct, durations). |

## Supported Products

HeyGen Remote MCP works with any MCP-compatible agent, including:

* **Claude** (Web, Desktop, and Code)
* **Codex CLI**
* **Cursor** (available in the [Cursor marketplace](https://cursor.com/marketplace/heygen))
* **Gemini CLI**
* **Lovable**
* **Manus**
* **Superhuman**
* **OpenAI**
* and more

See the dedicated setup guide for each product for detailed instructions.

## Connect Your Own Agent

You can integrate HeyGen Remote MCP into any custom agent or application that supports the Model Context Protocol. Just point it to the endpoint:

```text theme={null}
https://mcp.heygen.com/mcp/v1/
```

For security, HeyGen Remote MCP uses domain whitelisting. If your agent runs on a domain that isn't already whitelisted, you'll need to request access before it can connect.

## Remote MCP

| | Remote MCP |
| - | - |
| **Setup** | Add endpoint URL, authenticate via OAuth |
| **Runs on** | HeyGen's hosted infrastructure |
| **Authentication** | OAuth (no API key needed) |
| **Billing** | Web plan + premium credits |
| **Best for** | Most users — quick setup, works everywhere |

## FAQ

**Do I need an API key?** No. Remote MCP uses OAuth authentication tied to your HeyGen account. No API key required.

**Does this cost extra?** No. Video generation uses the credits included in your existing HeyGen plan.

**Which HeyGen plans support this?** Remote MCP is available on all HeyGen plans.

**Can I use my custom avatars and voices?** Yes. Any avatars and voices available in your HeyGen account are accessible through Remote MCP.

**What's the difference between this and the HeyGen API?** The HeyGen API gives you direct REST endpoints for programmatic control. Remote MCP wraps those capabilities so AI agents can use them conversationally — without you writing integration code.


# Superhuman
Source: https://heygen-1fa696a7.mintlify.app/mcp/superhuman

Add the HeyGen agent to Superhuman Go and turn any page into an AI avatar video.

Turn whatever is on your screen into a HeyGen video with Superhuman Go, the agent side panel in the Grammarly extension.

<Steps>
  <Step title="Open Superhuman Go">
    <div>
      <div>
        With the Grammarly extension installed, open the **Superhuman Go** side panel.
      </div>

      <div>
        <Frame>
          <img alt="Superhuman Go side panel" />
        </Frame>
      </div>
    </div>
  </Step>

  <Step title="Add the HeyGen agent">
    <div>
      <div>
        Click **+** (Add agents), search `heygen`, and select **HeyGen**.
      </div>

      <div>
        <Frame>
          <img alt="HeyGen in the Add agents search" />
        </Frame>
      </div>
    </div>
  </Step>

  <Step title="Connect your HeyGen account">
    <div>
      <div>
        Click **Sign in** and approve access. HeyGen now has its own chat in the sidebar.
      </div>

      <div>
        <Frame>
          <img alt="HeyGen agent sign-in" />
        </Frame>

        <Frame>
          <img alt="HeyGen agent in the Superhuman Go sidebar" />
        </Frame>
      </div>
    </div>
  </Step>

  <Step title="Ask for a video">
    <div>
      <div>
        On any page, ask:

        ```text wrap theme={null}
        Create a short video summary of the content on my screen.
        ```

        Click **Approve** when HeyGen asks to create the video. It plays in the panel when ready, with **Open in HeyGen** to share or edit.
      </div>

      <div>
        <Frame>
          <img alt="HeyGen video request waiting on Approve in Superhuman Go" />
        </Frame>
      </div>
    </div>
  </Step>
</Steps>

<Tip>
  Chain HeyGen with your other agents, for example: *"Get my notes from Granola and make a HeyGen video summary."*
</Tip>


# Output Modes
Source: https://heygen-1fa696a7.mintlify.app/output-modes

Pick the right HeyGen CLI output mode for your workflow. Defaults to agent-friendly JSON; supports streaming, pretty-print, and machine-readable formats.

The CLI is **agent-first**: the default output is structured JSON — no spinners, no color codes, no decorations. Just parseable data on stdout. Progress, warnings, and errors go to stderr so piping always works cleanly.

Humans can opt into a prettier experience with `--human`.

## Default: JSON (Agent-Friendly)

Every command outputs clean JSON by default. The response follows the HeyGen API envelope shape — a top-level `data` field wraps the payload:

```bash theme={null}
heygen avatar list
```

```json theme={null}
{
  "data": [
    {
      "id": "avt_angela_01",
      "name": "Angela",
      "gender": "female",
      "looks_count": 3,
      "preview_image_url": "https://files.heygen.com/avatar/avt_angela_01.jpg",
      "default_voice_id": "1bd001e7e50f421d891986aad5e3e5d2",
      "created_at": 1709856000
    }
  ],
  "has_more": true,
  "next_token": "eyJsYXN0X2lkIjoiYXZ0X21hcmN1c18wMiJ9"
}
```

## `--human`: Pretty Output for Humans

Add `--human` when you're working interactively. You get tables, colorized status values, and human-readable timestamps:

```bash theme={null}
heygen video list --human
```

```text theme={null}
ID                                Title                     Status     Created
4621f8ba1a8f4811b32f669c37be53a2  HeyGen in 20 Seconds      completed  2026-03-28 15:48
75c58ba041394ddcb3737d7eff9d514b  Video Agent Weekly Recap  completed  2026-03-25 22:18

Showing 4 of 5 columns. Remove --human for full JSON output.
```

For `get` commands (single resource), `--human` renders a key-value layout:

```bash theme={null}
heygen video get abc123 --human
```

```text theme={null}
Id:          abc123
Status:      completed
Title:       Demo
```

When `--wait` is used in human mode, the CLI shows a live spinner on stderr while polling:

```bash theme={null}
heygen video-agent create --prompt "Product demo" --wait --human
```

```text theme={null}
· Processing... (42s)
```

On a non-TTY stderr (e.g. in CI with `--human`), the spinner falls back to plain-text status lines:

```text theme={null}
Polling: status=processing (elapsed 10s)
Polling: status=processing (elapsed 22s)
```

## Errors

Errors always go to stderr as a structured JSON envelope, regardless of output mode:

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Video abc123 not found",
    "hint": "Check ID with: heygen video list",
    "request_id": "req_abc123"
  }
}
```

In `--human` mode, errors render as readable text instead:

```text theme={null}
Error: Video abc123 not found
Hint:  Check ID with: heygen video list
```

The `request_id` field is included when the error comes from the API (from the `X-Request-ID` response header). It is omitted for local errors such as bad flags or missing credentials.

## Exit Codes

| Code | Meaning |
| - | - |
| `0` | Success |
| `1` | General error (API error, network failure) |
| `2` | Usage error (invalid flags, missing arguments) |
| `3` | Authentication error (missing or invalid API key) |
| `4` | Timeout (resource created but polling timed out) |

Exit code `4` is distinct from `1` so agents and scripts can tell "the resource was created but we don't know the final status" apart from a hard failure. Stdout will contain the last known resource state when exit `4` occurs.

## Configuring a Default Output Mode

Set a persistent default so you don't need `--human` on every command:

```bash theme={null}
heygen config set output human
```

Valid values are `json` (default) and `human`. The priority order is:

**`--human` flag → `HEYGEN_OUTPUT` env var → `config set output` → default (`json`)**

```bash theme={null}
# Always human by default, but get JSON for this one invocation
heygen config set output human
heygen video get vid_xyz789 --output json
```

## Stdout vs Stderr

The CLI strictly separates data from everything else:

* **stdout** — JSON payload only. This is what gets piped to `jq`, captured in shell variables, or consumed by agents.
* **stderr** — progress indicators, warnings, and error messages.

This means piping works cleanly with no extra flags:

```bash theme={null}
# Extract all video IDs from your account
heygen video list | jq -r '.data[].id'

# Create a video and immediately open the URL in your browser
VIDEO_ID=$(heygen video-agent create --prompt "Demo video" | jq -r '.data.video_id')
heygen video get "$VIDEO_ID" --wait | jq -r '.data.video_url' | xargs open
```


# Photo Avatar
Source: https://heygen-1fa696a7.mintlify.app/photo-avatar

Turn a single photo into a talking AI avatar with the HeyGen Photo Avatar API. Upload an image, attach a script, render a lipsynced video starring that photo.

<img alt="" />

## Prerequisites

<Check>
  A portrait photo (PNG or JPEG) — clear, front-facing, good lighting
</Check>

<Check>
  A `voice_id` for the voice you want. Use `GET /v3/voices` to browse options.
</Check>

## Step 1 — Create a Photo Avatar

Upload your photo and create a Photo Avatar with `POST /v3/avatars`:

<Tabs>
  <Tab title="From URL">
    ```bash theme={null}
    curl -X POST "https://api.heygen.com/v3/avatars" \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "photo",
        "name": "Sarah — Marketing",
        "file": {
          "type": "url",
          "url": "https://example.com/portrait.jpg"
        }
      }'
    ```
  </Tab>

  <Tab title="From Asset ID">
    First upload the image via `POST /v3/assets`, then reference the returned `asset_id`:

    ```bash theme={null}
    # Upload the image
    curl -X POST "https://api.heygen.com/v3/assets" \
      -H "x-api-key: YOUR_API_KEY" \
      -F "file=@portrait.jpg"

    # Create the avatar
    curl -X POST "https://api.heygen.com/v3/avatars" \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "photo",
        "name": "Sarah — Marketing",
        "file": {
          "type": "asset_id",
          "asset_id": "RETURNED_ASSET_ID"
        }
      }'
    ```
  </Tab>
</Tabs>

The response includes an `avatar_item` with an `id` — this is your `avatar_id` for video creation.

## Step 2 — Generate the video

Use `POST /v3/videos` with `type: "avatar"` and the Photo Avatar ID:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar",
    "avatar_id": "YOUR_PHOTO_AVATAR_ID",
    "script": "Hi there! This video was created from a single photo using the HeyGen API.",
    "voice_id": "YOUR_VOICE_ID",
    "title": "Photo Avatar Demo",
    "resolution": "1080p",
    "aspect_ratio": "auto"
  }'
```

## Step 3 — Poll for completion

Video generation is asynchronous. Poll until `status` reaches `completed`:

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/videos/YOUR_VIDEO_ID" \
  -H "x-api-key: YOUR_API_KEY"
```

| Status | Meaning |
| - | - |
| `pending` | Queued for processing |
| `processing` | Video is being generated |
| `completed` | Ready — `video_url` is available |
| `failed` | Something went wrong |

## Full example

```python theme={null}
import requests
import time

API_KEY = "YOUR_API_KEY"
BASE = "https://api.heygen.com"
HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}

# 1. Create a Photo Avatar from a URL
avatar_resp = requests.post(f"{BASE}/v3/avatars", headers=HEADERS, json={
    "type": "photo",
    "name": "Demo Avatar",
    "file": {
        "type": "url",
        "url": "https://example.com/portrait.jpg"
    }
})
avatar_id = avatar_resp.json()["data"]["avatar_item"]["id"]
print(f"Avatar created: {avatar_id}")

# 2. Generate a video
video_resp = requests.post(f"{BASE}/v3/videos", headers=HEADERS, json={
    "type": "avatar",
    "avatar_id": avatar_id,
    "script": "Welcome! This is a Photo Avatar created from a single image.",
    "voice_id": "YOUR_VOICE_ID",
    "resolution": "1080p",
    "aspect_ratio": "auto"
})
video_id = video_resp.json()["data"]["video_id"]
print(f"Video created: {video_id}")

# 3. Poll until done
while True:
    status_resp = requests.get(f"{BASE}/v3/videos/{video_id}", headers=HEADERS)
    data = status_resp.json()["data"]
    print(f"Status: {data['status']}")
    if data["status"] == "completed":
        print(f"Download: {data['video_url']}")
        break
    elif data["status"] == "failed":
        print(f"Error: {data.get('failure_message')}")
        break
    time.sleep(10)
```

## Photo Avatar–specific parameters

These parameters are only available when using a Photo Avatar (`avatar_type: photo_avatar`):

| Parameter | Type | Description |
| - | - | - |
| `motion_prompt` | string | Natural-language prompt to control body motion and hand gestures (e.g. "nodding gently") |
| `expressiveness` | string | `high`, `medium`, or `low` (default: `low`) |

### Example with motion and expressiveness

```json theme={null}
{
  "type": "avatar",
  "avatar_id": "YOUR_PHOTO_AVATAR_ID",
  "script": "Let me show you our quarterly results.",
  "voice_id": "YOUR_VOICE_ID",
  "motion_prompt": "gesturing with hands while presenting",
  "expressiveness": "high"
}
```

## Optional parameters

| Parameter | Type | Description |
| - | - | - |
| `title` | string | Display name in the HeyGen dashboard |
| `resolution` | string | `1080p` (recommended) or `720p` |
| `aspect_ratio` | string | `auto` (recommended — matches the source, falling back to `16:9`), `16:9`, `9:16`, `4:5`, `5:4`, or `1:1` |
| `remove_background` | boolean | Remove the avatar background |
| `background` | object | Set a solid color (`type: "color"`) or image background |
| `voice_settings` | object | Adjust `speed`, `pitch`, and `locale` |
| `callback_url` | string | Webhook URL for completion notification |

<Warning>
  Photo quality matters. Use a well-lit, front-facing portrait with a neutral expression for the best results. Avoid sunglasses, hats covering the forehead, or extreme angles.
</Warning>

## Using a preset Photo Avatar

You can skip avatar creation and use a public preset avatar instead:

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/avatars/looks?avatar_type=photo_avatar&ownership=public" \
  -H "x-api-key: YOUR_API_KEY"
```

Pick any `id` from the response and use it directly as your `avatar_id` in `POST /v3/videos`.


# Bulk Asset Statuses
Source: https://heygen-1fa696a7.mintlify.app/reference/bulk-asset-statuses

/openapi/external-api.json get /v3/assets/statuses
Returns statuses for up to 100 assets by `asset_ids` and/or `batch_ids`: `queued`, `processing`, `completed`, `failed`, or `not_found`. Each entry's id is in `video_id`.



# Bulk Lipsync Statuses
Source: https://heygen-1fa696a7.mintlify.app/reference/bulk-lipsync-statuses

/openapi/external-api.json get /v3/lipsyncs/statuses
Returns statuses for up to 100 lipsyncs by `lipsync_ids` and/or `batch_ids`: `queued`, `processing`, `completed`, `failed`, or `not_found`. Each entry's id is in `video_id`.



# Bulk Video Statuses
Source: https://heygen-1fa696a7.mintlify.app/reference/bulk-video-statuses

/openapi/external-api.json get /v3/videos/statuses
Returns statuses for up to 100 videos in one request, addressed by comma-separated video_ids and/or batch_ids query params. Statuses are one of queued, processing, completed, or failed, plus not_found for unknown or unowned ids.



# Bulk Video Translation Statuses
Source: https://heygen-1fa696a7.mintlify.app/reference/bulk-video-translation-statuses

/openapi/external-api.json get /v3/video-translations/statuses
Returns statuses for up to 100 video translations by `video_translation_ids` and/or `batch_ids`: `queued`, `processing`, `completed`, `failed`, or `not_found`. Each entry's id is in `video_id`.



# Clone a Voice
Source: https://heygen-1fa696a7.mintlify.app/reference/clone-a-voice

/openapi/external-api.json post /v3/voices/clone
Creates a voice clone from an audio file. Returns a voice_clone_id that can be polled via GET /v3/voices/{voice_clone_id} until the status is 'complete'. The resulting voice can be used with POST /v3/voices/speech and POST /v3/videos.



# Complete Asset Upload
Source: https://heygen-1fa696a7.mintlify.app/reference/complete-asset-upload

/openapi/external-api.json post /v3/assets/{asset_id}/complete
Finalize a direct-to-S3 upload into a reusable asset. Call after the upload PUT returns 200. Idempotent: repeated calls return the same finalized asset.



# Complete Asset Upload Batch
Source: https://heygen-1fa696a7.mintlify.app/reference/complete-asset-upload-batch

/openapi/external-api.json post /v3/assets/complete/batches
Finalizes every uploaded file in a batch once all PUTs return 200. Files are ingested independently. Returns 202 with the `batch_id`; poll GET /v3/assets/batches/{batch_id} for progress. Safe to repeat.



# Create AI Clipping
Source: https://heygen-1fa696a7.mintlify.app/reference/create-ai-clipping

/openapi/external-api.json post /v3/ai-clipping
Submit a source video and return a job id immediately. The job runs asynchronously and produces one or more short clips per the requested output_settings. Poll GET /v3/ai-clipping/{id} or subscribe to ai_clipping.success / ai_clipping.fail webhooks.



# Create Asset Upload
Source: https://heygen-1fa696a7.mintlify.app/reference/create-asset-upload

/openapi/external-api.json post /v3/assets/direct-uploads
Begin a direct-to-S3 upload. Returns an asset_id and a presigned upload_url; PUT the file bytes to upload_url, then call POST /v3/assets/{asset_id}/complete. Unlike POST /v3/assets (which proxies the bytes), this never sends the file through the API.



# Create Asset Upload Batch
Source: https://heygen-1fa696a7.mintlify.app/reference/create-asset-upload-batch

/openapi/external-api.json post /v3/assets/direct-uploads/batches
Returns up to 100 presigned upload URLs in one call. PUT each file to its `upload_url` with the returned headers, then call POST /v3/assets/complete/batches. Send an Idempotency-Key to make retries safe.



# Create Avatar
Source: https://heygen-1fa696a7.mintlify.app/reference/create-avatar

/openapi/external-api.json post /v3/avatars
Creates a new avatar from an image, video footage, or a text prompt. Supports photo, digital_twin, and prompt types. Avatar training is asynchronous.



# Create Avatar Consent
Source: https://heygen-1fa696a7.mintlify.app/reference/create-avatar-consent

/openapi/external-api.json post /v3/avatars/{group_id}/consent
Starts the consent flow for an avatar group and returns a URL where the subject approves in their browser. Required before a private avatar can generate video. The link expires after 24 hours and accepts one submission.



# Create Avatar Looks
Source: https://heygen-1fa696a7.mintlify.app/reference/create-avatar-looks

/openapi/external-api.json post /v3/avatars/looks
Generates new looks for an existing avatar from `reference_look_id`. `type: look_pack` applies a Look Pack; `type: template` applies one look template and produces two looks. Billing happens when the request is accepted: an API key is charged 1 API credit per look, and a connected integration (OAuth, including MCP) the method's standard price from workspace credits. Free-tier MCP access cannot use this endpoint. Poll GET /v3/avatars/looks/{id} until each look finishes.



# Create Brand Glossary
Source: https://heygen-1fa696a7.mintlify.app/reference/create-brand-glossary

/openapi/external-api.json post /v3/brand-glossaries
Creates a brand glossary. Pass the returned `brand_glossary_id` when creating a video or translation to apply it. `name` must be unique in the workspace, ignoring case; a duplicate returns 409. Term lists are optional and can be added later with PATCH.



# Create Brand Kit
Source: https://heygen-1fa696a7.mintlify.app/reference/create-brand-kit

/openapi/external-api.json post /v3/brand-kits
Creates a brand kit by importing logos, colors and fonts from a public website; by calling it you confirm you have the rights to use those assets. The kit assembles in the background: poll GET /v3/brand-kits/{brand_kit_id} until status is `completed`. Send an Idempotency-Key to make retries safe.



# Create Filler Word Removal
Source: https://heygen-1fa696a7.mintlify.app/reference/create-filler-word-removal

/openapi/external-api.json post /v3/filler-word-removals
Submits a video for filler-word removal and returns a job id. The job cuts filler words and long silences and renders one cleaned video; if nothing changes, the charge is refunded. \$0.30 per source minute, 1-minute minimum. Poll GET /v3/filler-word-removals/{id} or use webhooks.



# Create Folder
Source: https://heygen-1fa696a7.mintlify.app/reference/create-folder

/openapi/external-api.json post /v3/folders
Creates a folder at the root or inside `parent_id`. Pass its `folder_id` to POST /v3/videos or POST /v3/video-translations to file output there. Names need not be unique, so store the ids you receive. Send an Idempotency-Key to make retries safe.



# Create HeyGen Image
Source: https://heygen-1fa696a7.mintlify.app/reference/create-heygen-image

/openapi/external-api.json post /v3/models/images
Generate one to five portraits with identity_remix, the default and only supported mode. Provide one to five identity_images and exactly one item in reference_images. The output preserves the identity while following the reference image's clothing, pose, composition, and background. Returns a generation_id to poll. The job completes when all requested images are available; partial results are not returned.



# Create HeyGen Video
Source: https://heygen-1fa696a7.mintlify.app/reference/create-heygen-video

/openapi/external-api.json post /v3/models/videos
Generates a scene with its sound from a prompt using HeyGen Video (`heygen-video-1`). Set `mode` to `text_to_video`, `image_to_video` or `reference_to_video`; reference-to-video takes up to twelve references in total, and reference videos must be between 1:4 and 4:1. Returns 202 with a `video_id`; poll GET /v3/models/videos/{video_id}. Send an Idempotency-Key to retry safely; without one, each submission creates a new generation. To have an avatar speak a script, use POST /v3/videos.



# Create HyperFrames Render
Source: https://heygen-1fa696a7.mintlify.app/reference/create-hyperframes-render

/openapi/external-api.json post /v3/hyperframes/renders
Renders a HyperFrames composition (an HTML+JS+assets project bundled as a .zip) into a video. Submit the project via `url`, `asset_id` (pre-uploaded via POST /v3/assets), or inline `base64`. Returns a `render_id` to poll via GET /v3/hyperframes/renders/{render_id}.



# Create Lipsync
Source: https://heygen-1fa696a7.mintlify.app/reference/create-lipsync

/openapi/external-api.json post /v3/lipsyncs
Replaces the audio on an existing video and re-animates the speaker's lip movements to match the new audio. Use mode: 'speed' for fast output or 'precision' for high-quality lip-sync.



# Create Lipsync Batch
Source: https://heygen-1fa696a7.mintlify.app/reference/create-lipsync-batch

/openapi/external-api.json post /v3/lipsyncs/batches
Submits up to 100 lipsync payloads as one batch, and items run independently. Returns 202 with a `batch_id`; poll GET /v3/lipsyncs/batches/{batch_id}. Send an Idempotency-Key to make retries safe.



# Create or Retrain an Audio Voice
Source: https://heygen-1fa696a7.mintlify.app/reference/create-or-retrain-an-audio-voice

/openapi/external-api.json post /v3/models/audio/voices
Creates an instant voice with `mode: instant` from one recording, or a professional voice with `mode: professional`. Instant voices do not support retraining. Use POST /v3/models/audio/tts/stream for streaming speech; model defaults to heygen-voice-1. Instant voices ignore seed, speed and pitch controls. Mode is required for both creation and retraining. Retrains a professional voice when `voice_id` is set. The voice is `PENDING` while training; poll GET /v3/models/audio/voices/{voice_id} until it is `ACTIVE` or `FAILED`. A new voice in professional mode needs a free professional-voice slot; each purchased slot provides five pooled trainings per monthly billing period, including the first, and failed trainings do not count. Send an Idempotency-Key to make retries safe.



# Create Proofread Session
Source: https://heygen-1fa696a7.mintlify.app/reference/create-proofread-session

/openapi/external-api.json post /v3/video-translations/proofreads
Creates a proofread session that extracts editable subtitles from a video before final rendering.



# Create Template from Video
Source: https://heygen-1fa696a7.mintlify.app/reference/create-template-from-video

/openapi/external-api.json post /v3/templates
Creates a private template from one of your videos, copying its scenes, avatars, script and media. URL-to-Video and older editor videos return `template_source_unsupported`. The template starts with no variables; declare them with PUT /v3/templates/{template_id}/variables.



# Create Video
Source: https://heygen-1fa696a7.mintlify.app/reference/create-video

/openapi/external-api.json post /v3/videos
Creates an avatar video: a HeyGen avatar or an image speaks your script or audio with lip-sync. Choose Avatar III, IV or V with `engine` (Avatar IV by default). To generate a whole scene from a prompt instead, use POST /v3/models/videos.



# Create Video Agent Session
Source: https://heygen-1fa696a7.mintlify.app/reference/create-video-agent-session

/openapi/external-api.json post /v3/video-agents
One-shot video generation from a prompt — agent handles scripting, avatar selection, scene composition, and rendering. Supports generate (fire-and-forget) and chat (multi-turn) modes.



# Create Video Batch
Source: https://heygen-1fa696a7.mintlify.app/reference/create-video-batch

/openapi/external-api.json post /v3/videos/batches
Submit up to 100 video creation payloads in one request and return a batch id immediately. Videos are created asynchronously; poll GET /v3/videos/batches/{batch_id} for per-item video ids and statuses.



# Create Video Translation
Source: https://heygen-1fa696a7.mintlify.app/reference/create-video-translation

/openapi/external-api.json post /v3/video-translations
Translates a video into one or more target languages with voice cloning and lip-sync. Returns one video_translation_id per language. Use mode: 'speed' (default) for fast turnaround or 'precision' for higher lip-sync quality.



# Create Video Translation Batch
Source: https://heygen-1fa696a7.mintlify.app/reference/create-video-translation-batch

/openapi/external-api.json post /v3/video-translations/batches
Submits up to 100 translation payloads, each shaped like POST /v3/video-translations, as one batch. A payload with several `output_languages` becomes one item per language, and items run independently. Returns 202 with a `batch_id` to poll. Send an Idempotency-Key to make retries safe.



# Create Webhook Endpoint
Source: https://heygen-1fa696a7.mintlify.app/reference/create-webhook-endpoint

/openapi/external-api.json post /v3/webhooks/endpoints
Registers an HTTPS URL to receive webhook event notifications. Returns the endpoint details and a signing secret. The signing secret is only shown at creation and rotation — store it securely.



# Delete a Voice
Source: https://heygen-1fa696a7.mintlify.app/reference/delete-a-voice

/openapi/external-api.json delete /v3/voices/{voice_id}
Deletes a voice clone you own and frees its place in your clone limit. A voice used by a template cannot be deleted. An unknown or already-deleted voice returns 404 `voice_not_found`; treat that as success in delete-then-list flows.



# Delete AI Clipping
Source: https://heygen-1fa696a7.mintlify.app/reference/delete-ai-clipping

/openapi/external-api.json delete /v3/ai-clipping/{job_id}
Soft-deletes an AI clip job and its clips.



# Delete an Audio Voice
Source: https://heygen-1fa696a7.mintlify.app/reference/delete-an-audio-voice

/openapi/external-api.json delete /v3/models/audio/voices/{voice_id}
Deletes the caller-owned model-backed audio voice. The voice is removed from subsequent reads. A professional voice cannot be deleted while its status is `PENDING`: wait for training to finish and retry. Deleting an instant voice that is still being created cancels it. Repeating a successful deletion returns the same successful response.



# Delete Asset
Source: https://heygen-1fa696a7.mintlify.app/reference/delete-asset

/openapi/external-api.json delete /v3/assets/{asset_id}
Permanently deletes an asset. The asset must belong to the caller's workspace and not already be deleted.



# Delete Avatar Group
Source: https://heygen-1fa696a7.mintlify.app/reference/delete-avatar-group

/openapi/external-api.json delete /v3/avatars/{group_id}
Permanently deletes an avatar group and all its associated looks. Cannot delete public or community groups.



# Delete Avatar Look
Source: https://heygen-1fa696a7.mintlify.app/reference/delete-avatar-look

/openapi/external-api.json delete /v3/avatars/looks/{look_id}
Deletes an avatar look. Photo avatar, digital twin and kit-based looks can be deleted; studio avatars cannot. Deleting the last look in a group also deletes the group.



# Delete Brand Glossary
Source: https://heygen-1fa696a7.mintlify.app/reference/delete-brand-glossary

/openapi/external-api.json delete /v3/brand-glossaries/{brand_glossary_id}
Deletes a brand glossary. This cannot be undone. Its pronunciation terms and translation rules stop applying to anything generated afterwards; videos already generated are unaffected, and requests that still reference it keep working.



# Delete Brand Kit
Source: https://heygen-1fa696a7.mintlify.app/reference/delete-brand-kit

/openapi/external-api.json delete /v3/brand-kits/{brand_kit_id}
Deletes a brand kit and its colors, logos and fonts. This cannot be undone. Videos already rendered with it are unaffected. A kit shared from another workspace cannot be deleted and returns 403.



# Delete HyperFrames Render
Source: https://heygen-1fa696a7.mintlify.app/reference/delete-hyperframes-render

/openapi/external-api.json delete /v3/hyperframes/renders/{render_id}
Soft-deletes a HyperFrames render. Subsequent GETs return 404.



# Delete Lipsync
Source: https://heygen-1fa696a7.mintlify.app/reference/delete-lipsync

/openapi/external-api.json delete /v3/lipsyncs/{lipsync_id}
Permanently deletes a lipsync job and its associated files. This action cannot be undone.



# Delete Proofread Session
Source: https://heygen-1fa696a7.mintlify.app/reference/delete-proofread-session

/openapi/external-api.json delete /v3/video-translations/proofreads/{proofread_id}
Deletes a proofread session, removing it from listings and from the workspace's projects. Requires an account role of Creator or higher. This action cannot be undone.



# Delete Template
Source: https://heygen-1fa696a7.mintlify.app/reference/delete-template

/openapi/external-api.json delete /v3/templates/{template_id}
Soft-deletes a template. It disappears from the list and can no longer be used to generate videos; videos already generated from it are unaffected. Templates managed by another HeyGen product cannot be deleted here.



# Delete Video
Source: https://heygen-1fa696a7.mintlify.app/reference/delete-video

/openapi/external-api.json delete /v3/videos/{video_id}
Permanently deletes a video and its associated files. This action cannot be undone.



# Delete Video Translation
Source: https://heygen-1fa696a7.mintlify.app/reference/delete-video-translation

/openapi/external-api.json delete /v3/video-translations/{video_translation_id}
Permanently deletes a video translation and its associated files. This action cannot be undone.



# Delete Webhook Endpoint
Source: https://heygen-1fa696a7.mintlify.app/reference/delete-webhook-endpoint

/openapi/external-api.json delete /v3/webhooks/endpoints/{endpoint_id}
Permanently removes a webhook endpoint. Events will no longer be delivered to this URL. This action cannot be undone.



# Design a Voice
Source: https://heygen-1fa696a7.mintlify.app/reference/design-a-voice

/openapi/external-api.json post /v3/voices
Returns up to 3 voices matching a natural language description (e.g. 'warm, confident female narrator'). Use the seed parameter to get different batches of results.



# Download Proofread SRT
Source: https://heygen-1fa696a7.mintlify.app/reference/download-proofread-srt

/openapi/external-api.json get /v3/video-translations/proofreads/{proofread_id}/srt
Returns presigned download URLs for the edited and original SRT files of a completed proofread session.



# Generate Speech
Source: https://heygen-1fa696a7.mintlify.app/reference/generate-model-speech

/openapi/external-api.json post /v3/models/audio/tts
Generate speech from the voice identified by `voice_id`.

The request stays open until speech generation finishes. The response contains a URL to a 44.1 kHz mono WAV file.

### Voice and settings

Use an `ACTIVE` HeyGen Voice clone in your workspace. `heygen-voice-1-turbo` speaks instant clones at lower latency and refuses professional clones. API-key billing accumulates fractional usage. OAuth requests, including MCP calls, are rounded up per request to whole billing units, so their effective cost can be higher.

`seed`, `speed`, `pitch_shift`, and `pitch_variance` apply only to professional clones. Instant clones, including Turbo, accept and ignore these controls.

### Language

Set `language` to the language of `text`. If you omit it, the language is detected from `text`. Successful responses include `Content-Language`, the language the speech was generated in.

### Limits and request ID

The rate limit is 30 requests per minute per workspace member.

Successful responses include `X-Request-Id`. Use this ID when you contact support about the request.



# Generate Speech
Source: https://heygen-1fa696a7.mintlify.app/reference/generate-speech

/openapi/external-api.json post /v3/voices/speech
Synthesizes speech from text with a catalog voice and returns an audio URL, its duration and optional word timestamps. Omit engine to use the voice's saved default and settings, or set it per request; choose an ElevenLabs model with settings: {model_id: 'eleven_v4'}. Requests that omit engine use HeyGen Voice for most public catalog voices. Set engine: 'heygen_voice' to explicitly request HeyGen Voice, or 'starfish' for Starfish. The legacy 'orca' input remains accepted; response engine values retain 'orca' for compatibility. A professional HeyGen Voice clone is synthesized by POST /v3/models/audio/tts instead. HTTP 400: the saved default or explicit engine is unsupported, not allowed on your plan, or incompatible with the requested locale or language. HTTP 403 (ai_vendor_access_restricted): workspace vendor policy blocks ElevenLabs and all of its model variants.



# Generate Video from Proofread
Source: https://heygen-1fa696a7.mintlify.app/reference/generate-video-from-proofread

/openapi/external-api.json post /v3/video-translations/proofreads/{proofread_id}/generate
Starts final video generation using the approved subtitles from a proofread session.



# Generate Video from Template
Source: https://heygen-1fa696a7.mintlify.app/reference/generate-video-from-template

/openapi/external-api.json post /v3/templates/{template_id}
Generates a video from a template by filling its variables. Use `scene_ids` to select, reorder or repeat the template's existing scenes. Poll GET /v3/videos/{video_id} or use webhooks for completion. An idempotent replay returns the original response, not the video's current state.



# Get AI Clipping
Source: https://heygen-1fa696a7.mintlify.app/reference/get-ai-clipping

/openapi/external-api.json get /v3/ai-clipping/{job_id}
Returns the full job resource including produced clips, statuses, and presigned download URLs.



# Get an Audio Voice
Source: https://heygen-1fa696a7.mintlify.app/reference/get-an-audio-voice

/openapi/external-api.json get /v3/models/audio/voices/{voice_id}
Returns one model-backed audio voice, owned by the caller's workspace or public, and its current lifecycle state. `PENDING` covers queued and running work, `ACTIVE` is ready for inference, and `FAILED` is terminal. An instant voice is `ACTIVE` as soon as it can speak.



# Get Asset
Source: https://heygen-1fa696a7.mintlify.app/reference/get-asset

/openapi/external-api.json get /v3/assets/{asset_id}
Returns metadata for an asset in the caller's workspace — including owner, upload timestamp, file type, and a publicly accessible URL.



# Get Asset Batch
Source: https://heygen-1fa696a7.mintlify.app/reference/get-asset-batch

/openapi/external-api.json get /v3/assets/batches/{batch_id}
Returns batch aggregate status and one page of items with their ids and statuses. Item statuses are one of queued, processing, completed, or failed. The per-item id is returned as video_id (the batch read model is shared with the videos batch API); for asset batches it holds the asset_id.



# Get Avatar Group
Source: https://heygen-1fa696a7.mintlify.app/reference/get-avatar-group

/openapi/external-api.json get /v3/avatars/{group_id}
Returns details for a specific avatar group including name, gender, preview URLs, looks count, and training status.



# Get Avatar Look
Source: https://heygen-1fa696a7.mintlify.app/reference/get-avatar-look

/openapi/external-api.json get /v3/avatars/looks/{look_id}
Returns details for a specific avatar look including supported engines, preferred orientation, preview URLs, and training status.



# Get Brand Glossary
Source: https://heygen-1fa696a7.mintlify.app/reference/get-brand-glossary

/openapi/external-api.json get /v3/brand-glossaries/{brand_glossary_id}
Returns one brand glossary with its full term list. Pronunciations affect generated audio only, not captions. Translation rules (`do_not_translate_terms`, `forced_translations`) apply only to translation features; a list is omitted from the response when it is empty. Tone settings are not returned here.



# Get Brand Kit
Source: https://heygen-1fa696a7.mintlify.app/reference/get-brand-kit

/openapi/external-api.json get /v3/brand-kits/{brand_kit_id}
Returns one brand kit with its colors, logos and fonts and the role each plays. While status is `loading` these are provisional; poll every 2 to 5 seconds until status is `completed`.



# Get Current API Key
Source: https://heygen-1fa696a7.mintlify.app/reference/get-current-api-key

/openapi/external-api.json get /v3/api_keys/self
Returns non-secret metadata, expiration, and permission scopes for the API key used to authenticate this request. This endpoint accepts API-key authentication only and does not require the key to grant itself a permission scope.



# Get Current User
Source: https://heygen-1fa696a7.mintlify.app/reference/get-current-user

/openapi/external-api.json get /v3/users/me
Returns the authenticated user's profile, remaining credits or balance, and billing details.



# Get Filler Word Removal
Source: https://heygen-1fa696a7.mintlify.app/reference/get-filler-word-removal

/openapi/external-api.json get /v3/filler-word-removals/{filler_word_removal_id}
Returns the job resource: lifecycle status, progress, and — once completed — the presigned download URL of the cleaned video plus removal statistics (num_cuts, reduction_pct, durations).



# Get Folder
Source: https://heygen-1fa696a7.mintlify.app/reference/get-folder

/openapi/external-api.json get /v3/folders/{folder_id}
Returns one folder in your workspace, including one in the trash (`is_trash`). Use it to check that a stored `folder_id` still exists. Deleted folders and folders in other workspaces return 404.



# Get HeyGen Image
Source: https://heygen-1fa696a7.mintlify.app/reference/get-heygen-image

/openapi/external-api.json get /v3/models/images/{generation_id}
Return the generation job status and ordered images with fresh download URLs once the entire job completes.



# Get HeyGen Video
Source: https://heygen-1fa696a7.mintlify.app/reference/get-heygen-video

/openapi/external-api.json get /v3/models/videos/{video_id}
Returns a HeyGen Video generation: `pending`, `processing`, `completed`, `failed` or `cancelled`. Completed results include a fresh `video_url`, duration and dimensions; failed results include `failure_code` and `failure_message`. Poll again to refresh an expired URL.



# Get HyperFrames Render
Source: https://heygen-1fa696a7.mintlify.app/reference/get-hyperframes-render

/openapi/external-api.json get /v3/hyperframes/renders/{render_id}
Returns full details for a single HyperFrames render, including status and signed video_url when complete.



# Get Lipsync
Source: https://heygen-1fa696a7.mintlify.app/reference/get-lipsync

/openapi/external-api.json get /v3/lipsyncs/{lipsync_id}
Returns details for a lipsync job including status, video_url, caption_url, and failure info if applicable.



# Get Lipsync Batch
Source: https://heygen-1fa696a7.mintlify.app/reference/get-lipsync-batch

/openapi/external-api.json get /v3/lipsyncs/batches/{batch_id}
Returns batch aggregate status and one page of items with their ids and statuses. Item statuses are one of queued, processing, completed, or failed. The per-item id is returned as video_id (the batch read model is shared with the videos batch API).



# Get Proofread Session
Source: https://heygen-1fa696a7.mintlify.app/reference/get-proofread-session

/openapi/external-api.json get /v3/video-translations/proofreads/{proofread_id}
Returns the status and details of a proofread session.



# Get Session Resource
Source: https://heygen-1fa696a7.mintlify.app/reference/get-session-resource

/openapi/external-api.json get /v3/video-agents/{session_id}/resources/{resource_id}
Returns a single session resource (image, video, draft, avatar, voice, etc.) by its resource_id.



# Get Template
Source: https://heygen-1fa696a7.mintlify.app/reference/get-template

/openapi/external-api.json get /v3/templates/{template_id}
Returns template details including its variable schema (with current default values) and scenes. Variable defaults are returned in the same shape the generate request accepts, so a response can be edited and posted back. Only draft version 4 templates (the current editor format) are supported.



# Get Video
Source: https://heygen-1fa696a7.mintlify.app/reference/get-video

/openapi/external-api.json get /v3/videos/{video_id}
Returns details for a video including status, video_url, thumbnail_url, duration, and failure info if applicable.



# Get Video Agent Session
Source: https://heygen-1fa696a7.mintlify.app/reference/get-video-agent-session

/openapi/external-api.json get /v3/video-agents/{session_id}
Returns the current status, progress, video_id, and recent chat messages for a session.



# Get Video Batch
Source: https://heygen-1fa696a7.mintlify.app/reference/get-video-batch

/openapi/external-api.json get /v3/videos/batches/{batch_id}
Returns batch aggregate status and one page of items with their video ids and statuses. Item statuses are one of queued, processing, completed, or failed.



# Get Video Scenes
Source: https://heygen-1fa696a7.mintlify.app/reference/get-video-scenes

/openapi/external-api.json get /v3/videos/{video_id}/scenes
Returns a video's scenes as it stands now, with the `edit_version` to send when editing. Each scene has a `background`, placed `elements` and a `script`. Skip element types you do not recognize. Geometry, text content, animations and background music are not described. A video whose editor document is still being prepared returns `409 resource_not_ready`; retry after it advances.



# Get Video Translation
Source: https://heygen-1fa696a7.mintlify.app/reference/get-video-translation

/openapi/external-api.json get /v3/video-translations/{video_translation_id}
Returns details for a translation job including status, output language, video_url, and failure info if applicable.



# Get Video Translation Batch
Source: https://heygen-1fa696a7.mintlify.app/reference/get-video-translation-batch

/openapi/external-api.json get /v3/video-translations/batches/{batch_id}
Returns batch aggregate status and one page of items with their ids and statuses. Item statuses are one of queued, processing, completed, or failed. The per-item id is returned as video_id (the batch read model is shared with the videos batch API).



# Get Voice
Source: https://heygen-1fa696a7.mintlify.app/reference/get-voice

/openapi/external-api.json get /v3/voices/{voice_id}
Returns details for a specific voice, including clone workflow status when available. Use this to poll a voice clone until its status is 'complete'.



# List AI Clipping
Source: https://heygen-1fa696a7.mintlify.app/reference/list-ai-clipping

/openapi/external-api.json get /v3/ai-clipping
Returns a cursor-paginated list of AI clip jobs in the authenticated user's workspace, newest first.



# List Audio Voices
Source: https://heygen-1fa696a7.mintlify.app/reference/list-audio-voices

/openapi/external-api.json get /v3/models/audio/voices
Returns model-backed audio voices, ordered newest first. With the default `type=private`, these are the voices in the caller's workspace, professional and instant; `mode` tells them apart. With `type=public`, these are the voices HeyGen provides to every workspace. Use `limit` and `token` to retrieve additional pages.



# List Avatar Groups
Source: https://heygen-1fa696a7.mintlify.app/reference/list-avatar-groups

/openapi/external-api.json get /v3/avatars
Returns a paginated list of avatar groups (characters). Each group contains one or more looks. Filterable by ownership.



# List Avatar Looks
Source: https://heygen-1fa696a7.mintlify.app/reference/list-avatar-looks

/openapi/external-api.json get /v3/avatars/looks
Returns a paginated list of avatar looks (outfits, poses, styles). Filterable by group_id, avatar_type, and ownership. The look id is the avatar_id to pass when creating a video.



# List Brand Glossaries
Source: https://heygen-1fa696a7.mintlify.app/reference/list-brand-glossaries

/openapi/external-api.json get /v3/brand-glossaries
Lists the brand glossaries in your workspace. A glossary sets how terms are pronounced in generated speech and how they are handled in translation. Pass a `brand_glossary_id` when creating a video or translation to apply it.



# List Brand Kits
Source: https://heygen-1fa696a7.mintlify.app/reference/list-brand-kits

/openapi/external-api.json get /v3/brand-kits
Returns brand kits available in the authenticated user's workspace. Each brand kit contains colors, fonts, and logos that can be applied to Video Agent sessions. Use the returned brand_kit_id with POST /v3/video-agents to generate on-brand videos.



# List HyperFrames Renders
Source: https://heygen-1fa696a7.mintlify.app/reference/list-hyperframes-renders

/openapi/external-api.json get /v3/hyperframes/renders
Returns a cursor-paginated list of HyperFrames renders in the account, newest first.



# List Lipsyncs
Source: https://heygen-1fa696a7.mintlify.app/reference/list-lipsyncs

/openapi/external-api.json get /v3/lipsyncs
Returns a paginated list of all lipsync jobs in the account.



# List Look Templates
Source: https://heygen-1fa696a7.mintlify.app/reference/list-look-templates

/openapi/external-api.json get /v3/avatars/look-templates
Lists the look templates and Look Packs your workspace can apply with POST /v3/avatars/looks. Send an item's `id` as `template_id` and its `type` as `type`. Filter by `gender` to match your avatar.



# List Proofread Sessions
Source: https://heygen-1fa696a7.mintlify.app/reference/list-proofread-sessions

/openapi/external-api.json get /v3/video-translations/proofreads
Returns a paginated list of all proofread sessions in the workspace, newest first.



# List Session Videos
Source: https://heygen-1fa696a7.mintlify.app/reference/list-session-videos

/openapi/external-api.json get /v3/video-agents/{session_id}/videos
Returns all videos produced within a Video Agent session, sorted newest-first.



# List Supported Translation Languages
Source: https://heygen-1fa696a7.mintlify.app/reference/list-supported-translation-languages

/openapi/external-api.json get /v3/video-translations/languages
Returns all supported target language names for video translation.



# List Templates
Source: https://heygen-1fa696a7.mintlify.app/reference/list-templates

/openapi/external-api.json get /v3/templates
Returns a paginated list of API-ready templates in the workspace. Templates are created and edited in the HeyGen web editor; only templates with variables defined are listed.



# List Video Agent Sessions
Source: https://heygen-1fa696a7.mintlify.app/reference/list-video-agent-sessions

/openapi/external-api.json get /v3/video-agents
Returns a paginated list of video agent sessions for the authenticated user, sorted newest-first.



# List Video Agent Styles
Source: https://heygen-1fa696a7.mintlify.app/reference/list-video-agent-styles

/openapi/external-api.json get /v3/video-agents/styles
Returns curated visual style templates available for Video Agent sessions. Each style controls scene composition, pacing, and aesthetics. Supports tag filtering (e.g. 'cinematic', 'retro-tech').



# List Video Translations
Source: https://heygen-1fa696a7.mintlify.app/reference/list-video-translations

/openapi/external-api.json get /v3/video-translations
Returns a paginated list of all video translation jobs in the account.



# List Videos
Source: https://heygen-1fa696a7.mintlify.app/reference/list-videos

/openapi/external-api.json get /v3/videos
Returns a paginated list of all videos in the account. Filterable by folder_id or title substring.



# List Voices
Source: https://heygen-1fa696a7.mintlify.app/reference/list-voices

/openapi/external-api.json get /v3/voices
Returns a paginated list of voices, filterable by type, engine, language, and gender. Speech generation supports Starfish, HeyGen Voice, and ElevenLabs. Each voice includes its speech default and available speech engines.



# List Webhook Endpoints
Source: https://heygen-1fa696a7.mintlify.app/reference/list-webhook-endpoints

/openapi/external-api.json get /v3/webhooks/endpoints
Returns a paginated list of registered webhook endpoints.



# List Webhook Event Types
Source: https://heygen-1fa696a7.mintlify.app/reference/list-webhook-event-types

/openapi/external-api.json get /v3/webhooks/event-types
Returns all available webhook event types with human-readable descriptions.



# List Webhook Events
Source: https://heygen-1fa696a7.mintlify.app/reference/list-webhook-events

/openapi/external-api.json get /v3/webhooks/events
Returns a paginated history of delivered webhook events. Filterable by event_type or entity_id.



# Rotate Webhook Signing Secret
Source: https://heygen-1fa696a7.mintlify.app/reference/rotate-webhook-signing-secret

/openapi/external-api.json post /v3/webhooks/endpoints/{endpoint_id}/rotate-secret
Generates a new signing secret for a webhook endpoint and immediately invalidates the old one. Store the new secret securely — it will not be shown again.



# Search audio (music or sound effects)
Source: https://heygen-1fa696a7.mintlify.app/reference/search-audio-music-or-sound-effects

/openapi/external-api.json get /v3/audio/sounds
Searches the music or sound-effects catalog by natural-language description (`type=music` by default, or `sound_effects`). Returns tracks ranked by similarity, each with a download URL, paginated by cursor.



# Send Video Agent Message
Source: https://heygen-1fa696a7.mintlify.app/reference/send-message-or-request-revision

/openapi/external-api.json post /v3/video-agents/{session_id}
Sends a follow-up turn to a session created in either `generate` or `chat` mode; follow-up turns preserve the session mode. Send a `message`, a scene `edit_plan` built from GET /v3/videos/{video_id}/scenes, or both. Items may reference different scene snapshots from this session; none identifies the output draft. `edit_version` is not a document lock, so two edits from one version may both be accepted. Returns the current working draft in `video_id`. Poll GET /v3/videos/{video_id} for status. For a failed video, inspect `failure_code` and `failure_message`; the session endpoint also exposes known stop reasons in `error`.



# Set Template Variables
Source: https://heygen-1fa696a7.mintlify.app/reference/set-template-variables

/openapi/external-api.json put /v3/templates/{template_id}/variables
Replaces a template's full set of variables: any variable you omit is removed. Media, character and voice variables bind to a node by `element_id`, listed under `composition` in GET /v3/templates/{template_id}. A text variable with `match` turns that text into a `{{name}}` placeholder.



# Stop Video Agent Session
Source: https://heygen-1fa696a7.mintlify.app/reference/stop-video-agent-session

/openapi/external-api.json post /v3/video-agents/{session_id}/stop
Halts an active agent run at its next checkpoint. Partial results are preserved.



# Stream Speech
Source: https://heygen-1fa696a7.mintlify.app/reference/stream-speech

/openapi/external-api.json post /v3/models/audio/tts/stream
Stream speech from the voice identified by `voice_id`.

The response sends base64 WAV parts as Server-Sent Events (SSE). Set `with_timestamps` to `true` to include alignment events. A successful stream ends with `data: [DONE]`.

### Voice and settings

Use an `ACTIVE` HeyGen Voice clone in your workspace. `heygen-voice-1-turbo` speaks instant clones at lower latency and refuses professional clones. API-key billing accumulates fractional usage. OAuth requests, including MCP calls, are rounded up per request to whole billing units, so their effective cost can be higher.

`seed`, `speed`, `pitch_shift`, and `pitch_variance` apply only to professional clones. Instant clones, including Turbo, accept and ignore these controls.

### Language

Set `language` to the language of `text`. If you omit it, the language is detected from `text`. Successful responses include `Content-Language`, the language the speech was generated in.

### Limits and request ID

The rate limit is 30 requests per minute per workspace member.

Successful responses include `X-Request-Id`. Use this ID when you contact support about the request.



# Update Avatar Group
Source: https://heygen-1fa696a7.mintlify.app/reference/update-avatar-group

/openapi/external-api.json patch /v3/avatars/{group_id}
Updates an avatar group you own. Currently sets `default_voice_id`, the voice this avatar uses by default; any voice in your workspace works, including clones. Public avatars cannot be updated.



# Update Avatar Look
Source: https://heygen-1fa696a7.mintlify.app/reference/update-avatar-look

/openapi/external-api.json patch /v3/avatars/looks/{look_id}
Updates the display name of an avatar look. Only supported for photo avatar and digital twin look types.



# Update Brand Glossary
Source: https://heygen-1fa696a7.mintlify.app/reference/update-brand-glossary

/openapi/external-api.json patch /v3/brand-glossaries/{brand_glossary_id}
Updates a brand glossary. A field you omit is left untouched, a list you send replaces the existing list in full, and an empty array removes every entry. A name already used in the workspace returns 409. Tone settings are never modified by this endpoint.



# Update Brand Kit
Source: https://heygen-1fa696a7.mintlify.app/reference/update-brand-kit

/openapi/external-api.json patch /v3/brand-kits/{brand_kit_id}
Updates a brand kit's name or role assignments: color roles, main logo, heading and body fonts. Omitted fields are unchanged and `null` is rejected. Each role object you send replaces the existing one in full; `{}` clears a role and it stays cleared. Role edits return 409 until the kit is `completed`; shared kits return 403.



# Update Lipsync
Source: https://heygen-1fa696a7.mintlify.app/reference/update-lipsync

/openapi/external-api.json patch /v3/lipsyncs/{lipsync_id}
Updates the display title of a lipsync job.



# Update Template
Source: https://heygen-1fa696a7.mintlify.app/reference/update-template

/openapi/external-api.json patch /v3/templates/{template_id}
Renames a template. Other properties are edited in the HeyGen editor or through PUT /v3/templates/{template_id}/variables. Returns the template detail.



# Update Video Translation
Source: https://heygen-1fa696a7.mintlify.app/reference/update-video-translation

/openapi/external-api.json patch /v3/video-translations/{video_translation_id}
Updates the display title of a video translation job.



# Update Webhook Endpoint
Source: https://heygen-1fa696a7.mintlify.app/reference/update-webhook-endpoint

/openapi/external-api.json patch /v3/webhooks/endpoints/{endpoint_id}
Updates the URL and/or subscribed event types for a webhook endpoint. The events array is fully replaced — include all types you want to keep.



# Upload Asset
Source: https://heygen-1fa696a7.mintlify.app/reference/upload-asset

/openapi/external-api.json post /v3/assets
Uploads a file (image, video, audio, PDF, or SRT subtitle) and returns an asset_id for use in other endpoints. Max 32 MB. Supported types: png, jpeg, mp4, webm, mp3, wav, pdf, srt.



# Upload Proofread SRT
Source: https://heygen-1fa696a7.mintlify.app/reference/upload-proofread-srt

/openapi/external-api.json put /v3/video-translations/proofreads/{proofread_id}/srt
Replaces the proofread subtitles with an edited SRT file.



# heygen-avatar
Source: https://heygen-1fa696a7.mintlify.app/skills/heygen-avatar

Create a persistent HeyGen avatar — a reusable face + voice identity for the agent, the user, or any named character. Prompt-based by default; photo upload for real-person digital twins.

<Info>
  **Skill:** `heygen-avatar` · **Invoke:** `/heygen-avatar [name_or_description]` · [Source](https://github.com/heygen-com/skills/tree/master/heygen-avatar)
</Info>

`heygen-avatar` creates and manages persistent HeyGen avatars — a reusable face + voice identity powered by HeyGen Avatar V. It handles identity extraction, avatar generation, voice selection, and saves everything to an `AVATAR-<NAME>.md` file so every downstream video reuses the same look and voice.

This is the **correct first step** when no avatar exists yet. It returns an `avatar_id` and `voice_id` you pass directly to [heygen-video](/skills/heygen-video).

## When to Use

* **Give the agent a face + voice** so it can present videos — *"bring yourself to life", "create your avatar", "design a presenter"*.
* **Put the user in videos** as themselves — *"create my avatar", "a digital twin of me", "I want my face in a video"*.
* **Build a named character** presenter — *"create an avatar called Cleo"*.
* **Establish identity before making videos** — run this, then chain into heygen-video.

<Note>
  **Not for:** generating videos (use [heygen-video](/skills/heygen-video)), translating videos (use [heygen-translate](/skills/heygen-translate)), or TTS-only tasks.
</Note>

## Creation Modes

Two creation types, two scoping modes — covering everything from agent personas to real-person twins.

<CardGroup>
  <Card title="Type A — From prompt (default)" icon="wand-magic-sparkles">
    AI-generated appearance from a text description. The default path for agents and named characters. `create_prompt_avatar(name, prompt, avatar_id?, avatar_group_id?)`.
  </Card>

  <Card title="Type B — From reference photo" icon="image">
    A real-person digital twin from an uploaded image (URL, asset\_id, or base64). Opt-in, for when the user wants photo realism. `create_photo_avatar(name, file, avatar_group_id?)`.
  </Card>
</CardGroup>

| Scoping mode | Behavior |
| - | - |
| **New character** (omit `avatar_id` / `avatar_group_id`) | Creates a brand-new character with its own group. |
| **New look** (prompt: pass a look's `avatar_id` · photo: include `avatar_group_id`) | Adds a variation — outfit, pose, orientation — to an existing character. The default for iteration. |

For prompt avatars, `avatar_id` (a look ID) is the visual reference that keeps the character's identity consistent — the new look saves to that avatar's group automatically. `avatar_group_id` only selects which group the result is saved to; it does not condition the generation. See [Prompt to Avatar](/docs/avatar-from-prompt) for the full behavior matrix.

<Tip>
  The **Group ID** is the stable character identity that never changes. Individual `look_id`s are ephemeral — always resolve them fresh from the group at runtime. AVATAR files store only the Group ID.
</Tip>

## Workflow

<Steps>
  <Step title="Who are we creating for?">
    Routes to **agent** (default), **user** (explicit "my"/"me"), or **named character**. Reads workspace `SOUL.md` / `IDENTITY.md` for the agent's identity before asking anything.
  </Step>

  <Step title="Identity extraction">
    Pulls appearance and voice traits from workspace files first; asks the user conversationally only for what's genuinely missing — one or two questions at a time, never a form.
  </Step>

  <Step title="Avatar creation">
    Builds the prompt (or uploads the photo), shows it to the user for approval, then calls the creation API. Identity traits map to HeyGen enums (age, gender, ethnicity, style, orientation, pose).
  </Step>

  <Step title="Voice">
    **Design** (describe the voice, get 3 semantic matches with audio previews) or **Browse** (filter the catalog by language + gender). Language-aware — matches the user's detected language. Waits for the user to pick.
  </Step>

  <Step title="Save & maintain aliases">
    Writes the `AVATAR-<NAME>.md` file with Group ID, Voice ID, and looks. Maintains `AVATAR-AGENT.md` / `AVATAR-USER.md` symlinks so consumer skills resolve identity generically.
  </Step>

  <Step title="Test (optional)">
    Generates a short greeting video in the user's language to preview the avatar in action.
  </Step>
</Steps>

## Identity Field Enums

When building a prompt avatar, identity traits map to these HeyGen enums:

| Field | Values |
| - | - |
| **age** | Young Adult · Early Middle Age · Late Middle Age · Senior · Unspecified |
| **gender** | Man · Woman · Unspecified |
| **ethnicity** | White · Black · Asian American · East Asian · South East Asian · South Asian · Middle Eastern · Pacific · Hispanic · Unspecified |
| **style** | Realistic · Pixar · Cinematic · Vintage · Noir · Cyberpunk · Unspecified |
| **orientation** | square · horizontal · vertical |
| **pose** | half\_body · close\_up · full\_body |

## The AVATAR File

Every avatar gets one `AVATAR-<NAME>.md` file at the workspace root — the single source of truth that consumer skills read.

```markdown theme={null}
# Avatar: <Name>

## Appearance
- Age / Gender / Ethnicity / Hair / Build / Features / Style

## Voice
- Tone / Accent / Energy / Think (one-line analogy)

## HeyGen
- Group ID: <stable character anchor — never changes>
- Voice ID / Voice Name / Voice Designed / Voice Seed
- Looks: landscape=<look_id>, portrait=<look_id>, square=<look_id>
- Last Synced: <ISO timestamp>
```

The top sections are portable natural language any platform can use; the HeyGen section is runtime config that skills read to make API calls.

## Example Prompts

| Prompt | What happens |
| - | - |
| *"Bring yourself to life — create your own avatar."* | Reads identity files, builds the agent's prompt avatar, designs a voice. |
| *"Create my avatar — I have a headshot. What look works for a founder intro?"* | Asks discovery questions, uploads the photo, recommends setting and tone. |
| *"Create an avatar called Cleo, a warm documentary narrator."* | Builds a named character with a matched voice. |
| *"Give me a new look — something more cinematic."* | Adds a look under the existing group (Mode 2), updates the AVATAR file. |

<Card title="View the full SKILL.md" icon="github" href="https://github.com/heygen-com/skills/blob/master/heygen-avatar/SKILL.md">
  Includes the complete workflow, reference docs for avatar creation, asset routing, and troubleshooting.
</Card>


# heygen-translate
Source: https://heygen-1fa696a7.mintlify.app/skills/heygen-translate

Translate and dub an existing video into 175+ languages with voice cloning and lip-sync. The presenter keeps their face, their voice is cloned, and lips re-sync to the new audio.

<Info>
  **Skill:** `heygen-translate` · **Invoke:** `/heygen-translate [video_url_or_path] [--to language]` · [Source](https://github.com/heygen-com/skills/tree/master/heygen-translate)
</Info>

`heygen-translate` localizes a finished video into 175+ languages. The presenter keeps their face, their voice is cloned into the target language, and their lips re-sync to the new audio — viewers see the same person speaking natively. You supply a source video and target languages; the engine handles transcription, translation, voice cloning, lip-sync, and optional burned-in captions.

This is **not** new-video generation. The performance, framing, and brand assets in the original are preserved — translation rides on top of what's already there.

## When to Use

* **Localize an existing video** — *"translate this to Spanish", "dub this into Japanese", "I need this in 10 languages for a launch"*.
* **Same presenter, another language** (not a new presenter — that's [heygen-video](/skills/heygen-video)).
* **Podcast / audio-only translation** — *"translate this podcast, keep my video"*.
* **High-stakes content** where you want to review/edit subtitles before final render (the proofreads workflow).

<Note>
  **Not for:** creating new videos from scratch (use [heygen-video](/skills/heygen-video) and write the script in the target language), avatar creation (use [heygen-avatar](/skills/heygen-avatar)), or text-only translation. Use this skill **only when a source video already exists**.
</Note>

## Workflow

Four phases. Discovery is the only place the skill asks questions; the rest is silent until delivery.

<Steps>
  <Step title="Discovery">
    Gathers the minimum: source video (URL, file path, or HeyGen asset\_id) and target language(s) — asked open-ended, no picker. Confirms speaker count, content type, captions, and duration flexibility with smart defaults.
  </Step>

  <Step title="Pre-flight (silent)">
    Validates the language string against the canonical list, routes the source (public URL passes through; local files upload, max 32 MB), and classifies the content into one of five profiles to set the right flags.
  </Step>

  <Step title="Submit + Poll (silent)">
    Submits one job per language (batchable), then background-polls — 30s for the first 3 min, then 60s. Most finish in 5–15 min; some take 30+. Surfaces only on completion, hard failure, or a stall.
  </Step>

  <Step title="Deliver">
    Posts one message per completed language with the video URL, duration, mode, and caption status. Delivers each as it finishes rather than waiting for the whole batch.
  </Step>
</Steps>

## Content Profiles

The skill picks one profile from the source and sets flags accordingly — you rarely need to specify:

| Profile | Use when | Key flags |
| - | - | - |
| **Talking head** (default) | One person to camera, clean audio | `precision`, speech enhancement, captions, dynamic duration |
| **Podcast / audio-only** | Static or absent visual | `translate_audio_only`, speech enhancement |
| **Music / high-soundtrack** | Background music interferes with speech | `disable_music_track`, speech enhancement |
| **Multi-speaker** | Two+ distinct speakers | Talking-head defaults + `speaker_num` (**required** — don't guess) |
| **Corporate / branded** | Brand voice, glossary discipline | Talking-head defaults + `brand_voice_id`; consider proofreads |

<Tip>
  **Always precision mode** unless the user explicitly asks for speed. **Always confirm speaker count** for non-obvious cases — wrong speaker count is the #1 quality killer, causing voices to bleed across speakers.
</Tip>

## Proofread Workflow

For high-stakes content, run a proofread session so the user can review and edit translated subtitles *before* the engine commits to a final render. Default **ON** for long videos (>3 min), corporate/branded content, high-stakes legal/medical/educational, and languages the user reads natively.

```
proofreads create → poll → fetch SRT → edit (glossary, register, names) →
upload edited SRT → generate final → poll → deliver
```

This gives you an editable SRT you can also use as a sidecar caption file — preferable to burned-in captions when you might want to restyle them later.

## What to Know Before Translating

<AccordionGroup>
  <Accordion title="Source quality is the ceiling" icon="video">
    Translation can't improve on the source. Muffled audio, fast cuts, heavy face occlusion, or low resolution all degrade lip-sync and voice quality. Warn the user upfront in Pre-flight — never after a bad result. Lip-sync is best on stable, front-facing, well-lit shots ≥720p with minimal cuts.
  </Accordion>

  <Accordion title="Locale pairs compress and expand" icon="arrows-left-right">
    en→zh, en→ja, en→ko run \~30% shorter; de→en, ja→en run longer; en→ar/he expand. Dynamic duration matters most for these — without it, en→zh sounds artificially slow. Regional variants matter too: Spanish (Spain) ≠ Spanish (Mexico); "Chinese (Mandarin, Simplified)" ≠ Cantonese ≠ Taiwanese Mandarin.
  </Accordion>

  <Accordion title="Formality and RTL" icon="language">
    Register-heavy languages (Japanese keigo, Korean honorifics, German Sie/du, Thai) default to neutral-formal — proofread if you need to match a conversational source. RTL languages (Arabic, Hebrew, Urdu, Persian) render captions right-to-left and can collide with source lower-thirds; consider audio-only or caption styling review.
  </Accordion>

  <Accordion title="Cost & time" icon="clock">
    Translations bill by source duration. A 5-min video × 5 languages = \~25 billable minutes, each rendering in 10–20 min. Surface source-minutes × language-count and an honest render-time range — don't quote dollar figures (they vary by plan).
  </Accordion>
</AccordionGroup>

## Example Prompts

| Prompt | What happens |
| - | - |
| *"Translate this video to Spanish: \[URL]"* | Single-language dub with voice clone + lip-sync. |
| *"Dub this launch video into French, German, and Japanese."* | Batch translation, one job per language, delivered as each completes. |
| *"Translate this podcast but keep my video."* | Audio-only mode — returns a translated MP3 track. |
| *"Localize this for our enterprise launch — I want to review the subtitles first."* | Proofread workflow with editable SRT before final render. |

<Card title="View the full SKILL.md" icon="github" href="https://github.com/heygen-com/skills/blob/master/heygen-translate/SKILL.md">
  Includes the full proofreads playbook, language-locale guide, asset routing, and failure-mode decoder.
</Card>


# heygen-video
Source: https://heygen-1fa696a7.mintlify.app/skills/heygen-video

Generate HeyGen presenter videos via the v3 Video Agent pipeline — handles Frame Check, prompt engineering, avatar resolution, and voice selection. Idea in, finished video out.

<Info>
  **Skill:** `heygen-video` · **Invoke:** `/heygen-video [topic_or_script] [--avatar avatar_id]` · [Source](https://github.com/heygen-com/skills/tree/master/heygen-video)
</Info>

`heygen-video` is a video *producer*, not a CLI wrapper. It takes an idea and guides it to a finished cut: Discovery → Script → Prompt Craft → Frame Check → Generate → Deliver. It runs entirely on the **v3 Video Agent pipeline** and handles the things that separate good output from bad — aspect-ratio correction, prompt engineering, avatar conflict detection, and voice matching.

It accepts an `avatar_id` from [heygen-avatar](/skills/heygen-avatar) for identity-first videos, or uses a stock presenter. Returns a video share URL plus a session URL for iteration.

<Warning>
  **v3 only.** Never call deprecated `POST /v2/video/generate`, `GET /v2/avatars`, or v1 endpoints directly. Raw HTTP skips Frame Check and prompt engineering and produces visibly worse videos. Route through MCP, the OpenClaw plugin, or the `heygen` CLI via this skill.
</Warning>

## When to Use

* **Any HeyGen video generation** — *"generate a HeyGen video", "make a talking-head video"*.
* **Personalized video messages** — outreach, team updates, announcements, pitches.
* **Presenter-led explainers, tutorials, product demos** with a human face.
* *"Make a video of me saying…", "send a video to my leads", "summarize this article as a 60-second explainer from my avatar"*.

<Note>
  **Not for:** avatar creation (use [heygen-avatar](/skills/heygen-avatar) first), cinematic b-roll without a presenter, translating videos (use [heygen-translate](/skills/heygen-translate)), or streaming avatars.
</Note>

## Pipeline

<Steps>
  <Step title="First Look — avatar check">
    Scans the workspace for `AVATAR-*.md` files. If found, pre-loads the avatar as a default. If none, runs heygen-avatar first. **Blocking gate:** verifies the avatar is trained (`preview_image_url` non-null) before proceeding — unready avatars fail silently.
  </Step>

  <Step title="Discovery">
    Conversationally gathers purpose, audience, duration, tone, distribution (landscape/portrait), assets, key message, visual style, avatar, and language. Asks one or two items at a time — never a 10-item form.
  </Step>

  <Step title="Script">
    Writes for the ear in the video's language, structured by type (Product Demo, Explainer, Tutorial, Sales Pitch, Announcement). Extracts literal on-screen text and adds the script-framing directive so Video Agent expands naturally instead of padding with silence.
  </Step>

  <Step title="Prompt Craft">
    Transforms the script into an optimized Video Agent prompt: narrator framing, duration signal, asset anchoring, tone calibration, media-type guidance, and a style block stacked at the end.
  </Step>

  <Step title="Frame Check">
    Resolves the look\_id fresh from the group\_id, inspects orientation and background, and appends framing/background correction notes so the avatar fits the target aspect ratio without black bars.
  </Step>

  <Step title="Generate & Deliver">
    Submits to the v3 Video Agent, polls silently (20–45 min typical), then delivers the video with a one-line summary and a HeyGen dashboard link for editing.
  </Step>
</Steps>

## Modes

The skill routes to a mode based on how much the user has already decided:

| Signal | Mode | Starts at |
| - | - | - |
| Vague idea ("make a video about X") | **Full Producer** | Discovery |
| Has a written prompt | **Enhanced Prompt** | Prompt Craft |
| "Just generate" / skip questions | **Quick Shot** | Generate |
| "Dry run" / "preview" | **Dry-Run** | Creative preview, no API call |

## Visual Styles

Two ways to control the look — combine them freely.

<CardGroup>
  <Card title="API Styles (style_id)" icon="palette">
    Curated templates. One parameter replaces all visual direction. Browse via `list_video_agent_styles(tag, limit)` — tags include `cinematic`, `retro-tech`, `iconic-artist`, `pop-culture`, `handmade`, `print`. Show thumbnails + previews before choosing.
  </Card>

  <Card title="Prompt Styles" icon="pen-ruler">
    Full manual control. Pick from 20 named styles (Soft Signal, Swiss Pulse, Deconstructed, Maximalist Type…) and paste a copy-paste STYLE block at the end of the prompt. Match mood first, content second.
  </Card>
</CardGroup>

<Tip>
  **Top performers across 40+ production videos:** Deconstructed (most reliable across topics), Swiss Pulse (data-heavy), Digital Grid (tech), Geometric Bold (elegant, versatile), Maximalist Type (high energy — use sparingly).
</Tip>

## Media Types

Video Agent supports three media types — be explicit or it guesses (often wrong):

| Use case | Best media type |
| - | - |
| Data, stats, brand elements, diagrams | **Motion Graphics** — animated text, charts, icons |
| Abstract concepts, custom scenarios | **AI-Generated** — for things stock can't cover |
| Real environments, human emotions | **Stock Media** — authentic footage |

## Critical Rules

* **When `avatar_id` is set, never describe the avatar's appearance in the prompt** — say "the selected presenter." Describing it is the #1 cause of avatar mismatch.
* **Always include the script-framing directive** so Video Agent expands the concept instead of padding with dead air.
* **Always end the prompt with a style block** — without one, visuals drift scene-to-scene.
* **Capture the `session_id` immediately** — the session URL `https://app.heygen.com/video-agent/{session_id}` can't be recovered later.

## Example Prompts

| Prompt | What happens |
| - | - |
| *"Make a 30-second cinematic founder intro of me. Ask what you need."* | Full pipeline: avatar → style recommendation → video. |
| *"Turn the key points from this PDF into a team update from my avatar: \[file]"* | PDF → script → presenter video. |
| *"Summarize this article as a 60-second explainer: \[URL]"* | Fetches content, extracts points, scripts, generates. |
| *"Make a 20-second outreach video to an investor — what should I include?"* | Guides the message, you approve the script, the avatar delivers it. |

<Card title="View the full SKILL.md" icon="github" href="https://github.com/heygen-com/skills/blob/master/heygen-video/SKILL.md">
  Includes the complete pipeline, all 20 style blocks, prompt-craft anatomy, motion vocabulary, and Frame Check correction matrix.
</Card>


# Install
Source: https://heygen-1fa696a7.mintlify.app/skills/install

Install HeyGen Skills into Claude Code, Cursor, Codex, Gemini CLI, and 12+ other agents — via gh skill install, ClawHub, or git clone — then set up authentication.

The repo ships three skills you can install independently: **heygen-avatar**, **heygen-video**, and **heygen-translate**. Most users want avatar + video together (they chain); install translate whenever you need to localize finished videos.

<Tip>
  **Fastest path — let the agent do it.** Paste this into your agent and it handles everything (clone, auth, verify, first video):

  ```text theme={null}
  Read https://raw.githubusercontent.com/heygen-com/skills/master/INSTALL_FOR_AGENTS.md
  and follow it. Ask me for any API keys you need.
  ```
</Tip>

## Step 1 — Install the Skills

<Tabs>
  <Tab title="gh skill install">
    Works across 12+ agents (Claude Code, Cursor, Codex, Gemini CLI, Copilot, Junie, Goose, OpenHands, Amp, Cline, OpenCode, Warp, and more). Requires [GitHub CLI](https://cli.github.com) v2.90+. Writes to the correct directory for your agent automatically.

    ```bash theme={null}
    gh skill install heygen-com/skills heygen-avatar
    gh skill install heygen-com/skills heygen-video
    gh skill install heygen-com/skills heygen-translate
    ```

    Project scope is the default. For user scope (every project on this machine), add `--scope user`. Pin to a release tag for reproducibility:

    ```bash theme={null}
    gh skill install heygen-com/skills heygen-avatar@v3.1.0 --pin
    ```
  </Tab>

  <Tab title="ClawHub">
    Installs all three skills to your agent's default skills directory:

    ```bash theme={null}
    clawhub install heygen-skills
    ```
  </Tab>

  <Tab title="OpenClaw plugin">
    For OpenClaw users who want bundled MCP support:

    ```bash theme={null}
    openclaw plugins install clawhub:@heygen/openclaw-plugin-heygen
    ```
  </Tab>

  <Tab title="Git clone">
    Clone into your agent's skills directory. The three skills are auto-discovered at `heygen-avatar/SKILL.md`, `heygen-video/SKILL.md`, and `heygen-translate/SKILL.md`.

    ```bash theme={null}
    # Claude Code
    git clone https://github.com/heygen-com/skills.git ~/.claude/skills/heygen-skills

    # OpenClaw
    git clone https://github.com/heygen-com/skills.git ~/.openclaw/skills/heygen-skills
    ```

    Not sure where your skills directory is? Ask your agent: *"Where is your skills directory?"*
  </Tab>
</Tabs>

## Step 2 — Set Up Authentication

Pick the transport that matches how you want to be billed. The skills auto-detect which to use.

<Tabs>
  <Tab title="CLI + API key (agents)">
    Recommended for agents, CI, and scripts. Get a key at [platform.heygen.com/api-keys](https://platform.heygen.com/api-keys), then install the CLI and set the key:

    ```bash theme={null}
    curl -fsSL https://static.heygen.ai/cli/install.sh | bash
    export HEYGEN_API_KEY=<your-key>
    ```

    Verify:

    ```bash theme={null}
    heygen --version
    heygen auth status
    ```

    To persist the key across sessions, add the `export` line to your shell profile (`~/.zshrc`, `~/.bashrc`), or run `heygen auth login` to store it at `~/.heygen/credentials`. If `HEYGEN_API_KEY` is set, the skills use the CLI — no MCP probing.
  </Tab>

  <Tab title="MCP + OAuth (no API key)">
    Zero-setup if you're already on a HeyGen plan with credits. Connect the remote MCP server and the skills auto-detect it when no `HEYGEN_API_KEY` is set.

    ```bash theme={null}
    # Claude Code
    claude mcp add --transport http heygen https://mcp.heygen.com/mcp/v1/
    ```

    The first call triggers an OAuth consent flow in your browser. Calls run against your existing plan credits. See the [MCP setup guides](/mcp/overview) for per-agent instructions.
  </Tab>
</Tabs>

<Note>
  **Priority:** If `HEYGEN_API_KEY` is set, the skills use the CLI. Otherwise they look for MCP tools. Set the key only if you want direct API access; otherwise use MCP. The skills require **v3 only** — never v1 or v2 endpoints.
</Note>

## Step 3 — Create Your First Avatar and Video

With the skills installed and auth set, drive the full pipeline in two prompts:

<Steps>
  <Step title="Create your avatar">
    Use the **heygen-avatar** skill — from a description (default) or a photo:

    ```text theme={null}
    Create my HeyGen avatar from this photo: [your photo]
    ```

    The skill creates a persistent digital twin with a voice and saves an `AVATAR-<NAME>.md` file for reuse.
  </Step>

  <Step title="Make a video">
    Use the **heygen-video** skill — it picks up the avatar automatically:

    ```text theme={null}
    Make a 30-60 second video of me introducing myself, casual tone.
    ```

    The skill writes a script, runs the v3 Video Agent pipeline, and returns a share link.
  </Step>

  <Step title="(Optional) Localize it">
    Use the **heygen-translate** skill on any finished video:

    ```text theme={null}
    Translate that video into Spanish and Japanese.
    ```
  </Step>
</Steps>

That's it — the avatar persists, so every future video reuses it automatically.

## Requirements

* A HeyGen account — sign in via MCP (OAuth) or with an [API key](https://platform.heygen.com/api-keys) for the CLI.
* An AI agent that supports skills (Claude Code, OpenClaw, Codex, Cursor, or similar).
* No runtime dependencies, packages, or build step.

<Card title="Full install reference" icon="github" href="https://github.com/heygen-com/skills/blob/master/INSTALL.md">
  Pinning, scopes, and per-agent paths are documented in the repo's INSTALL.md.
</Card>


# Overview
Source: https://heygen-1fa696a7.mintlify.app/skills/overview

HeyGen Skills give any AI agent a face, a voice, and the ability to create, translate, and deliver video. Three composable skills — avatar, video, and translation — that work standalone or chain together.

**HeyGen Skills** are open-source [agent skills](https://github.com/heygen-com/skills) that teach Claude Code, Cursor, Codex, Gemini CLI, and other AI agents how to drive HeyGen end-to-end. Your agent gets a face, a voice, and the ability to send video like a message — no glue code, no API wrangling.

Each skill is a `SKILL.md` instruction file plus reference docs. The agent loads it on demand, follows the embedded workflow, and calls HeyGen through the [MCP server](/mcp/overview) or the [CLI](/cli). You get production-grade output (correct aspect ratios, prompt engineering, voice matching) without writing the pipeline yourself.

<Info>
  Skills are the agent-native layer on top of HeyGen. The [MCP server](/mcp/overview) and [CLI](/cli) expose the *tools*; skills encode the *expertise* for using them well.
</Info>

## The Three Skills

<CardGroup>
  <Card title="heygen-avatar" icon="user" href="/skills/heygen-avatar">
    Turn a photo or description into a persistent digital twin — a reusable face + voice identity for the agent, the user, or any named character.
  </Card>

  <Card title="heygen-video" icon="clapperboard" href="/skills/heygen-video">
    Turn an idea into a scripted, prompt-engineered presenter video with your avatar delivering the message. Built on the v3 Video Agent pipeline.
  </Card>

  <Card title="heygen-translate" icon="language" href="/skills/heygen-translate">
    Localize a finished video into 175+ languages with voice cloning and lip-sync. The presenter keeps their face; their voice speaks natively.
  </Card>
</CardGroup>

## How They Chain

The skills are standalone but compose into a full pipeline. They communicate through human-readable `AVATAR-<NAME>.md` files at your workspace root: **heygen-avatar** writes them, **heygen-video** reads them.

```
Photo / Description          Avatar File              Finished Video           Localized Video
       │                        │                         │                         │
  heygen-avatar     →     AVATAR-NAME.md      →      heygen-video      →     heygen-translate
  (identity + voice)      (reusable state)           (script + video)        (175+ languages)
```

A single request like *"Create my avatar and make a 30-second founder intro"* runs **heygen-avatar** first (identity → avatar ready), then hands the `avatar_id` and `voice_id` to **heygen-video**. **heygen-translate** rides on top of any finished video whenever you need to localize it.

| Skill | What it does | Invoke | Returns |
| - | - | - | - |
| **heygen-avatar** | Photo/description → persistent digital twin (face + voice) | `/heygen-avatar` | `avatar_id` + `voice_id` |
| **heygen-video** | Idea → script → prompt-engineered presenter video | `/heygen-video` | Video share URL + session URL |
| **heygen-translate** | Existing video → translated & dubbed version | `/heygen-translate` | Translated video URL per language |

## Authentication

Skills support two auth modes with an explicit priority order. The skill detects the mode silently at session start.

| Priority | Mode | Trigger | Billing | Best for |
| - | - | - | - | - |
| 1 | **CLI (API key)** | `HEYGEN_API_KEY` is set | Direct API usage (separately metered) | Agents, CI, scripts |
| 2 | **MCP (OAuth)** | MCP tools visible **and** no API key | Existing HeyGen plan credits | Users already on a HeyGen plan |
| 3 | **CLI (fallback)** | `heygen auth login` session | Direct API usage | Interactive CLI users |

<Note>
  **Billing tradeoff:** CLI mode bills against your HeyGen API usage. MCP mode consumes your existing HeyGen plan credits — no extra API billing. If `HEYGEN_API_KEY` is set, the CLI always wins.
</Note>

## Supported Agents

Skills install across 12+ agents via [`gh skill install`](/skills/install) — including Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, Junie, Goose, OpenHands, Amp, Cline, OpenCode, and Warp.

## Get Started

<CardGroup>
  <Card title="Install the skills" icon="download" href="/skills/install">
    Install across any agent with `gh skill install`, ClawHub, or git clone, then wire up auth.
  </Card>

  <Card title="Browse the source" icon="github" href="https://github.com/heygen-com/skills">
    Read the `SKILL.md` files and reference docs in the open-source repo.
  </Card>
</CardGroup>

<Tip>
  Want a zero-effort install? Paste this into your agent: *"Read [https://raw.githubusercontent.com/heygen-com/skills/master/INSTALL\_FOR\_AGENTS.md](https://raw.githubusercontent.com/heygen-com/skills/master/INSTALL_FOR_AGENTS.md) and follow it. Ask me for any API keys you need."* The agent clones the repo, sets up auth, runs a verify test, and ends with a working video.
</Tip>


# Sound effects
Source: https://heygen-1fa696a7.mintlify.app/sound-effects

Search HeyGen's sound-effects catalog with natural language and get ready-to-use, pre-signed audio URLs for your videos via the HeyGen API.

<img alt="" />

Find sound effects by describing the moment you're scoring — "whoosh for a scene change", "cash register cha-ching", "soft notification chime" — and get back ranked SFX, each with a pre-signed download URL. It's the same semantic search behind [background music](/background-music): set `type=sound_effects` on `GET /v3/audio/sounds` and describe what you want in plain language.

## Search the Catalog

Send a `GET` request to `/v3/audio/sounds` with a natural-language `query` and `type=sound_effects`:

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/audio/sounds?query=whoosh%20for%20a%20scene%20change&type=sound_effects&limit=3" \
  -H "x-api-key: YOUR_API_KEY"
```

```json Response theme={null}
{
  "data": [
    {
      "id": "7f2e91ac5b3d4e8f9a1c6d0b2e4f8a3c",
      "name": "Cinematic Whoosh: 7f2e91ac",
      "description": "Fast airy whoosh transition, ideal for scene changes and reveals.",
      "audio_url": "https://heygen-product.s3-accelerate.amazonaws.com/sound_effects/7f2e91ac...wav?X-Amz-Algorithm=...",
      "duration": 1.4,
      "score": 0.941,
      "type": "sound_effects"
    },
    {
      "id": "c4a8d2f1e6b9470a8d3e5f7c1a9b2d6e",
      "name": "Swipe Transition: c4a8d2f1",
      "description": "Quick swish swipe, light and modern, suited to UI motion and cuts.",
      "audio_url": "https://heygen-product.s3-accelerate.amazonaws.com/sound_effects/c4a8d2f1...wav?X-Amz-Algorithm=...",
      "duration": 0.9,
      "score": 0.902,
      "type": "sound_effects"
    }
  ],
  "has_more": true,
  "next_token": "eyJvZmZzZXQiOiAzLCAiX3R5cGUiOiAic291bmRfZWZmZWN0cyJ9"
}
```

## Query Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `query` | string | — | **Required.** Natural-language description of the sound you want, e.g. `cash register cha-ching`. Results are ranked by semantic similarity to this text. |
| `type` | string | `music` | Audio content type. Set to `sound_effects` to search the SFX catalog; `music` (the default) searches [background music](/background-music). |
| `limit` | integer | `10` | Maximum number of results to return (1–50). |
| `min_score` | number | `0.7` | Minimum semantic similarity score (0–1). Effects scoring below this are omitted. Raise it for tighter matches; lower it to widen the net. |
| `token` | string | — | Opaque pagination cursor. Pass the `next_token` from a prior response to fetch the next page. |

## Response Fields

| Field | Type | Description |
| - | - | - |
| `data[].id` | string | Stable identifier for the sound effect. |
| `data[].name` | string | Display name of the sound effect. |
| `data[].description` | string | Human-readable description of the sound and where it fits. |
| `data[].audio_url` | string | Pre-signed download URL for the audio file (WAV). |
| `data[].duration` | number | Length in seconds. Most effects are short — under a few seconds. |
| `data[].score` | number | Semantic similarity score (0–1) against your `query`. Results are returned highest-first. |
| `data[].type` | string | `sound_effects` for results from the SFX catalog. |
| `has_more` | boolean | `true` if more results are available beyond this page. |
| `next_token` | string | Cursor for the next page. Pass it as `token` on your next request. Absent when `has_more` is `false`. |

<Note>
  Each `audio_url` is a pre-signed link with a limited lifetime. Download the file (or hand the URL to a downstream step) soon after searching rather than caching it for later.
</Note>

## Paginate Through Results

When `has_more` is `true`, pass the returned `next_token` as the `token` parameter to fetch the next page:

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/audio/sounds?query=whoosh%20for%20a%20scene%20change&type=sound_effects&limit=3&token=eyJvZmZzZXQiOiAzLCAiX3R5cGUiOiAic291bmRfZWZmZWN0cyJ9" \
  -H "x-api-key: YOUR_API_KEY"
```

## Full Example

```python theme={null}
import requests
from urllib.parse import urlencode

API_KEY = "YOUR_API_KEY"
BASE = "https://api.heygen.com"
HEADERS = {"x-api-key": API_KEY}

def search_sound_effects(query, limit=10, min_score=0.7):
    """Yield every matching sound effect, following pagination."""
    token = None
    while True:
        params = {
            "query": query,
            "type": "sound_effects",
            "limit": limit,
            "min_score": min_score,
        }
        if token:
            params["token"] = token
        resp = requests.get(
            f"{BASE}/v3/audio/sounds?{urlencode(params)}",
            headers=HEADERS,
        )
        page = resp.json()
        for effect in page["data"]:
            yield effect
        if not page.get("has_more"):
            break
        token = page["next_token"]

# Grab the single best-matching effect
best = next(search_sound_effects("cash register cha-ching", limit=1))
print(f"{best['name']} ({best['duration']}s, score {best['score']:.2f})")
print(f"Download: {best['audio_url']}")
```

<Tip>
  If your integration validates the `type` field in responses against an enum, add `sound_effects` to it — the [changelog entry](/changelog) for this release has the full migration note.
</Tip>


# HeyGen Studio
Source: https://heygen-1fa696a7.mintlify.app/studio-videos

Compose avatar clips, images, and video footage into a single rendered video with one API call — HeyGen handles layout, timing, and the final export.

<img alt="" />

## Overview

A **studio video** is a single video composed from an ordered list of whole-frame scenes — avatar clips, still images, and existing video footage — concatenated in the order you send them. You describe the scenes; HeyGen owns the layout, derives each scene's duration, center-crops every scene to one global output canvas, and returns a single `video_id` for the finished MP4.

Create one by passing `"type": "studio"` to [`POST /v3/videos`](/reference/create-video) — the same endpoint that renders `avatar`, `image`, and `cinematic_avatar` videos:

```json theme={null}
{
  "type": "studio",
  "scenes": [ ... ]
}
```

Each scene is one of three types:

| Scene `type` | What it renders | Duration comes from |
| - | - | - |
| [`avatar_video`](#avatar-video-scenes) | An avatar or animated image speaking a script or audio track | The audio |
| [`image`](#image-scenes) | A still image, silent or narrated | `duration` (silent) or the audio (narrated) |
| [`video`](#video-scenes) | An existing video clip, silent or narrated | The clip itself (silent) or the voiceover (narrated) |

Rendering is all-or-nothing: one request produces one video, and every scene renders or none do. Output settings — aspect ratio, resolution, captions — are global, set once per request.

Each scene renders up to **30 minutes**. When a scene's duration comes from an audio track longer than that, split the audio and send it as consecutive scenes — see [Usage Limits](/docs/usage-limits#output-video-specifications).

<Note>
  Studio videos define their scenes **in the request**, which is ideal for programmatic composition. To render a reusable layout you've designed visually in HeyGen Studio, use a [HeyGen Studio Template](/templates) instead.
</Note>

## Quick Example

A three-scene video: a title card held for three seconds, an avatar delivering the message, and an existing clip as the outro.

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "studio",
    "title": "Product update — July",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "scenes": [
      {
        "type": "image",
        "source": { "type": "url", "url": "https://example.com/title-card.png" },
        "duration": 3
      },
      {
        "type": "avatar_video",
        "input": {
          "type": "avatar",
          "avatar_id": "YOUR_AVATAR_ID",
          "script": "Here is everything we shipped this month.",
          "voice_id": "YOUR_VOICE_ID",
          "background": { "type": "color", "color": "#0b1220" }
        }
      },
      {
        "type": "video",
        "source": { "type": "url", "url": "https://example.com/outro.mp4" },
        "playback": { "volume": 0.6 }
      }
    ]
  }'
```

```json Response theme={null}
{
  "data": {
    "video_id": "vid_9f2c..."
  }
}
```

Generation is asynchronous. Poll [`GET /v3/videos/{video_id}`](/reference/get-video) until `status` is `completed`, then read the download URL — or pass a `callback_url` to receive a [webhook](/docs/webhooks) when the video is ready.

## Request Body

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `type` | string | Yes | — | Must be `studio`. |
| `scenes` | array | Yes | — | Ordered list of whole-frame scenes to concatenate, `1`–`50`. Each is one of the [scene types](#scene-types) below. |
| `title` | string | No | — | Display title for the video in the HeyGen dashboard. |
| `aspect_ratio` | string | No | `16:9` | Global output aspect ratio: `16:9`, `9:16`, `4:5`, `5:4`, `1:1`, or `auto`. Every scene is rendered onto this one canvas — see [Scene framing](#scene-framing). |
| `resolution` | string | No | — | Global output resolution: `720p` or `1080p`. |

### Scene framing

A scene keeps its own shape inside the canvas rather than being cropped to fill it: where the two differ, the scene is scaled to fit and the remainder is padded. On a `1:1` canvas at `1080p`, an `avatar_video` scene from a 16:9 avatar renders as 1080x612 with padding above and below, and an `image` scene renders as a 608x1080 column with padding to either side.

Match `aspect_ratio` to the shape your scenes already are when you want an edge-to-edge frame.

\| `brand_glossary_id` | string | No | — | Brand glossary controlling how custom terms are pronounced — see [Brand Glossary](#brand-glossary). |
\| `caption` | object | No | — | Caption settings — see [Captions](#captions). |
\| `callback_url` | string | No | — | [Webhook](/docs/webhooks) URL to receive a POST notification when the video is ready. |
\| `callback_id` | string | No | — | Caller-defined identifier echoed back in the webhook payload. |
\| `watermark` | object | No | — | Custom watermark image overlay (PNG or JPEG). A premium option for select Enterprise customers — contact support to request access. |

The output container is MP4.

## Scene Types

Every scene fills the whole frame and carries a `type` discriminator that determines its remaining fields.

### Avatar Video Scenes

`"type": "avatar_video"` renders a speaking scene. Its `input` object has `"type": "avatar"` and references an avatar you already have by `avatar_id`. The scene's duration is derived from the audio.

Mirrors the standalone [avatar creation mode](/generate-avatar-video), minus the output settings — those are global on the studio request. Any avatar look works, exactly as in the standalone mode: **video avatars, studio avatars, and photo avatars**. To use a photo avatar (a "talking photo"), pass its look id as `avatar_id`.

```json theme={null}
{
  "type": "avatar_video",
  "input": {
    "type": "avatar",
    "avatar_id": "YOUR_AVATAR_ID",
    "script": "Welcome back.",
    "voice_id": "YOUR_VOICE_ID"
  }
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `type` | string | Yes | Must be `avatar`. |
| `avatar_id` | string | Yes | HeyGen avatar ID (video avatar or photo avatar look ID). |
| `script` | string | One audio source required | Text for the avatar to speak. Pair with `voice_id`, or omit `voice_id` to use the avatar's default voice. |
| `voice_id` | string | With `script` | Voice for text-to-speech. Browse with [`GET /v3/voices`](/reference/list-voices). Optional when the avatar has a default voice. |
| `audio_url` | string | One audio source required | Public URL of an audio file to lip-sync. |
| `audio_asset_id` | string | One audio source required | Asset ID of an uploaded audio file — see [Asset Management](/assets). |
| `voice_settings` | object | No | Voice tuning: `speed` (`0.5`–`1.5`), `pitch` (`-50`–`50` semitones), `volume` (`0.0`–`1.0`), `locale`. |
| `engine` | object | No | Generation engine — see [Choosing an engine](#choosing-an-engine). |
| `motion_prompt` | string | No | Natural-language prompt controlling body motion and hand gestures. Supported for photo avatars on either engine, and for video avatars on [Avatar V](/avatar-v). |
| `expressiveness` | string | No | Expressiveness level for photo avatars on [Avatar IV](/avatar-iv). Defaults to `low`. |
| `background` | object | No | Background composited behind the avatar: a solid color, an image, or a video. See [Scene backgrounds](#scene-backgrounds). |
| `remove_background` | boolean | No | Removes the avatar's own backdrop so `background` shows behind it. Video avatars must be trained with matting (the default for new digital twins). |

Provide exactly one audio source: `script` (with `voice_id` or a default voice), `audio_url`, or `audio_asset_id`.

<Note>
  To lip-sync your own photo, register it as a photo avatar first via the [photo-avatar API](/create-photo-avatar), then use its look id as `avatar_id` here. A studio scene references existing avatars; it does not animate a raw image inline.
</Note>

#### Choosing an engine

The `avatar` input accepts an optional `engine` object, defaulting to [Avatar IV](/avatar-iv) when omitted. Pass `{ "type": "avatar_v" }` for cross-reference-driven animation on [Avatar V](/avatar-v) — check `supported_api_engines` on the avatar look to confirm eligibility. On Avatar V you may also set `engine.reference_look_id` to a `digital_twin` look in the same avatar group to pin the animation reference; when omitted, video avatars self-reference and photo avatars pick an eligible look from the group. `expressiveness` applies on Avatar IV; `motion_prompt` applies to photo avatars on either engine and to video avatars on Avatar V.

<Note>
  Avatar V needs a usable reference look in the avatar's group, so it is not available for every photo avatar: if the group has none, the request fails with a `400`. A non-public `digital_twin` reference must also clear its group's consent requirements, whether you supplied it or it was selected for you. To see what a group already has, use [`GET /v3/avatars/looks?group_id=...&avatar_type=digital_twin`](/reference/list-avatar-looks) — the group id is the `group_id` field on any look in that group. Filtering by `avatar_type` alone searches your whole workspace and can return a digital twin from a different group, which is rejected. The listing shows candidates rather than guaranteeing eligibility: a non-public group needs [consent](/docs/avatar-consent). A look with `status: processing` (still training) can still be used as a reference.
</Note>

#### Scene backgrounds

`background` sets what appears behind the avatar in an `avatar_video` scene. Pass one of:

| `type` | Shape | Behavior |
| - | - | - |
| `color` | `{ "type": "color", "color": "#RRGGBB" }` | Solid color. |
| `image` | `{ "type": "image", "source": { ... } }` | Image scaled to cover the frame. |
| `video` | `{ "type": "video", "source": { ... } }` | Clip scaled to cover the frame, muted, and looped for the whole scene. |

`source` takes the same [asset input](#asset-input) as image and video scenes: a public URL or an uploaded `asset_id`.

Most avatars have their own backdrop in the footage or photo, and it fills the frame, so an image or video background stays hidden behind it. Set `remove_background: true` on the same input to cut the avatar out and show your background:

```json theme={null}
{
  "type": "avatar_video",
  "input": {
    "type": "avatar",
    "avatar_id": "YOUR_AVATAR_ID",
    "script": "Here is a quick look at the dashboard.",
    "voice_id": "YOUR_VOICE_ID",
    "remove_background": true,
    "background": {
      "type": "image",
      "source": { "type": "url", "url": "https://example.com/dashboard-screenshot.png" }
    }
  }
}
```

<Note>
  `remove_background` on a video avatar needs a look trained with matting, the default for recently created digital twins. Otherwise the request fails with a `400`: *"This video avatar does not support background removal. The avatar must have native alpha or be trained with matting enabled."* Photo avatars are supported.
</Note>

### Image Scenes

`"type": "image"` shows a still image in one of two modes — choose exactly one:

* **Silent** — set `duration` (seconds) and no audio source. The image holds on screen for that long.
* **Narrated** — set exactly one audio source and omit `duration`. The scene length follows the audio.

```json theme={null}
{
  "type": "image",
  "source": { "type": "url", "url": "https://example.com/chart.png" },
  "script": "Revenue grew forty percent quarter over quarter.",
  "voice_id": "YOUR_VOICE_ID"
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `type` | string | Yes | Must be `image`. |
| `source` | object | Yes | Still image to display — see [Asset input](#asset-input). |
| `duration` | number | Silent mode | Seconds to hold the image, up to `300`. |
| `script` | string | Narrated mode | Text to speak over the image. Pair with `voice_id`. |
| `voice_id` | string | With `script` | Voice for text-to-speech. |
| `audio_url` | string | Narrated mode | Public URL of an audio file to play over the image. |
| `audio_asset_id` | string | Narrated mode | Asset ID of an uploaded audio file. |
| `voice_settings` | object | No | Voice tuning (speed, pitch, locale). |

### Video Scenes

`"type": "video"` drops an existing clip into the sequence. Like an [image scene](#image-scenes), it plays in one of two modes:

* **Silent** — no audio source. The clip plays full-length at its own duration.
* **Narrated** — set exactly one voiceover source (the same audio inputs a narrated image scene accepts). The voiceover drives the scene's duration, and [`playback.mode`](#playback-and-scene-duration) controls how the clip fills that time — hold the last frame, loop, or adjust speed to fit.

```json theme={null}
{
  "type": "video",
  "source": { "type": "asset_id", "asset_id": "YOUR_ASSET_ID" },
  "script": "Here is the feature in action.",
  "voice_id": "YOUR_VOICE_ID",
  "playback": { "mode": "fit_to_scene", "mute": true }
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `type` | string | Yes | Must be `video`. |
| `source` | object | Yes | Video clip to include — see [Asset input](#asset-input). |
| `script` | string | Narrated mode | Voiceover text to speak over the clip. Pair with `voice_id`. |
| `voice_id` | string | With `script` | Voice for text-to-speech. Browse with [`GET /v3/voices`](/reference/list-voices). |
| `audio_url` | string | Narrated mode | Public URL of an audio file to play over the clip. |
| `audio_asset_id` | string | Narrated mode | Asset ID of an uploaded audio file — see [Asset Management](/assets). |
| `voice_settings` | object | No | Voice tuning (speed, pitch, locale) for a `script` voiceover. |
| `playback` | object | No | Scene-duration alignment and clip audio control — see [Playback and scene duration](#playback-and-scene-duration). Omit to hold the last frame (narrated) and keep the clip's source volume. |

In narrated mode, provide exactly one voiceover source: `script` (with `voice_id`), `audio_url`, or `audio_asset_id`.

#### Playback and scene duration

The `playback` object carries two composable controls: how the clip aligns to a voiceover-driven scene duration, and the clip's own audio level.

| Field | Type | Default | Description |
| - | - | - | - |
| `mode` | string | `freeze` | Narrated scenes only — how the clip fills the voiceover-driven duration. `freeze` plays the clip once and holds the last frame; `loop` repeats the clip; `fit_to_scene` adjusts playback speed so the clip ends exactly with the voiceover. |
| `volume` | number | `1.0` | Clip audio volume, `0.0`–`1.0`, where `1.0` is the source level. |
| `mute` | boolean | `false` | Force the clip silent regardless of `volume`. |

`mode` requires a voiceover, since the voiceover is what defines the target scene duration — a silent clip always plays full-length. The voiceover and the clip's own audio mix independently: there is no automatic ducking, so set `playback.volume` (or `mute`) yourself to bring the clip down under narration. With `fit_to_scene`, mute the clip when its source audio shouldn't be speed-adjusted along with the visuals.

## Asset input

The image/video scene `source` field, and the `source` of an image or video [scene background](#scene-backgrounds), take an asset object, discriminated by `type`. Provide one of:

| Form | Shape |
| - | - |
| Public URL | `{ "type": "url", "url": "https://..." }` |
| Uploaded asset | `{ "type": "asset_id", "asset_id": "..." }` — from [`POST /v3/assets`](/reference/upload-asset) (see [Asset Management](/assets)). |

Inline base64 is not accepted for scene sources or backgrounds and returns a `400`. Use a public URL, or upload the file with [`POST /v3/assets`](/reference/upload-asset) and pass its `asset_id`.

## Captions

Pass a `caption` object to generate captions across the full composed video. Captions are derived from the speech in [`avatar_video`](#avatar-video-scenes) scenes and narrated [`image`](#image-scenes) scenes. A sidecar subtitle file is always returned via `subtitle_url` in the chosen `file_format`; add `style` to additionally burn the captions into the rendered video — the sidecar is still delivered.

| Field | Type | Required | Default | Description |
| - | - | - | - | - |
| `file_format` | string | No | `srt` | Format of the sidecar caption file. |
| `style` | string | No | — | Visual style for burned-in captions: `default`. Omit for sidecar-only captions. |

## Brand Glossary

A [brand glossary](/docs/brand-glossary) is a set of custom pronunciations, for example speaking `HeyGen` as `hey-jen`. Glossaries are created and edited in the HeyGen web app under Brand Kit. Pass one with the top-level `brand_glossary_id`, a **global** setting that applies to the whole request.

```json theme={null}
{ "brand_glossary_id": "8c2d5e91a47b4f3c8d1e6a9b2f5c7d40" }
```

Find your ids with [`GET /v3/brand-glossaries`](/reference/list-brand-glossaries), and see which terms a glossary remaps with [`GET /v3/brand-glossaries/{brand_glossary_id}`](/reference/get-brand-glossary).

A glossary applies wherever HeyGen generates the speech: an `avatar_video` scene, or an `image` or `video` scene narrated with `script`. Scenes that supply finished audio (`audio_url` or `audio_asset_id`) play unchanged.

> A glossary changes the **spoken audio only**. Captions and the `.srt` sidecar keep the original spelling, so a term written `HeyGen` still reads `HeyGen` on screen while being spoken as `hey-jen`.

An id that does not exist in your workspace returns `400` and no video is created.

## Rendering at Scale

A studio request composes its scenes into a single video, so it is not accepted by the batch endpoint. A `"type": "studio"` item in [`POST /v3/videos/batches`](/reference/create-video-batch) is rejected. Send studio videos one per request to `POST /v3/videos` and track each returned `video_id`.


# HeyGen Studio Template
Source: https://heygen-1fa696a7.mintlify.app/templates

Find your HeyGen Studio templates and read each one's variable schema over the API, then fill the slots and render.

<img alt="" />

## Overview

A template is a video layout you build once in HeyGen Studio, with named slots for text, media, avatars, and voices. Use the API to find your templates, read what each one exposes, and generate videos from them:

* [`GET /v3/templates`](/reference/list-templates) — list the API-ready templates in your workspace.
* [`GET /v3/templates/{template_id}`](/reference/get-template) — read a template's variable schema (with current defaults) and its scenes.
* [`POST /v3/templates/{template_id}`](/reference/generate-video-from-template) — fill the variables and render a video.

<Note>
  Create templates in the HeyGen web editor ([HeyGen Studio](https://app.heygen.com/avatar/studio)), or over the API with [Create Studio Template via API](/create-template). The detail endpoint supports templates built in the **current editor format** (draft version 4).
</Note>

## List Templates

* Endpoint: `GET /v3/templates`
* Purpose: Return a paginated list of API-ready templates in the workspace.

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/templates?limit=100" \
  -H "x-api-key: YOUR_API_KEY"
```

```json Response theme={null}
{
  "data": {
    "templates": [
      {
        "id": "77e650952c024c6188a35e23e7088617",
        "name": "Quarterly Update",
        "thumbnail_url": "https://.../thumb.png",
        "aspect_ratio": "16:9",
        "created_at": 1711929600,
        "updated_at": 1711929600
      }
    ],
    "has_more": false,
    "next_token": null
  }
}
```

### Query Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `limit` | integer | No | `100` | Templates per page, `1`–`100`. |
| `token` | string | No | — | Opaque pagination cursor from a previous response's `next_token`. |

## Get a Template

* Endpoint: `GET /v3/templates/{template_id}`
* Purpose: Return template details including its variable schema (with current default values) and scene list.

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/templates/77e650952c024c6188a35e23e7088617" \
  -H "x-api-key: YOUR_API_KEY"
```

```json Response theme={null}
{
  "data": {
    "id": "77e650952c024c6188a35e23e7088617",
    "name": "Quarterly Update",
    "aspect_ratio": "16:9",
    "variables": {
      "headline": {
        "type": "text",
        "content": "Q3 in review"
      },
      "cover_image": {
        "type": "image",
        "asset": { "type": "url", "url": "https://.../cover.png" },
        "fit": "cover"
      }
    },
    "scenes": [
      {
        "scene_id": "scene_1",
        "script": "Welcome to the {{headline}} update.",
        "variables": [
          { "name": "headline", "variable_type": "text" }
        ]
      }
    ]
  }
}
```

The `variables` object is keyed by variable name, and each value is returned **in the same shape a generate request accepts** — so you can take this response, replace the default values with your own, and submit it back to render a video. The `content`, `asset`, and other fields hold the template's current defaults; a `text` variable may come back empty when the template leaves it unfilled.

### Variable Types

Every variable has a `type` discriminator that determines the rest of its fields:

#### `text`

| Field | Type | Required | Description |
| - | - | - | - |
| `content` | string | Yes | Replacement text, up to `10000` characters. May be empty in a GET response (an unfilled default); must be non-empty when generating. |

#### `image`

| Field | Type | Required | Default | Description |
| - | - | - | - | - |
| `asset` | object | Yes | — | Image to place — see [Asset input](#asset-input). |
| `fit` | string | No | `contain` | How the image fits the placeholder box: `cover`, `contain`, `crop`, or `none`. |

#### `video`

| Field | Type | Required | Default | Description |
| - | - | - | - | - |
| `asset` | object | Yes | — | Video to place — see [Asset input](#asset-input). |
| `fit` | string | No | `contain` | How the video fits the placeholder box: `cover`, `contain`, `crop`, or `none`. |
| `play_style` | string | No | `loop` | Playback when the video is shorter than the scene: `fit_to_scene`, `freeze`, `loop`, `once`, or `full_video`. |
| `volume` | number | No | `1.0` | Audio volume of the video track, `0.0` (muted) to `1.0`. |

#### `audio`

| Field | Type | Required | Description |
| - | - | - | - |
| `asset` | object | Yes | Audio to place — see [Asset input](#asset-input). |

#### `voice`

| Field | Type | Required | Description |
| - | - | - | - |
| `voice_id` | string | Yes | Voice used for text-to-speech. Browse with [`GET /v3/voices`](/reference/list-voices). |
| `locale` | string | No | Optional voice locale, e.g. `en-US`. |

#### `character`

| Field | Type | Required | Description |
| - | - | - | - |
| `avatar_id` | string | Yes | Avatar look ID to place; any avatar look, including talking photos. Same IDs as [`GET /v3/avatars/looks`](/reference/list-avatar-looks). Whether the look is an avatar or a talking photo is inferred from the look itself. |

Deprecated aliases, still accepted on input and returned alongside `avatar_id` until a published sunset: `avatar_look_id` and `character_id` (same value as `avatar_id`), and `character_type` (ignored on input; returned as the kind recorded on the template). Send `avatar_id`.

### Asset input

`image`, `video`, and `audio` variables take an `asset` object, discriminated by `type`. Provide one of:

| Form | Shape |
| - | - |
| Public URL | `{ "type": "url", "url": "https://..." }` |
| Uploaded asset | `{ "type": "asset_id", "asset_id": "..." }` — from [`POST /v3/assets`](/reference/upload-asset) (see [Upload Assets](/docs/upload-assets)). |
| Inline base64 | `{ "type": "base64", "media_type": "image/png", "data": "<base64>" }` |

### Scenes

`scenes` lists the template's scenes in order. Each has a `scene_id` (usable to restrict a render to a subset of scenes), the `script` text with variable placeholders left unreplaced, and the `variables` referenced in that scene.

Each scene renders up to **30 minutes**. A `script` or `audio` value that would drive a scene past that needs splitting across scenes in Studio — see [Usage Limits](/docs/usage-limits#output-video-specifications).

## Generate a Video

* Endpoint: `POST /v3/templates/{template_id}`
* Purpose: Render a video from the template, replacing its variables with the values you supply.

### Quick Example

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/templates/YOUR_TEMPLATE_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "headline": { "type": "text", "content": "Q3 in review" },
      "cover_image": {
        "type": "image",
        "asset": { "type": "url", "url": "https://example.com/cover.png" },
        "fit": "cover"
      }
    },
    "title": "Quarterly Update — Q3",
    "caption": false
  }'
```

```json Response theme={null}
{
  "data": {
    "video_id": "vid_9f2c..."
  }
}
```

Generation is asynchronous. Poll [`GET /v3/videos/{video_id}`](/reference/get-video) until `status` is `completed`, then read the download URL.

### Request Body

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `variables` | object | Yes | — | Replacements keyed by variable name, each following the per-type shapes in [Variable Types](#variable-types). Send every text variable: an omitted text variable is not filled with its default. Character, voice, image, video and audio variables can be omitted to keep their template values. |
| `title` | string | No | — | Title for the generated video. |
| `scene_ids` | array of strings | No | — | Scene IDs to render, in order — repeats allowed to duplicate a scene. Scenes must already exist in the template; the API can't create new ones. Omit to render every scene. |
| `dimension` | object | No | — | Output resolution override as `{ "width": ..., "height": ... }` (even, `128`–`4096`). Must keep the template's aspect ratio. |
| `fps` | number | No | `25` | Output frame rate: `25`, `30`, or `60`. |
| `caption` | boolean | No | `false` | Burn captions into the video. |
| `subtitles` | object | No | — | Subtitle style — see [Subtitle settings](#subtitle-settings). Supplying this implies captions. |
| `reorder_music` | boolean | No | `true` | When `true`, background-audio tracks move with their scenes; when `false`, they stay pinned to the original layout positions. |
| `keep_text_vertically_centered` | boolean | No | `false` | Re-center replaced text elements based on their rendered height. |
| `include_gif` | boolean | No | `false` | Include a GIF preview URL in the webhook payload. |
| `enable_sharing` | boolean | No | `false` | Make the generated video's share page publicly accessible. |
| `callback_url` | string | No | — | [Webhook](/docs/webhooks) URL called with the result, in addition to any registered endpoints. |
| `callback_id` | string | No | — | Opaque ID echoed back in webhook events for this video. |
| `folder_id` | string | No | — | Folder to place the generated video in. |
| `brand_glossary_id` | string | No | — | [Brand glossary](/docs/brand-glossary) controlling pronunciation of custom terms. Find ids with [`GET /v3/brand-glossaries`](/reference/list-brand-glossaries). |
| `brand_voice_id` | string | No | — | Deprecated. The former name for `brand_glossary_id`; both are accepted and resolve to the same glossary. |

### Subtitle settings

When you pass `subtitles`, `preset_name` is required; the rest override the preset.

| Field | Type | Required | Default | Description |
| - | - | - | - | - |
| `preset_name` | string | Yes | — | Subtitle preset, e.g. `classic`, `bold`, `bright`. |
| `alignment` | integer | No | `2` | Subtitle alignment. |
| `disable_highlight` | boolean | No | `false` | Override the preset's word-highlight style. |
| `font_size` | integer | No | — | Font-size override for the preset. |
| `position` | object | No | — | Position override as `{ "x": ..., "y": ... }`. |

## From template to video

The typical flow is three steps:

1. **Discover** — [`GET /v3/templates`](/reference/list-templates) to find the template and its `id`.
2. **Inspect** — [`GET /v3/templates/{template_id}`](/reference/get-template) to read the variable schema and defaults.
3. **Fill and generate** — replace the defaults in the `variables` object with your own values and `POST` them to [`POST /v3/templates/{template_id}`](/reference/generate-video-from-template), then poll [`GET /v3/videos/{video_id}`](/reference/get-video) for the result.


# Building a Studio Template
Source: https://heygen-1fa696a7.mintlify.app/templates-guide

Create a reusable template in HeyGen Studio, mark its script, voice, avatar, and background as variables, then fill those variables and render videos over the API.

## Overview

A template is a video you design once in HeyGen Studio and reuse by swapping in different values. You mark the parts you want to change per video, the script, the voice, the avatar, the background, as **variables**, give each one a name, then use the API to fill those variables and generate a new video for every set of values.

One idea ties Studio and the API together: **the name you give a variable in Studio is the exact key you send in the API.** Name a variable `name` in the editor, and you fill it with `"name": { ... }` in your request.

This guide walks the full loop: build the template in Studio, then drive it from the API.

<Tip>
  Want to create templates and mark their variables without opening Studio? See [Create Studio Template via API](/create-template).
</Tip>

<Note>
  For the complete variable-type schema (text, image, video, audio, voice, character), asset inputs, scenes, and every generate option, see the [Studio Template reference](/templates).
</Note>

## Prerequisites

* A HeyGen account with **Studio** access ([app.heygen.com](https://app.heygen.com/avatar/studio)).
* An **API key**.

## Part 1 — Build the template in Studio

You'll build a one-scene welcome video with four variables: the viewer's **name** (text), the **voiceover**, the **presenter** (avatar), and the **background**.

<Steps>
  <Step title="Open the template editor">
    In HeyGen Studio, create a new video (or open an existing one) and lay out your avatar, script, and background as usual. This layout is what every generated video will share.

    <Frame>
      <img alt="HeyGen Studio editor with an avatar on the canvas" />
    </Frame>
  </Step>

  <Step title="Turn script text into a variable">
    In the **Script** pane, wrap any word you want to change per video in double braces. Here the script is `Hi {{name}}, Welcome to HeyGen`, so `name` becomes a text variable you fill at generate time.

    <Frame>
      <img alt="Script with the name token typed as a variable" />
    </Frame>

    <Tip>The text between the braces is the variable name, and it is the exact key you send in the API.</Tip>
  </Step>

  <Step title="Make the voice a variable">
    Open the three-dots menu on the script and choose **API Variable**. Name it `voiceover` and click **Save**. The voice for the scene can now be set per request.

    <Frame>
      <img alt="Three-dots menu with API Variable, naming the voice variable voiceover" />
    </Frame>
  </Step>

  <Step title="Make the avatar a variable">
    Select the avatar on the canvas, then click the **API** button in the hover toolbar. Name it `presenter` and **Save**. You can now swap the avatar per video.

    <Frame>
      <img alt="Avatar selected with the API button, naming the character variable presenter" />
    </Frame>
  </Step>

  <Step title="Make the background a variable">
    Click the background directly (not the avatar), then click the **API** button in its toolbar. Name it `background` and **Save**. The scene background can now be set per request.

    <Frame>
      <img alt="Background selected with the API button, naming the image variable background" />
    </Frame>
  </Step>

  <Step title="Save the template">
    Click **Done Editing**. Your template is now API-ready and will appear in the templates list.

    <Frame>
      <img alt="Template saved successfully" />
    </Frame>
  </Step>
</Steps>

You now have a template with four named variables, `name`, `voiceover`, `presenter`, and `background`. Those names are exactly the keys you use next.

## Part 2 — Generate videos from the API

The flow is four calls: find the template, read its variables, fill them, then poll for the finished video.

<Steps>
  <Step title="Find your template">
    List the API-ready templates in your workspace and grab the `id` of the one you built.

    ```bash theme={null}
    curl -X GET "https://api.heygen.com/v3/templates?limit=10" \
      -H "x-api-key: YOUR_API_KEY"
    ```

    ```json Response theme={null}
    {
      "data": [
        {
          "id": "8ce3768236cd4e8a9ee8d88aad3537ae",
          "name": "DemoTemp",
          "thumbnail_url": "https://resource2.heygen.ai/image/.../original.png",
          "aspect_ratio": "16:9",
          "created_at": 1784323047,
          "updated_at": 1784323073
        }
      ],
      "has_more": false,
      "next_token": null
    }
    ```
  </Step>

  <Step title="Read the variable schema">
    Fetch the template to see the variables you named in Studio, with their types and current defaults.

    ```bash theme={null}
    curl -X GET "https://api.heygen.com/v3/templates/8ce3768236cd4e8a9ee8d88aad3537ae" \
      -H "x-api-key: YOUR_API_KEY"
    ```

    ```json Response theme={null}
    {
      "data": {
        "id": "8ce3768236cd4e8a9ee8d88aad3537ae",
        "name": "DemoTemp",
        "aspect_ratio": "16:9",
        "variables": {
          "name":       { "type": "text",      "content": "" },
          "voiceover":  { "type": "voice",     "voice_id": "330290724a1b470fb63153f34d4c0183" },
          "presenter":  { "type": "character", "avatar_id": "Annie_expressive5_public" },
          "background": { "type": "image",     "asset": { "type": "url", "url": "https://..." }, "fit": "none" }
        },
        "scenes": [
          {
            "scene_id": "BSueuHJY",
            "script": "Hi {{name}}, Welcome to HeyGen",
            "variables": [
              { "name": "name",       "variable_type": "text" },
              { "name": "voiceover",  "variable_type": "voice" },
              { "name": "presenter",  "variable_type": "character" },
              { "name": "background", "variable_type": "image" }
            ]
          }
        ]
      }
    }
    ```

    <Tip>Each variable comes back **in the same shape a generate request accepts**, so you can take this object, swap the values, and send it straight back.</Tip>
  </Step>

  <Step title="Fill the variables and generate">
    Send the variables keyed by the names you set in Studio. Here we personalize `name` to "Alex" and set a new background.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "https://api.heygen.com/v3/templates/8ce3768236cd4e8a9ee8d88aad3537ae" \
        -H "x-api-key: YOUR_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "title": "Welcome video for Alex",
          "variables": {
            "name":       { "type": "text",  "content": "Alex" },
            "voiceover":  { "type": "voice", "voice_id": "330290724a1b470fb63153f34d4c0183" },
            "presenter":  { "type": "character", "avatar_id": "Annie_expressive5_public" },
            "background": { "type": "image", "asset": { "type": "url", "url": "https://example.com/office.jpg" }, "fit": "cover" }
          }
        }'
      ```

      ```python Python theme={null}
      import requests

      resp = requests.post(
          "https://api.heygen.com/v3/templates/8ce3768236cd4e8a9ee8d88aad3537ae",
          headers={"x-api-key": "YOUR_API_KEY"},
          json={
              "title": "Welcome video for Alex",
              "variables": {
                  "name":       {"type": "text", "content": "Alex"},
                  "voiceover":  {"type": "voice", "voice_id": "330290724a1b470fb63153f34d4c0183"},
                  "presenter":  {"type": "character", "avatar_id": "Annie_expressive5_public"},
                  "background": {"type": "image", "asset": {"type": "url", "url": "https://example.com/office.jpg"}, "fit": "cover"},
              },
          },
      )
      video_id = resp.json()["data"]["id"]
      print(video_id)
      ```

      ```javascript Node theme={null}
      const res = await fetch(
        "https://api.heygen.com/v3/templates/8ce3768236cd4e8a9ee8d88aad3537ae",
        {
          method: "POST",
          headers: { "x-api-key": "YOUR_API_KEY", "Content-Type": "application/json" },
          body: JSON.stringify({
            title: "Welcome video for Alex",
            variables: {
              name:       { type: "text", content: "Alex" },
              voiceover:  { type: "voice", voice_id: "330290724a1b470fb63153f34d4c0183" },
              presenter:  { type: "character", avatar_id: "Annie_expressive5_public" },
              background: { type: "image", asset: { type: "url", url: "https://example.com/office.jpg" }, fit: "cover" },
            },
          }),
        }
      );
      const { data } = await res.json();
      console.log(data.id);
      ```
    </CodeGroup>

    ```json Response theme={null}
    {
      "data": {
        "id": "cb0009e7367b4a14b12981c4b6a85cb2",
        "status": "pending",
        "title": "Welcome video for Alex",
        "created_at": 1784325403
      }
    }
    ```

    <Note>Character, voice, image, video and audio variables you omit keep their template values. **Always send every text variable**: an omitted text variable is not filled with its default, and its placeholder name is spoken instead. Add `"test": true` to render a lower-quality test video with no credit charge while you wire things up.</Note>
  </Step>

  <Step title="Poll for the finished video">
    Generation is asynchronous. Poll the video by the `id` returned above until its `status` is `completed`, then read `video_url`.

    ```bash theme={null}
    curl -X GET "https://api.heygen.com/v3/videos/cb0009e7367b4a14b12981c4b6a85cb2" \
      -H "x-api-key: YOUR_API_KEY"
    ```

    ```json Response theme={null}
    {
      "data": {
        "id": "cb0009e7367b4a14b12981c4b6a85cb2",
        "status": "completed",
        "video_url": "https://files2.heygen.ai/.../cb0009e7....mp4",
        "duration": 2.03
      }
    }
    ```

    <Tip>Instead of polling, set a `callback_url` on the generate request to be notified when the video is ready. See [Webhooks](/docs/webhooks).</Tip>
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="My template isn't in the list">
    Only templates that have **at least one variable defined** appear in `GET /v3/templates`, and the detail endpoint supports templates built in the current editor (draft version 4). Make sure you marked and saved at least one variable in Studio.
  </Accordion>

  <Accordion title="I get an unknown-variable error">
    The keys in your `variables` object must match the variable names you set in Studio exactly (case-sensitive). Read `GET /v3/templates/{template_id}` to confirm the names.
  </Accordion>

  <Accordion title="A text variable comes back empty">
    A `text` variable can be empty in the schema (an unfilled default), but it must be non-empty when you generate.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Studio Template reference" href="/templates" icon="book">
    Every variable type, asset input, scenes, and generate options.
  </Card>

  <Card title="Webhooks" href="/docs/webhooks" icon="bell">
    Get notified when a video finishes instead of polling.
  </Card>
</CardGroup>


# Transparent Background Videos
Source: https://heygen-1fa696a7.mintlify.app/transparent-background-videos

Generate avatar videos with a transparent background (alpha channel) using the HeyGen API. Set output_format to webm to get a compositing-ready video with no background.

<img alt="" />

To get an avatar video with a transparent background, request the **WebM** output format on [`POST /v3/videos`](/reference/create-video). WebM carries an alpha channel; MP4 does not. This is the single most-missed setting — the default output is a standard MP4 with an opaque background, so if you don't ask for WebM you will never get transparency.

<Warning>
  **Your avatar must support matting.** Transparent output requires an avatar trained with matting (background separation) — the default for recently-created avatars, so most Digital Twins and Studio Avatars qualify. If an avatar doesn't support it, the WebM request is rejected with the error *"This video avatar does not support webm output. The avatar must be trained with matting enabled."* — if you hit it, use a more recently-created avatar.
</Warning>

## Prerequisites

<Check>
  An `avatar_id` for a matting-trained avatar — matting is the default for recently-created avatars. Use `GET /v3/avatars/looks` to browse your looks and copy an `id`.
</Check>

<Check>
  A `voice_id` for the voice you want. Use `GET /v3/voices` to browse available voices. (You can omit `voice_id` when using an `avatar_id` — the avatar's default voice is used.)
</Check>

## The one required switch: `output_format`

`output_format` accepts two values:

| Value | Result |
| - | - |
| `mp4` | **Default.** Standard video, opaque background. No alpha channel. |
| `webm` | Transparent background — a WebM file with an alpha channel, ready for compositing. |

Selecting `output_format: "webm"` does three things automatically:

1. Returns a WebM file with a real alpha channel.
2. Applies background removal for you — you do **not** need to set `remove_background`.
3. Rejects any `background` value in the same request (you can't both remove and set a background).

So the minimum change to turn a normal avatar video into a transparent one is adding a single field: `"output_format": "webm"`.

## Step 1 — Create the video

Send a `POST` to `/v3/videos` with `type: "avatar"`, your avatar and voice, and `output_format: "webm"`:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar",
    "avatar_id": "YOUR_AVATAR_LOOK_ID",
    "script": "Hi! This video has a transparent background, ready to drop onto any scene.",
    "voice_id": "YOUR_VOICE_ID",
    "title": "Transparent Background Demo",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "output_format": "webm"
  }'
```

<Note>
  `output_format: "webm"` already removes the background. Passing `"remove_background": true` alongside it is redundant but harmless. Do **not** also pass a `background` object — with WebM it is rejected.
</Note>

The response confirms the resolved format so you can verify WebM was accepted:

```json theme={null}
{
  "data": {
    "video_id": "v_abc123def456",
    "status": "waiting",
    "output_format": "webm"
  }
}
```

Copy `data.video_id` for the next step. If `data.output_format` comes back as `mp4`, your request did not select WebM — recheck the field name and value.

## Step 2 — Poll for completion

Video generation is asynchronous. Poll `GET /v3/videos/{video_id}` until `status` is `completed`:

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/videos/YOUR_VIDEO_ID" \
  -H "x-api-key: YOUR_API_KEY"
```

| Status | Meaning |
| - | - |
| `pending` | Queued for processing |
| `processing` | Video is being generated |
| `completed` | Ready — `video_url` points to the `.webm` file |
| `failed` | Something went wrong — check `failure_message` |

When `status` is `completed`, `data.video_url` is a presigned download link to your transparent WebM.

## Full example

```python theme={null}
import requests
import time

API_KEY = "YOUR_API_KEY"
BASE = "https://api.heygen.com"
HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}

# 1. Create a transparent-background video.
#    output_format="webm" is the ONLY switch you need — it also removes the background.
resp = requests.post(f"{BASE}/v3/videos", headers=HEADERS, json={
    "type": "avatar",
    "avatar_id": "YOUR_AVATAR_LOOK_ID",
    "script": "Hi! This video has a transparent background.",
    "voice_id": "YOUR_VOICE_ID",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "output_format": "webm",
})
data = resp.json()["data"]
video_id = data["video_id"]
assert data["output_format"] == "webm", "WebM was not selected — check your request"
print(f"Video created: {video_id}")

# 2. Poll until done.
while True:
    detail = requests.get(f"{BASE}/v3/videos/{video_id}", headers=HEADERS).json()["data"]
    print(f"Status: {detail['status']}")
    if detail["status"] == "completed":
        print(f"Transparent WebM: {detail['video_url']}")
        break
    if detail["status"] == "failed":
        print(f"Error: {detail.get('failure_message')}")
        break
    time.sleep(10)
```

## Why MP4 can't be transparent

MP4 (H.264/H.265) has no alpha channel — the container and codecs simply can't store per-pixel transparency. Any request that leaves `output_format` at its `mp4` default produces an opaque video, no matter what else you set. Transparency requires a format that supports alpha, which on this API is **WebM**. If you need a different alpha-capable container (for example MOV/ProRes 4444 for a video editor), render the WebM and transcode it locally.

## Common pitfalls

* **Left `output_format` at the default.** Omitting it gives you an opaque MP4. Add `"output_format": "webm"`.
* **Set `remove_background: true` but kept MP4.** Background removal without WebM does not give you a usable transparent file — MP4 can't carry the alpha channel. Use `output_format: "webm"` (which removes the background for you).
* **Used an avatar that wasn't trained with matting.** WebM requires a matting-enabled avatar; otherwise the request is rejected with a clear error. Matting is on by default for recently-created avatars — if you hit this, try a more recent avatar. See the warning at the top.
* **Passed a `background` object together with `webm`.** WebM removes the background and rejects any `background` value — send one or the other, not both.
* **Expected the file extension to change on its own.** The transparency comes from the WebM container returned in `video_url`, not from renaming an MP4.

## Avatar IV, Avatar V, and Avatar III

`output_format` is a top-level field on the create request, independent of the rendering engine, so transparent background works the same across all avatar engines:

* **Avatar IV** (the default engine when `engine` is omitted) — no change needed; just add `output_format: "webm"`.
* **Avatar V** — pass `"engine": {"type": "avatar_v"}` and `"output_format": "webm"` together. Transparency is set the same way.
* **Avatar III** — pass `"engine": {"type": "avatar_iii"}` and `"output_format": "webm"` together. Works with digital twin, studio avatar, and photo avatar looks alike.

<Note>
  Transparent output is **not** available for Cinematic Avatar (`type: "cinematic_avatar"`). That mode has no `output_format` field.
</Note>


# Get Current User
Source: https://heygen-1fa696a7.mintlify.app/user-profile

Retrieve the authenticated user's profile, credit balance, and plan tier from the HeyGen API. Useful for in-app credit displays and account-management UIs.

<img alt="" />

* Endpoint: `GET https://api.heygen.com/v3/users/me`
* Purpose: Returns the authenticated user's profile, remaining credits or balance, and billing details. Use this to check your account status or remaining quota before making API calls.

### Authentication

| Header | Value |
| - | - |
| `X-Api-Key` | Your HeyGen API key |

### Quick Example

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/users/me" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

### Response

```json theme={null}
{
  "data": {
    "username": "jane_doe",
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "billing_type": "wallet",
    "wallet": {
      "currency": "usd",
      "remaining_balance": 42.50,
      "auto_reload": {
        "enabled": false
      }
    },
    "subscription": null,
    "usage_based": null
  }
}
```

### Response Fields

| Field | Type | Description |
| - | - | - |
| `username` | string | Account username. |
| `email` | string or null | Account email. |
| `first_name` | string or null | First name. |
| `last_name` | string or null | Last name. |
| `billing_type` | string or null | Which billing object is populated: `"wallet"`, `"subscription"`, or `"usage_based"`. |

### Billing Types

The `billing_type` field tells you which of the three billing objects to read. Only one is populated at a time.

**Wallet** (`billing_type: "wallet"`) — Prepaid balance, typically for API key auth.

| Field | Type | Description |
| - | - | - |
| `wallet.currency` | string | `"usd"` or `"credits"` |
| `wallet.remaining_balance` | number or null | Current balance. |
| `wallet.auto_reload.enabled` | boolean | Whether auto-reload is on. |
| `wallet.auto_reload.threshold_usd` | number or null | Balance threshold that triggers reload. |
| `wallet.auto_reload.amount_usd` | number or null | Amount added on reload. |

**Subscription** (`billing_type: "subscription"`) — Per-pool credit balances for web-plan subscriptions.

| Field | Type | Description |
| - | - | - |
| `subscription.plan` | string | Plan tier: `"free"`, `"starter"`, `"creator"`, `"pro"`, `"team"`, `"enterprise"`, or `"business_plus"`. |
| `subscription.credits.premium_credits.remaining` | integer or null | Remaining premium credits. |
| `subscription.credits.premium_credits.resets_at` | string or null | When the credit pool resets. |
| `subscription.credits.add_on_credits.remaining` | integer or null | Remaining add-on credits. |

**Usage-based** (`billing_type: "usage_based"`) — Metered billing with optional spending cap.

| Field | Type | Description |
| - | - | - |
| `usage_based.spending_current_usd` | number or null | Current spend this period. |
| `usage_based.spending_cap_usd` | number or null | Spending cap (if set). |


# Video Details
Source: https://heygen-1fa696a7.mintlify.app/video-details

Read everything the API knows about a video you've created — delivery URLs, lifecycle timestamps, and the full scene-by-scene composition.

<img alt="" />

## Overview

Creating a video returns a `video_id`. Two endpoints read everything back from that id:

| Endpoint | Answers | Returns |
| - | - | - |
| [`GET /v3/videos/{video_id}`](/reference/get-video) | *What came out?* | Status, timestamps, and every deliverable: MP4, thumbnail, GIF, captioned variant, subtitles |
| [`GET /v3/videos/{video_id}/scenes`](/reference/get-video-scenes) | *What is it made of?* | The composition: backgrounds, avatars, clips, and the script each scene speaks |

The first is the endpoint you already poll after [creating a video](/reference/create-video) — it now returns far more than the status-and-URL pair it started with. The scenes endpoint is new.

## Video Details

```bash theme={null}
curl "https://api.heygen.com/v3/videos/{video_id}" \
  -H "x-api-key: YOUR_API_KEY"
```

```json Response theme={null}
{
  "data": {
    "id": "ca86dbcf9097461da11c42b1e4cd6efc",
    "title": "Field team FAQ — week one",
    "status": "completed",
    "created_at": 1787847881,
    "completed_at": 1787847968,
    "duration": 10.8669,
    "video_url": "https://files2.heygen.ai/.../ca86dbcf....mp4?Expires=...",
    "thumbnail_url": "https://files2.heygen.ai/.../ca86dbcf....jpeg?Expires=...",
    "gif_url": "https://resource2.heygen.ai/video/ca86dbcf.../gif.gif",
    "video_page_url": "https://app.heygen.com/videos/ca86dbcf9097461da11c42b1e4cd6efc"
  }
}
```

**Lifecycle**

* `status` — `pending` → `processing` → `completed` or `failed`
* `created_at`, `completed_at` — Unix timestamps; the difference is your render time
* `failure_code`, `failure_message` — on a failed video: branch on the code, log the message

**Deliverables** — up to five outputs on a completed video:

| Field | What it is |
| - | - |
| `video_url` | The rendered MP4 |
| `thumbnail_url` | Poster frame |
| `gif_url` | Animated preview — for hover states and embeds |
| `subtitle_url` | Sidecar subtitle file, when created with [captions](/studio-videos#captions) |
| `captioned_video_url` | Second MP4 with captions burned in — `video_url` stays clean |

**Placement**

* `title`, `folder_id` — where the video lives in your workspace
* `video_page_url` — deep link to the video in the HeyGen app
* `duration` — final length in seconds
* `output_language` — BCP-47 code; present only on [translated](/docs/video-translate) videos, which is also how you tell them apart

<Note>
  Media URLs are presigned and expire (the `Expires` parameter says when). Download what you need rather than storing the URLs — re-fetch the details for a fresh link at any time.
</Note>

Fields that don't apply are simply absent: a processing video has no `video_url` yet, and only a failed video carries failure fields.

## Video Scenes

[`GET /v3/videos/{video_id}/scenes`](/reference/get-video-scenes) opens the composition itself — for any video in your workspace, whichever surface created it: a [studio request](/studio-videos), a [template render](/templates), an [avatar video](/generate-avatar-video), or a video composed by hand in the editor. It describes the video **as it stands now**, including editor changes made after creation. When a [brand glossary](/docs/brand-glossary) shapes the video's speech, `video.brand_glossary_id` carries its id.

A video whose composition can't be read answers with an error rather than an empty document: `404` `video_not_found` when there is no editor document to read (some translated videos, for example), and `400` when the video predates the current editor format.

<img alt="Anatomy of the scenes response: video context plus a list of scenes, each with a background, elements, and script" />

```bash theme={null}
curl "https://api.heygen.com/v3/videos/{video_id}/scenes" \
  -H "x-api-key: YOUR_API_KEY"
```

```json Response theme={null}
{
  "data": {
    "video_id": "0d6116be51f3434e82d492db84535786",
    "video": {
      "title": "Orby Style Demo",
      "aspect_ratio": "16:9",
      "resolution": "1080p",
      "caption": { "enabled": false }
    },
    "scenes": [
      {
        "id": "42319b88-cfb8-4faa-8572-77391c78359f",
        "background": { "type": "color", "color": "#ffffff" },
        "elements": [
          {
            "id": "77448d08-499c-47c7-b542-adb2240711ba",
            "type": "avatar",
            "avatar_id": "Leos_standing_sofa_side",
            "engine": "avatar_v"
          },
          {
            "id": "a_roll_9cgnoo-design_element_kagzee-650f",
            "type": "motion_graphics"
          }
        ],
        "script": [
          {
            "id": "577c787f",
            "type": "text",
            "text": "Hi! I'm Orby. This is a quick test to show you your custom tech style in action.",
            "voice_id": "5d8c378ba8c3434586081a52ac368738",
            "voice_settings": { "speed": 1.0, "pitch": 0.0, "volume": 1.0 },
            "trim_to_speech": true
          }
        ]
      }
    ]
  }
}
```

### Roles, not kinds

A scene's three content fields split by the **role** a thing plays: `background` fills the frame, `elements` are placed within it, `script` is the audio over it.

<Warning>
  A whole-frame image or clip lands in `background` — code that only walks `elements` misses it.
</Warning>

A video background or video element reads back with the same playback controls a [studio scene](/studio-videos#playback-and-scene-duration) accepts: `playback` (`freeze` / `loop` / `fit_to_scene`), `trim`, `volume`, `speed_multiplier`.

### Reading elements

* **Every element appears** — the count is always truthful. `avatar`, `image`, and `video` are described in full; anything else is a placeholder with just an `id` and `type` (like `motion_graphics` above).
* **Skip unrecognized types** rather than erroring — the set is open and grows with the editor.
* **Recurse into containers** — a `group` or `mask` carries its children under `children`, each described like a top-level element.
* **Avatar elements report what a create request can set** — `avatar_id`, `engine`, `expressiveness`, `motion_prompt` — so what you read back is what you could send back. New fields are added additively.

### Reading scripts

| `type` | Content |
| - | - |
| `text` | Synthesized speech — verbatim script (inline markup included), `voice_id`, `voice_settings`, `trim_to_speech` |
| `audio` | Uploaded audio — `audio_url` |
| `silence` | Held silence — `duration` in seconds |

Walking `scenes[].script[].text` yields the full narration in playback order — for search indexing, compliance review, or driving a [translation](/docs/video-translate).

### Scope

* Asset URLs (`url`, `audio_url`) are returned when a live link exists at the time of the response; when the stored link has lapsed, the field is absent — the element itself is still reported. As with the deliverables above, download media you need rather than storing the URLs.
* The response is scoped to composition **content**. Visual styling — element geometry, text-element contents, animations, per-scene caption styling, background music — lives outside it, so a rebuild from this response reproduces the content and narration, not the pixel-exact layout.

## Putting the two together

<Steps>
  <Step title="Wait for the render">
    Poll [`GET /v3/videos/{video_id}`](/reference/get-video) until `status` is `completed` — or skip polling with a [webhook](/docs/webhooks).
  </Step>

  <Step title="Download the deliverables">
    Grab `video_url`, `subtitle_url`, and friends before their presigned links expire.
  </Step>

  <Step title="Index the composition">
    Call [`GET /v3/videos/{video_id}/scenes`](/reference/get-video-scenes) — scripts for search, avatar and voice ids for auditing, scene structure for your own UI.
  </Step>
</Steps>

Requesting an id that doesn't exist in your workspace returns `404` with code `video_not_found`, from either endpoint.