# AI clipping
Source: https://developers.heygen.com/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://developers.heygen.com/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 '{}'
```

The per-upload cap for this flow is 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": "..."}`). The 32 MB per-file limit applies to URL inputs too — 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.


# Automated Broadcast
Source: https://developers.heygen.com/automated-broadcast

Run scheduled video broadcasts - news roundups, daily briefings, market updates. The HeyGen API generates each clip on a cron schedule from fresh data inputs.

## The Problem

Publishing regular video content — daily news roundups, weekly company updates, recurring educational series — is unsustainable without a production team. But consistency is what builds an audience.

## How It Works

```
Schedule triggers → Aggregate content → LLM writes script → Video Agent renders → Auto-distribute
```

A fully automated pipeline that runs on a schedule, collects fresh content from your sources, generates a video, and delivers it to your audience — no human in the loop.

## Build It

<Steps>
  <Step title="Set up content aggregation">
    Pull content from whatever sources feed your broadcast.

    ```python theme={null}
    import requests
    from datetime import datetime

    def aggregate_content():
        stories = []

        # RSS feeds
        import feedparser
        feed = feedparser.parse("https://news.ycombinator.com/rss")
        for entry in feed.entries[:5]:
            stories.append({
                "title": entry.title,
                "summary": entry.get("summary", ""),
                "source": "Hacker News",
                "url": entry.link,
            })

        # APIs (example: your internal metrics)
        metrics = requests.get("https://api.yourapp.com/weekly-stats").json()
        stories.append({
            "title": f"This week: {metrics['new_users']} new users, {metrics['revenue']} revenue",
            "summary": f"Growth of {metrics['growth_pct']}% week over week",
            "source": "Internal",
        })

        return stories

    stories = aggregate_content()
    ```
  </Step>

  <Step title="Generate a video script with an LLM">
    ```python theme={null}
    import anthropic

    client = anthropic.Anthropic()

    story_text = "\n".join(
        f"- {s['title']} ({s['source']}): {s['summary']}"
        for s in stories
    )

    message = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1500,
        messages=[{
            "role": "user",
            "content": f"""Create a HeyGen Video Agent prompt for a 60-second
    news/update video.

    Date: {datetime.now().strftime('%B %d, %Y')}

    Stories to cover:
    {story_text}

    Structure:
    - Intro (5s): "Here's your [daily/weekly] update for [date]"
    - Stories (45s): Cover the top 3 stories with text overlays for key stats
    - Sign-off (10s): "That's your update. See you [tomorrow/next week]."

    Tone: Authoritative but approachable. Clean, news-desk style background.
    Keep pacing brisk — one story every 15 seconds."""
        }],
    )
    video_prompt = message.content[0].text
    ```
  </Step>

  <Step title="Generate the video">
    ```python theme={null}
    resp = requests.post(
        "https://api.heygen.com/v3/video-agents",
        headers={
            "X-Api-Key": HEYGEN_API_KEY,
            "Content-Type": "application/json",
        },
        json={"prompt": video_prompt},
    )
    video_id = resp.json()["data"]["video_id"]

    # Poll until complete
    import time
    while True:
        status = requests.get(
            f"https://api.heygen.com/v3/videos/{video_id}",
            headers={"X-Api-Key": HEYGEN_API_KEY},
        ).json()["data"]

        if status["status"] == "completed":
            video_url = status["video_url"]
            break
        elif status["status"] == "failed":
            raise Exception(f"Video failed: {status.get('failure_message')}")

        time.sleep(15)
    ```
  </Step>

  <Step title="Distribute automatically">
    Deliver the video to your audience wherever they are.

    ```python theme={null}
    # Telegram
    import telegram
    bot = telegram.Bot(token=TELEGRAM_TOKEN)
    bot.send_video(chat_id=CHANNEL_ID, video=video_url, caption="Daily Update")

    # Slack
    requests.post(SLACK_WEBHOOK, json={
        "text": f"Daily update is ready: {video_url}",
    })

    # Email (via your ESP)
    send_email(
        to=subscriber_list,
        subject=f"Your Daily Update — {datetime.now().strftime('%B %d')}",
        html=f'<a href="{video_url}"><img src="{thumbnail_url}"></a>',
    )
    ```
  </Step>

  <Step title="Schedule it">
    Run the pipeline on a schedule using cron, GitHub Actions, or a cloud function.

    ```yaml theme={null}
    # .github/workflows/daily-broadcast.yml
    name: Daily Video Broadcast
    on:
      schedule:
        - cron: '0 17 * * 1-5'  # 5 PM UTC, weekdays
    jobs:
      broadcast:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - run: pip install -r requirements.txt
          - run: python broadcast.py
            env:
              HEYGEN_API_KEY: ${{ secrets.HEYGEN_API_KEY }}
              ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
              TELEGRAM_TOKEN: ${{ secrets.TELEGRAM_TOKEN }}
    ```
  </Step>
</Steps>

## Real-World Example

STUDIO 47, a German broadcaster, reported these results after adopting HeyGen for automated video production (via [HeyGen customer stories](https://www.heygen.com/customer-stories/studio-47)):

* Significantly faster content creation
* 24/7 production capability
* Substantial cost reduction vs traditional production
* Expanded into multilingual content that wasn't feasible before

## Resilient Delivery

Build fallbacks for when things go wrong:

```python theme={null}
def deliver(video_url, caption):
    try:
        # Try primary: send video by URL
        bot.send_video(chat_id=CHANNEL_ID, video=video_url, caption=caption)
    except Exception:
        try:
            # Fallback: download and upload as file
            video_data = requests.get(video_url).content
            bot.send_video(chat_id=CHANNEL_ID, video=video_data, caption=caption)
        except Exception:
            # Last resort: send text with link
            bot.send_message(chat_id=CHANNEL_ID, text=f"{caption}\n\n{video_url}")
```

## Broadcast Types

| Type                  | Schedule       | Content source                   | Duration |
| --------------------- | -------------- | -------------------------------- | -------- |
| **Daily news**        | Every morning  | RSS, APIs, web scrape            | 45–60s   |
| **Weekly roundup**    | Monday morning | Internal metrics + industry news | 90s      |
| **Product changelog** | Each release   | Git commits, release notes       | 30–45s   |
| **Company all-hands** | Weekly/monthly | Meeting notes, updates           | 60–90s   |
| **Social digest**     | Daily          | Trending topics in your niche    | 30s      |

## Variations

* **Multi-language:** Generate once, [translate](/cookbook/video-agent/multilingual-content) for regional audiences
* **Different avatars per topic:** Use different presenters for different content categories
* **Audience segmentation:** Generate different versions for different subscriber segments

***

## Next Steps

<CardGroup>
  <Card title="Content Repurposing" icon="recycle" href="/cookbook/video-agent/content-repurposing">
    Repurpose existing content instead of aggregating new content.
  </Card>

  <Card title="Docs to Video" icon="file-lines" href="/cookbook/video-agent/docs-to-video">
    Trigger video generation from code changes instead of a schedule.
  </Card>
</CardGroup>


# Automated Video Pipeline
Source: https://developers.heygen.com/automated-pipeline

Build end-to-end automated video pipelines - data in, finished video out. HeyGen API integrates with your CMS, CRM, or data warehouse to render videos on demand.

## The Problem

You need to generate the same type of video repeatedly with different data — weekly reports, personalized onboarding videos, per-customer dashboards, changelog announcements. Doing this manually doesn't scale.

## How It Works

```
Data event → Template composition + injected data → Hyperframes render → Distribute
```

Hyperframes compositions are just HTML files. You can template them, inject data, and render programmatically — no browser, no human, no AI agent in the loop.

## Build It

<Steps>
  <Step title="Create a template composition">
    Build one great composition with your AI agent, then extract the variable parts:

    ```html theme={null}
    <!-- Template: weekly-report/index.html -->
    <div id="root" data-composition-id="main" data-start="0"
         data-duration="15" data-width="1920" data-height="1080">

      <div id="metric-1" class="clip" data-start="1" data-duration="4"
           data-track-index="2">
        <span class="value">{{ACTIVE_USERS}}</span>
        <span class="label">active users this week</span>
      </div>

      <div id="metric-2" class="clip" data-start="5" data-duration="4"
           data-track-index="2">
        <span class="value">{{REVENUE}}</span>
        <span class="label">revenue</span>
      </div>

      <!-- ... more metrics ... -->
    </div>
    ```
  </Step>

  <Step title="Build the generation script">
    ```python theme={null}
    import subprocess
    import shutil
    from pathlib import Path

    def generate_report_video(data: dict, output_path: str):
        """Generate a weekly report video from data."""

        # Copy template
        work_dir = Path(f"/tmp/report-{data['week']}")
        shutil.copytree("templates/weekly-report", work_dir, dirs_exist_ok=True)

        # Inject data into template
        html = (work_dir / "index.html").read_text()
        html = html.replace("{{ACTIVE_USERS}}", f"{data['active_users']:,}")
        html = html.replace("{{REVENUE}}", f"${data['revenue']:,.0f}")
        html = html.replace("{{GROWTH}}", f"{data['growth_pct']:.1f}%")
        (work_dir / "index.html").write_text(html)

        # Render
        subprocess.run([
            "npx", "hyperframes", "render",
            "--output", output_path,
            "--quality", "standard",
            "--fps", "30",
        ], cwd=str(work_dir), check=True)

        # Cleanup
        shutil.rmtree(work_dir)
        return output_path
    ```
  </Step>

  <Step title="Trigger from your pipeline">
    **GitHub Actions:**

    ```yaml theme={null}
    # .github/workflows/weekly-report.yml
    name: Weekly Report Video
    on:
      schedule:
        - cron: '0 9 * * 1'  # Every Monday at 9am

    jobs:
      generate:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - uses: actions/setup-node@v4
            with:
              node-version: '22'
          - run: sudo apt-get install -y ffmpeg
          - run: python scripts/generate_report.py
          - uses: actions/upload-artifact@v4
            with:
              name: weekly-report
              path: renders/*.mp4
    ```

    **Webhook-triggered:**

    ```python theme={null}
    from flask import Flask, request

    app = Flask(__name__)

    @app.route("/webhook/new-signup", methods=["POST"])
    def on_new_signup():
        user = request.json
        generate_welcome_video(
            name=user["name"],
            company=user["company"],
            output=f"renders/welcome-{user['id']}.mp4"
        )
        # Upload to CDN, send via email, etc.
        return {"status": "ok"}
    ```
  </Step>
</Steps>

## Pipeline Patterns

| Trigger           | Data source            | Output                      | Example                   |
| ----------------- | ---------------------- | --------------------------- | ------------------------- |
| **Cron schedule** | Database query         | Weekly/monthly report video | Monday metrics recap      |
| **Webhook**       | Event payload          | Per-user personalized video | Welcome onboarding        |
| **Git push**      | Changelog / commit log | Release announcement        | "What's new in v2.4"      |
| **API call**      | Request parameters     | On-demand custom video      | Customer dashboard export |

## Combine with Video Agent

For the best of both worlds — motion graphics + avatar narration:

```python theme={null}
def generate_narrated_report(data):
    # Step 1: Render the motion graphics with Hyperframes
    graphics_path = generate_report_video(data, "renders/graphics.mp4")

    # Step 2: Generate avatar narration with Video Agent
    narration = requests.post(
        "https://api.heygen.com/v3/video-agents",
        headers={"X-Api-Key": HEYGEN_API_KEY},
        json={
            "prompt": f"""Narrate this weekly report: {data['active_users']:,} active
            users (up {data['growth_pct']:.0f}%), ${data['revenue']:,.0f} revenue.
            Keep it under 15 seconds, upbeat and concise.""",
        },
    ).json()

    # Step 3: Composite in Hyperframes (avatar PiP over graphics)
    # ... or use ffmpeg to overlay
```

<Tip>
  Start simple — get one template working end-to-end, then add automation. A working pipeline that generates one video type reliably is more valuable than a complex system that handles everything.
</Tip>

***

## Next Steps

<CardGroup>
  <Card title="Data Visualization" icon="chart-bar" href="/cookbook/hyperframes/data-to-video">
    Build the animated visualizations that feed into your pipeline.
  </Card>

  <Card title="Docs to Video" icon="book" href="/cookbook/video-agent/docs-to-video">
    Similar automation pattern using Video Agent for avatar-based content.
  </Card>
</CardGroup>


# Avatar III
Source: https://developers.heygen.com/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 — same 4K support and the same [Digital Twin rate](/docs/pricing#video-generation-avatar-iii).

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}`. For pricing, see [Self-Serve Pricing](/docs/pricing#video-generation-avatar-iii) and [Enterprise Pricing](/docs/enterprise-pricing#video-generation-avatar-iii). To compare engines, see [Models](/models).


# Avatar IV
Source: https://developers.heygen.com/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 Realtime
Source: https://developers.heygen.com/avatar-realtime

Stream a HeyGen avatar that speaks in real time. Drive speech from a script, an audio file, or a live text stream at 720p.

<img alt="" />

Avatar Realtime opens a **live streaming session** where an avatar speaks in real time — useful for live agents, kiosks, and voice assistants with a face. You create a session, poll for the playback URL, and play it.

Avatar Realtime is **agent-agnostic**. Your application owns speech-to-text (STT) and the LLM — Avatar Realtime is only responsible for the face and voice. You stream text or audio to HeyGen, and HeyGen renders the avatar and publishes the video to an **HLS stream**. Because playback is plain HLS, there is no frontend dependency on LiveKit (or any other WebRTC stack): any HLS player can consume the output. This makes Avatar Realtime the right choice when you already have your own agent orchestration and just need to give it a talking face. If you want HeyGen to handle the full conversational loop — STT, LLM, and turn-taking — use [Live Avatar](/live-avatar) instead.

<Warning>
  Avatar Realtime streams at **720p only**.
</Warning>

## Create a session

[`POST /v3/avatar-realtime`](/reference/create-avatar-realtime-session) — choose how to drive speech with the `type` field:

* `tts` — speak a script (`avatar_id`, `voice_id`, `text`)
* `audio` — lip-sync to your own audio (`avatar_id`, `audio`)
* `text_stream` — stream text live, e.g. from an LLM (`avatar_id`, `voice_id`, `text`)

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/avatar-realtime" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "tts",
    "avatar_id": "Daisy-inskirt-20220818",
    "voice_id": "1bd001e7e50f421d891986aad5158bc8",
    "text": "Hi there — welcome to HeyGen Avatar Realtime."
  }'
```

```json Response theme={null}
{ "data": { "stream_id": "a1b2c3d4-..." } }
```

## Get the playback URL

`GET /v3/avatar-realtime/{stream_id}` — poll until the session is ready, then play the HLS `url` in any HLS player.

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

```json Response theme={null}
{ "data": { "stream_id": "a1b2c3d4-...", "status": "ready", "url": "https://.../stream.m3u8" } }
```

## Stream more text

For `text_stream` sessions, append text as it becomes available — the avatar keeps speaking on the open stream.

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/avatar-realtime/a1b2c3d4-.../text" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Here are the results I found." }'
```

## Limits

| Limit                         | Default | Notes                                                     |
| ----------------------------- | ------- | --------------------------------------------------------- |
| Idle timeout (`text_stream`)  | 30 sec  | The session closes if no new text arrives for 30 seconds. |
| Max session length            | 1 hour  | Sessions are capped at one hour.                          |
| Concurrent sessions per space | 3       | Maximum simultaneous realtime sessions.                   |

<Note>
  All three limits are adjustable — [reach out to us](https://www.heygen.com/contact-us/sales) to raise them.
</Note>

## Pricing

Billed per second of session duration (720p only): **\$0.05 / sec** self-serve, **0.05 credits / sec** on Enterprise. See [Self-Serve Pricing](/docs/pricing) and [Enterprise Pricing](/docs/enterprise-pricing).


# Avatar V
Source: https://developers.heygen.com/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)* — an `instant_avatar` look to use as the animation reference. Must belong to the same avatar group as `avatar_id`. 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://developers.heygen.com/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://developers.heygen.com/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": 734003200 },
      { "filename": "session-2.mp4", "content_type": "video/mp4", "size_bytes": 812646400 }
    ]
  }'
```

```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": 3600,
        "max_bytes": 734003200,
        "status": "pending_upload"
      },
      {
        "asset_id": "asset_81aa...",
        "upload_url": "https://heygen-uploads.s3.amazonaws.com/...",
        "upload_headers": { "Content-Type": "video/mp4" },
        "expires_in_seconds": 3600,
        "max_bytes": 812646400,
        "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.                                                                                |

### 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://developers.heygen.com/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://developers.heygen.com/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, 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://developers.heygen.com/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://developers.heygen.com/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="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: each scene is center-cropped to a 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` (up to `4k`), captions (sidecar `subtitle_url` plus optional burn-in), and webhooks.
  * **Batches:** studio payloads work as items in [`POST /v3/videos/batches`](/reference/create-video-batch), alongside the other creation modes.
</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:

  * **Realtime Avatar Streaming**: Added comprehensive support for streaming interactions via `POST /v3/avatar-realtime`, including endpoints to manage stream state, send text, and fetch word timing (`GET /v3/avatar-realtime/{stream_id}/words`).
  * **Background Removals**: New dedicated endpoints to programmatically manage background removal jobs: `GET/POST /v3/background-removals` and `DELETE/GET /v3/background-removals/{job_id}`.
  * **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="4K Temporarily Unavailable for Avatar IV & V" description="Changed - June 2026">
  **4K output for Avatar IV & V is temporarily deprecated**

  4K rendering for Avatar IV & V video generation is temporarily unavailable. The 4K rate has been removed from the [pricing page](/pricing) for these tiers — 720p / 1080p output and pricing are unaffected.

  * This is a temporary pause; 4K support is expected to return in a future update.
</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 [Create Avatar](/docs/create-avatar#prompt-to-avatar) 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 at a flat **\$7.00 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`. 4K renders are billed at 1.5× the 1080p rate.
  * `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. Aspect ratio does not affect pricing.

  **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. Pricing for 4K renders is unchanged — 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="Avatar V Pricing Parity with Avatar IV" description="Changed - May 12, 2026">
  **Avatar V is billed at the same rates as Avatar IV**

  Per-second video generation rates for Avatar V now match Avatar IV across both [self-serve](/docs/pricing) and [enterprise](/docs/enterprise-pricing) plans. No action required — pricing tables have been updated to reflect the combined Avatar IV & V rates.
</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://developers.heygen.com/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://developers.heygen.com/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 dashboard](https://app.heygen.com/settings/api?nav=API):

```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://developers.heygen.com/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                                                                                                                                                                                                                                                                                                                                                                                           |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--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 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 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           |

### Flags for `asset complete create`

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

### Flags for `asset create`

| Flag             | Description                                                                       |
| ---------------- | --------------------------------------------------------------------------------- |
| `--file <value>` | File to upload (image, video, audio, PDF, or SRT subtitle). Max 32 MB. (required) |

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

| Flag                         | Description                                                                                                                                                         |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--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).   |

## Asset Batch

Create and track batches of direct-to-S3 asset uploads.

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

### Flags for `asset-batch batches get`

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

### Flags for `asset-batch complete batches create`

| Flag                 | Description                                                               |
| -------------------- | ------------------------------------------------------------------------- |
| `--batch-id <value>` | Identifier returned by POST /v3/assets/direct-uploads/batches. (required) |

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

| Flag                     | Description                                                                              |
| ------------------------ | ---------------------------------------------------------------------------------------- |
| `--callback-url <value>` | Reserved for parity with the other batch APIs; asset completion does not emit a webhook. |
| `--title <value>`        | Display name for the batch, shown in the HeyGen app.                                     |

### Flags for `asset-batch 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 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    |

### Flags for `avatar consent create`

| Flag                    | Description                                                                                                       |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `--reroute-url <value>` | Callback URL where the user is redirected after completing consent. Defaults to HeyGen's consent completion page. |

### Flags for `avatar create`

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

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

## 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 list` | `GET /v3/brand-glossaries` | List Brand Glossaries |
| `heygen brand kits list`       | `GET /v3/brand-kits`       | List Brand Kits       |

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

## Lipsync

Dub or replace audio on existing videos

| Command                              | API Endpoint                       | Description    |
| ------------------------------------ | ---------------------------------- | -------------- |
| `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 update <lipsync-id>` | `PATCH /v3/lipsyncs/{lipsync_id}`  | Update Lipsync |

### Flags for `lipsync create`

| Flag                          | Description                                                                           |
| ----------------------------- | ------------------------------------------------------------------------------------- |
| `--callback-id <value>`       | ID included in webhook payload                                                        |
| `--callback-url <value>`      | Webhook URL for completion notifications                                              |
| `--disable-music-track`       | Remove background music                                                               |
| `--enable-caption`            | Generate captions for the output video                                                |
| `--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>`         | Project/folder ID to organize lipsync into                                            |
| `--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 update`

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

## Lipsync Batch

Create and track batches of lipsyncs.

| Command                                       | API Endpoint                          | Description           |
| --------------------------------------------- | ------------------------------------- | --------------------- |
| `heygen lipsync-batch batches create`         | `POST /v3/lipsyncs/batches`           | Create Lipsync Batch  |
| `heygen lipsync-batch batches get <batch-id>` | `GET /v3/lipsyncs/batches/{batch_id}` | Get Lipsync Batch     |
| `heygen lipsync-batch statuses list`          | `GET /v3/lipsyncs/statuses`           | Bulk Lipsync Statuses |

### Flags for `lipsync-batch batches create`

| Flag                     | Description                                                                     |
| ------------------------ | ------------------------------------------------------------------------------- |
| `--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-batch batches get`

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

### Flags for `lipsync-batch 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. |

## Template

Generate videos from reusable templates by replacing their variables

| Command                                  | API Endpoint                       | Description                  |
| ---------------------------------------- | ---------------------------------- | ---------------------------- |
| `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               |

### Flags for `template generate`

| Flag                              | Description                                                                                                                                                                                                         |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--brand-voice-id <value>`        | Brand voice ID controlling pronunciation                                                                                                                                                                            |
| `--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>`             | Folder to place the generated video in                                                                                                                                                                              |
| `--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 |

## 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 statuses list`          | `GET /v3/videos/statuses`           | Bulk Video Statuses |

### Flags for `video batches create`

| Flag                     | Description                                                                     |
| ------------------------ | ------------------------------------------------------------------------------- |
| `--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 batches get`

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

### Flags for `video create`

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 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 Message or Request Revision |
| `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-kit-id <value>` | Brand kit ID to apply brand colors, fonts, and logos to the generated video.                                                                                   |
| `--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                                                                                        |
| `--mode <value>`         | Session mode. 'generate' produces one video (fire-and-forget). 'chat' enables multi-turn interaction — the agent may pause for decisions and allows revisions. |
| `--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.                                                           |
| `--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                            |
| ------------------------ | -------------------------------------- |
| `--avatar-id <value>`    | Override avatar for this message       |
| `--brand-kit-id <value>` | Brand kit ID to apply for this message |
| `--message <value>`      | Text message to the agent (required)   |
| `--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 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 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 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 update <video-translation-id>`        | `PATCH /v3/video-translations/{video_translation_id}`            | Update Video Translation             |

### Flags for `video-translate create`

| Flag                          | Description                                                                                                                                                                                                              |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--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`            | Generate captions for translated video                                                                                                                                                                                   |
| `--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>`         | Project/folder ID to organize translation into                                                                                                                                                                           |
| `--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                                                                                                                                                                                                          |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--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>`         | Project/folder ID to organize proofread into                                                                                                                                                                         |
| `--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                                |
| ------------------------ | ------------------------------------------ |
| `--callback-id <value>`  | ID included in webhook payload             |
| `--callback-url <value>` | Webhook URL for completion notifications   |
| `--captions`             | Generate captions for the translated video |
| `--translate-audio-only` | Only translate audio, keep original video  |

### 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 update`

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

## Video Translation Batch

Create and track batches of video translations.

| Command                                                 | API Endpoint                                    | Description                     |
| ------------------------------------------------------- | ----------------------------------------------- | ------------------------------- |
| `heygen video-translation-batch batches create`         | `POST /v3/video-translations/batches`           | Create Video Translation Batch  |
| `heygen video-translation-batch batches get <batch-id>` | `GET /v3/video-translations/batches/{batch_id}` | Get Video Translation Batch     |
| `heygen video-translation-batch statuses list`          | `GET /v3/video-translations/statuses`           | Bulk Video Translation Statuses |

### Flags for `video-translation-batch batches create`

| Flag                     | Description                                                                     |
| ------------------------ | ------------------------------------------------------------------------------- |
| `--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-translation-batch batches get`

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

### Flags for `video-translation-batch 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. |

## 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. (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 voice engine (e.g. 'starfish'). When set, only voices compatible with that engine are returned. |
| `--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                                                                                                                                                |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--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>`     | BCP-47 locale tag (e.g. 'en-US', 'pt-BR'). When set, language is inferred from locale.                                                                     |
| `--speed <n>`          | Speed multiplier (0.5-2.0).                                                                                                                                |
| `--text <value>`       | Text to synthesize (1-5000 characters). (required)                                                                                                         |
| `--voice-id <value>`   | Voice ID to use. The voice must support the starfish engine. Filter compatible voices by passing engine=starfish to the voice listing endpoint. (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                                                                                           |
| --------------------- | ----------------------------------------------------------------------------------------------------- |
| `--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 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 |


# Content Repurposing
Source: https://developers.heygen.com/content-repurposing

Repurpose blog posts, podcasts, and long-form video into avatar-led short clips with the HeyGen API. One source, dozens of platform-ready outputs.

## The Problem

You invest hours writing a great blog post. It reaches your readers — but misses the much larger audience that consumes content through video. Manually converting articles to video takes almost as long as writing them.

## How It Works

```
Written content → LLM extracts key points → Video Agent renders → Distribute on video platforms
```

An LLM reads your content and writes a production-quality video prompt — extracting the most compelling points and restructuring them for video. The same article can become a 90-second YouTube explainer, a 30-second TikTok, and a 60-second LinkedIn post.

## Build It

<Steps>
  <Step title="Fetch your content">
    Pull the article from your CMS, a URL, or a local file.

    ```python theme={null}
    # From a file
    with open("article.md") as f:
        article = f.read()

    # Or from a URL (use a proper extraction library for production)
    import requests
    article = requests.get("https://yourblog.com/posts/your-article").text
    ```
  </Step>

  <Step title="Generate a video prompt with an LLM">
    The LLM acts as a producer — extracting the most engaging points and structuring them for video.

    ```python theme={null}
    import anthropic

    client = anthropic.Anthropic()

    message = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1024,
        messages=[{
            "role": "user",
            "content": f"""You are a video producer converting a written article
    into a HeyGen Video Agent prompt.

    Read this article and create a 60-second video prompt that:
    1. Opens with the most compelling insight or stat (hook)
    2. Covers the 3 most important points — not everything, the best bits
    3. Uses specific visual descriptions — what the viewer sees on screen
    4. Ends with a CTA to read the full article
    5. Matches the tone of the original

    Article:
    {article}

    Output ONLY the Video Agent prompt."""
        }],
    )
    video_prompt = message.content[0].text
    ```

    <Info>
      **Don't summarize — adapt.** The LLM shouldn't just compress the article. It should identify the most *visual* and *engaging* points and restructure them for video. A great blog point might be boring on video, and vice versa.
    </Info>
  </Step>

  <Step title="Generate the video">
    Submit the prompt. Attach any images or charts from the article as file inputs.

    ```python theme={null}
    resp = requests.post(
        "https://api.heygen.com/v3/video-agents",
        headers={
            "X-Api-Key": HEYGEN_API_KEY,
            "Content-Type": "application/json",
        },
        json={
            "prompt": video_prompt,
            "files": [
                {"type": "url", "url": "https://yourblog.com/images/chart.png"},
            ],
        },
    )
    video_id = resp.json()["data"]["video_id"]
    ```

    Then poll for completion — see [Video Agent docs](/docs/video-agent).
  </Step>

  <Step title="Generate multiple formats">
    One article can become multiple videos for different platforms:

    ```python theme={null}
    formats = [
        {"platform": "YouTube", "duration": "90s", "orientation": "landscape", "style": "in-depth"},
        {"platform": "TikTok/Reels", "duration": "30s", "orientation": "portrait", "style": "hook-driven"},
        {"platform": "LinkedIn", "duration": "60s", "orientation": "landscape", "style": "professional"},
    ]

    for fmt in formats:
        # Regenerate the LLM prompt with platform-specific instructions
        platform_prompt = generate_prompt_for(article, fmt)
        # Submit to Video Agent with the right orientation
        submit_video(platform_prompt, orientation=fmt["orientation"])
    ```
  </Step>
</Steps>

## Content Types That Convert Well

| Content type         | Video style          | Tips                                              |
| -------------------- | -------------------- | ------------------------------------------------- |
| **How-to articles**  | Tutorial walkthrough | Step-by-step with text overlays                   |
| **Listicles**        | Quick tips           | One point every 5–7 seconds, great for short-form |
| **Opinion/analysis** | Thought leadership   | Presenter-driven, conversational                  |
| **Case studies**     | Story-driven         | Before/after structure, stats as highlights       |
| **Newsletters**      | Weekly digest        | Cover 3–5 highlights, keep it breezy              |

## Automating the Pipeline

```
Blog CMS webhook → "New post published"
       ↓
  Fetch article content
       ↓
  LLM generates video prompt
       ↓
  Video Agent renders
       ↓
  Upload to YouTube / post to social
       ↓
  Add video embed to original article
```

Trigger from a CMS webhook, cron job, or CI/CD. See [Automated Broadcast](/cookbook/video-agent/automated-broadcast) for scheduling and distribution patterns.

## Variations

* **Teaser + full:** 15-second teaser for social, 90-second deep dive for YouTube
* **Multi-language:** Generate in English, then [translate](/cookbook/video-agent/multilingual-content) for global audiences
* **Podcast-to-video:** Extract audio highlights → write visual prompt → avatar presents the key takeaways

***

## Next Steps

<CardGroup>
  <Card title="Social Media Pipeline" icon="share-nodes" href="/cookbook/video-agent/social-media-pipeline">
    Generate original social content, not just repurposed articles.
  </Card>

  <Card title="Automated Broadcast" icon="tower-broadcast" href="/cookbook/video-agent/automated-broadcast">
    Automate the entire content → video → distribute pipeline.
  </Card>
</CardGroup>


# Data Visualization Videos
Source: https://developers.heygen.com/data-to-video

Convert spreadsheets, dashboards, and analytics into avatar-led explainer videos via the HeyGen API. The agent narrates the data and surfaces the key findings.

## Examples

<Tabs>
  <Tab title="Sorting Algorithms">
    <div>
      <iframe />
    </div>

    9 sorting algorithms on 100 bars — bubble sort through merge sort. Each comparison plays a pitched tone. 76 seconds with synthesized audio.
  </Tab>

  <Tab title="4000 Weeks">
    <div>
      <iframe />
    </div>

    A 75-year life as 3,900 weekly squares. They fill in with an accelerating heartbeat. The empty ones are what's left.
  </Tab>

  <Tab title="Flappy Bird">
    <div>
      <iframe />
    </div>

    A full Flappy Bird game playing itself — pixel art, auto-pilot AI, wing flap sounds, score dings. 33 seconds. No game engine, just HTML + math.
  </Tab>
</Tabs>

## The Problem

Data tells a story, but spreadsheets and static charts don't. Animated visualizations are compelling — but building them as shareable video (not just an interactive webpage) usually means screen recording with all its artifacts.

## How It Works

```
Data source → Generate visualization HTML → Animate with GSAP → Render to MP4
```

Hyperframes renders anything a browser can display. D3 charts, Canvas graphics, SVG diagrams, CSS animations — they all become pixel-perfect video frames.

## Build It

<Steps>
  <Step title="Prepare your data">
    Your data can come from anywhere — a CSV, an API, a database, or generated programmatically.

    ```python theme={null}
    # Example: pull GitHub stats
    import requests

    repos = requests.get(
        "https://api.github.com/users/your-username/repos",
        headers={"Authorization": f"token {GITHUB_TOKEN}"}
    ).json()

    stats = {
        "total_repos": len(repos),
        "languages": {},
        "total_stars": sum(r["stargazers_count"] for r in repos),
    }
    for r in repos:
        lang = r.get("language") or "Other"
        stats["languages"][lang] = stats["languages"].get(lang, 0) + 1
    ```
  </Step>

  <Step title="Describe the visualization to your AI agent">
    ```
    I have GitHub data for a developer: 13 repos, 472 commits,
    top languages are TypeScript (5), Dart (3), JavaScript (1).

    Create a "GitHub Wrapped" style video — vertical 9:16, 45 seconds.
    Show the stats one by one with animated counters, a bar chart of
    languages that grows, and end with a highlight reel of project names.
    Use a dark theme with green (#00ff88) accents like GitHub's contribution graph.
    ```

    The AI agent writes the HTML composition with the data baked into the animation.
  </Step>

  <Step title="Add generated audio (optional)">
    For data visualizations, synthesized audio often works better than voiceover. You can generate tones programmatically:

    ```python theme={null}
    import wave, struct, math

    # Generate pitched tones for a sorting visualizer
    sample_rate = 44100
    samples = []
    for value in data_points:
        freq = 200 + (value / max_value) * 1000  # pitch = data value
        for i in range(int(0.03 * sample_rate)):  # 30ms per tone
            env = 1.0 - (i / (0.03 * sample_rate)) * 0.7
            s = env * 0.25 * math.sin(2 * math.pi * freq * i / sample_rate)
            samples.append(s)

    with wave.open("data-sound.wav", "w") as wf:
        wf.setnchannels(1)
        wf.setsampwidth(2)
        wf.setframerate(sample_rate)
        for s in samples:
            wf.writeframes(struct.pack("<h", int(max(-1, min(1, s)) * 32767)))
    ```

    Then reference it in the composition:

    ```html theme={null}
    <audio id="data-sfx" data-start="0" data-track-index="5"
           data-volume="0.8" src="data-sound.wav"></audio>
    ```
  </Step>

  <Step title="Preview and render">
    ```bash theme={null}
    npx hyperframes dev    # preview at localhost:3002
    npx hyperframes render # export to MP4
    ```
  </Step>
</Steps>

## Visualization Ideas

| Type                        | What it looks like                               | Complexity                            |
| --------------------------- | ------------------------------------------------ | ------------------------------------- |
| **Animated bar chart**      | Bars growing, sorting, racing                    | Simple — CSS + GSAP                   |
| **Counter/ticker**          | Numbers rolling up from 0 to target              | Simple — GSAP snap                    |
| **Line chart drawing**      | SVG polyline with stroke-dashoffset animation    | Medium — SVG + GSAP                   |
| **Dashboard**               | Multiple panels updating simultaneously          | Medium — layout + timing              |
| **Algorithm visualization** | Sorting bars, pathfinding grids, tree traversals | Complex — pre-compute states, animate |
| **Physics simulation**      | Bouncing balls, pendulum waves, particle systems | Complex — math-driven positions       |

## Automate It

The real power: **data in, video out** as a pipeline.

```python theme={null}
import subprocess

def generate_data_video(data, template_dir, output_path):
    """Generate a video from data using Hyperframes."""

    # 1. Write data into the composition
    with open(f"{template_dir}/data.json", "w") as f:
        json.dump(data, f)

    # 2. Render
    subprocess.run([
        "npx", "hyperframes", "render",
        "--output", output_path,
        "--quality", "standard"
    ], cwd=template_dir)

    return output_path

# Generate weekly report videos from database
for week in get_weekly_metrics():
    generate_data_video(
        data=week,
        template_dir="templates/weekly-report",
        output_path=f"renders/report-{week['date']}.mp4"
    )
```

<Tip>
  Combine with [Docs to Video](/cookbook/video-agent/docs-to-video) for a fully automated pipeline: data changes → Hyperframes renders visualization → Video Agent adds avatar narration.
</Tip>

***

## Next Steps

<CardGroup>
  <Card title="Motion Graphics" icon="wand-magic-sparkles" href="/cookbook/hyperframes/motion-graphics">
    Animated title cards, product launches, and brand content.
  </Card>

  <Card title="Automated Pipeline" icon="gears" href="/cookbook/hyperframes/automated-pipeline">
    CI/CD integration for continuous video generation from data.
  </Card>
</CardGroup>


# Design a Custom Voice
Source: https://developers.heygen.com/design-a-voice

Generate a new HeyGen voice from a natural-language description. No audio sample needed; describe the voice and HeyGen synthesizes it for use in your videos.

## Steps

<Steps>
  <Step title="Describe the voice you want">
    Use `voice create` with a natural language prompt:

    ```bash theme={null}
    heygen voice create --prompt "warm, confident female narrator with a slight British accent"
    ```

    ```json theme={null}
    {
      "data": {
        "seed": 0,
        "voices": [
          {
            "voice_id": "BDfLWYibC6on6hn2IqEC",
            "name": "Warm Confident Narrator",
            "gender": "female",
            "language": "English",
            "preview_audio_url": "https://files2.heygen.ai/voice-design/previews/..."
          },
          {
            "voice_id": "1jgmj3JDxkh9ybd7CRzS",
            "name": "Warm Confident Narrator",
            "preview_audio_url": "..."
          },
          {
            "voice_id": "Db84ogyBT4thl08lVok8",
            "name": "Warm Pro Narrator",
            "preview_audio_url": "..."
          }
        ]
      }
    }
    ```

    You get up to 3 voice options. Each includes a `preview_audio_url` you can listen to before committing.
  </Step>

  <Step title="Get different options with --seed">
    The same prompt with the same seed always returns the same voices. Increment `--seed` to explore new batches:

    ```bash theme={null}
    heygen voice create --prompt "warm, confident female narrator" --seed 1
    heygen voice create --prompt "warm, confident female narrator" --seed 2
    ```
  </Step>

  <Step title="Use the voice in a video">
    Take the `voice_id` and pass it to any video creation command.

    <CodeGroup>
      ```bash Video Agent (prompt-based) theme={null}
      heygen video-agent create \
        --prompt "A presenter introducing our new product line" \
        --voice-id "BDfLWYibC6on6hn2IqEC"
      ```

      ```bash Video Create (full control) theme={null}
      heygen video create -d '{
        "type": "avatar",
        "avatar_id": "avt_angela_01",
        "script": "Welcome to the future of video creation.",
        "voice_id": "BDfLWYibC6on6hn2IqEC"
      }'
      ```
    </CodeGroup>
  </Step>
</Steps>

## Prompt tips

The quality of your voice depends on the quality of your description:

| Prompt                                                            | Result                    |
| ----------------------------------------------------------------- | ------------------------- |
| `"deep male voice with authority, like a movie trailer narrator"` | Dramatic, resonant bass   |
| `"friendly young woman, upbeat and energetic, American accent"`   | Casual, approachable      |
| `"calm, measured British male, BBC documentary style"`            | Professional, trustworthy |
| `"enthusiastic tech reviewer, fast-paced, excited"`               | High energy, engaging     |
| `"soft-spoken female, ASMR-like, soothing"`                       | Gentle, intimate delivery |

## Optional flags

| Flag       | Description                                                    |
| ---------- | -------------------------------------------------------------- |
| `--gender` | `male` or `female` — narrows results                           |
| `--locale` | BCP-47 locale tag (e.g. `en-US`, `pt-BR`) for accent targeting |
| `--seed`   | Increment to get different batches (default: `0`)              |

## Browsing existing voices instead

If you'd rather use a stock voice:

```bash theme={null}
# All English female voices
heygen voice list --language English --gender female --limit 20

# Private voices (ones you've created)
heygen voice list --type private
```


# Docs to Video
Source: https://developers.heygen.com/docs-to-video

Convert README files, knowledge base articles, and documentation into avatar-led explainer videos via the HeyGen API. One command, one rendered video.

## The Problem

Documentation is essential but most people don't read it. Video walkthroughs get significantly more engagement — but recording, editing, and keeping them in sync with doc changes costs more than most teams can justify.

## How It Works

```
Doc changes → LLM writes a video prompt → Video Agent renders → Embed or distribute
```

You don't send docs directly to Video Agent. An LLM converts documentation into a structured video prompt — acting as a video producer who reads the source material and writes production direction.

## Build It

<Steps>
  <Step title="Extract the content">
    ```python theme={null}
    # From a file
    with open("README.md") as f:
        content = f.read()

    # Or from a URL
    import requests
    content = requests.get(
        "https://raw.githubusercontent.com/your-org/repo/main/README.md"
    ).text
    ```
  </Step>

  <Step title="Generate a video prompt with an LLM">
    ```python theme={null}
    import anthropic

    client = anthropic.Anthropic()

    message = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1024,
        messages=[{
            "role": "user",
            "content": f"""You are a video producer. Convert this documentation
    into a HeyGen Video Agent prompt.

    Structure as 3–5 scenes with timing. Open with a hook explaining what this
    does and why it matters. Walk through key points visually. End with a next
    step. Target: 60 seconds. Be specific about visuals.

    Documentation:
    {content}

    Output ONLY the Video Agent prompt."""
        }],
    )
    video_prompt = message.content[0].text
    ```

    <Info>
      **The two-stage pattern:** Content → LLM (writes production prompt) → Video Agent (renders). The LLM bridges the gap between "what the docs say" and "what the video should show."
    </Info>
  </Step>

  <Step title="Submit to Video Agent">
    ```python theme={null}
    resp = requests.post(
        "https://api.heygen.com/v3/video-agents",
        headers={
            "X-Api-Key": HEYGEN_API_KEY,
            "Content-Type": "application/json",
        },
        json={"prompt": video_prompt},
    )
    video_id = resp.json()["data"]["video_id"]
    ```

    Optionally attach screenshots or diagrams as [file inputs](/docs/video-agent#file-input-formats). Then poll for completion.
  </Step>
</Steps>

## CI/CD Integration

Trigger video generation automatically when documentation changes:

```yaml theme={null}
# .github/workflows/docs-video.yml
name: Generate Doc Video
on:
  push:
    paths: ['docs/**', 'README.md', 'CHANGELOG.md']

jobs:
  generate-video:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate video
        env:
          HEYGEN_API_KEY: ${{ secrets.HEYGEN_API_KEY }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: python scripts/generate-doc-video.py
```

<Warning>
  Store API keys as [GitHub encrypted secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets). Never commit them.
</Warning>

## Variations

* **Changelog videos:** "Here's what's new in v2.3" — generate for each release
* **API docs:** Walk through new endpoints or breaking changes visually
* **Onboarding:** Auto-generate "Getting Started" videos from quickstart guides
* **Multi-language:** Generate, then [translate](/cookbook/video-agent/multilingual-content) for international docs

***

## Next Steps

<CardGroup>
  <Card title="Content Repurposing" icon="recycle" href="/cookbook/video-agent/content-repurposing">
    Apply the same pattern to blog posts and articles.
  </Card>

  <Card title="Automated Broadcast" icon="tower-broadcast" href="/cookbook/video-agent/automated-broadcast">
    Schedule video generation pipelines.
  </Card>
</CardGroup>


# API Key
Source: https://developers.heygen.com/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 [HeyGen API dashboard](https://app.heygen.com/home?from=\&nav=API)
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.

## 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** in your [API dashboard](https://app.heygen.com/home?from=\&nav=API)


# Avatar Consent
Source: https://developers.heygen.com/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/create-avatar#digital-twin)), 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>
  Consent applies only to **digital twin** avatars. Photo avatars (`type: "photo"`) and prompt-to-avatar characters (`type: "prompt"`) depict no real, identifiable person and do **not** require consent.
</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 in v3                                                            |
| **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, whitelisted accounts | Available today in v3 — [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, whitelisted accounts | [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; whitelisted 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. 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 (e.g. `"pending"`).                                                                                                                                                   |

### Upload a consent video (Level 2)

Whitelisted 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 requires a whitelisted account — 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** — the subject names themselves and explicitly allows HeyGen to use their footage — so minor wording differences are fine. A clear version of the statement:

> "I, \[Full Name], hereby allow HeyGen to use the footage of me to build a HeyGen avatar."

| Requirement       | Detail                                                                                                |
| ----------------- | ----------------------------------------------------------------------------------------------------- |
| Consent statement | The subject says the line above: their name plus explicit permission for HeyGen to use their footage. |
| 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            | A short clip is enough.                                                                               |
| Format            | A standard video file (for example MP4), supplied as a public HTTPS URL or an uploaded `asset_id`.    |

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 photo and prompt avatars, which never require consent.
</Tip>

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


# Avatar Looks
Source: https://developers.heygen.com/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://developers.heygen.com/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. `null` means consent is not required.                                                                                                                                  |
| `status`            | string or null | Training status: `"processing"`, `"pending_consent"`, `"completed"`, or `"failed"`. 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).

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


# Choosing the Right Video API
Source: https://developers.heygen.com/docs/choosing-the-right-video-api

Compare HeyGen's video APIs - Video Agent, Direct Video, and Cinematic Avatar. Pick the right endpoint for your use case in this side-by-side decision.

HeyGen offers three ways to create videos programmatically. The right choice depends on how much control you need and whether you want a spoken script or a prompt-composed cinematic shot.

|                           | Video Agent                   | Direct Video      | Cinematic Avatar                               |
| ------------------------- | ----------------------------- | ----------------- | ---------------------------------------------- |
| **Endpoint**              | `POST /v3/video-agents`       | `POST /v3/videos` | `POST /v3/videos` (`type: "cinematic_avatar"`) |
| **Input**                 | Natural language prompt       | Structured JSON   | Prompt + 1–3 avatar looks                      |
| **Script writing**        | Agent writes it               | You write it      | None — motion driven by the prompt             |
| **Avatar selection**      | Agent picks (or you override) | You specify       | You specify 1–3 looks                          |
| **Voice selection**       | Agent picks (or you override) | You specify       | None — no spoken voice                         |
| **Interactive iteration** | ✅ Via chat mode               | ❌                 | ❌                                              |
| **Webhook support**       | ✅ `callback_url`              | ✅ `callback_url`  | ✅ `callback_url`                               |
| **Control level**         | Low (prompt-driven)           | High (explicit)   | Medium (prompt + your looks)                   |

## Video Agent — best for speed

Send a text prompt, get a video. The agent handles scripting, avatar selection, and scene composition automatically.

```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 60-second onboarding video for our SaaS product. Friendly tone.",
    "callback_url": "https://yourapp.com/webhook/heygen"
  }'
```

**Use when:**

* You want a video fast without managing avatars or scripts
* You're building a product where end users describe videos in natural language
* You want to iterate interactively — use `mode: "chat"` to review the storyboard before rendering

**Trade-off:** Less control over exact scene composition and creative choices.

## Direct Video — best for control

Explicitly specify the avatar, voice, and script. Predictable, repeatable output for automated pipelines.

```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": "your_voice_id",
    "script": "Hi there! This video was created just for you.",
    "aspect_ratio": "auto",
    "resolution": "1080p",
    "callback_url": "https://yourapp.com/webhook/heygen"
  }'
```

**Use when:**

* Building automated pipelines (personalized sales videos, daily reports)
* You need exact control over avatar, voice, and script
* Generating videos programmatically from data (CRM records, form submissions)

**Trade-off:** You handle all creative decisions — avatar IDs and voice IDs must be known upfront.

## Cinematic Avatar — best for cinematic shots

A prompt-driven variant of `POST /v3/videos`. Hand HeyGen 1–3 avatar looks plus a natural-language prompt and the Seedance pipeline composes the scene, motion, and framing — no script or voice. See the full [Cinematic Avatar guide](/cinematic-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": "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,
    "callback_url": "https://yourapp.com/webhook/heygen"
  }'
```

**Use when:**

* You want cinematic b-roll or motion of an avatar rather than a talking-head script
* You want to feature up to three looks in one composed shot
* You want to steer style and motion with your own reference videos and images

**Trade-off:** No spoken script or voice, and output is capped at **720p / 1080p** (4K is not supported). Clips run 4–15 seconds.

## Not sure which to pick?

Start with Video Agent. If you need precise control over the script, avatar, or timing, switch to `POST /v3/videos`. If you want a prompt-composed cinematic shot with no script, reach for [Cinematic Avatar](/cinematic-avatar).

You can also combine them — use Video Agent to explore ideas and find the right style, then recreate with explicit parameters for the final production version.


# Create Avatar
Source: https://developers.heygen.com/docs/create-avatar

Create a HeyGen avatar from video footage, a single photo, or a text prompt. Covers all three creation types, generating new looks for an existing avatar, the consent flow, and how to render videos with your trained avatar.

<img alt="" />

Three creation modes all go through [`POST /v3/avatars`](/reference/create-avatar) — distinguished by the `type` field. The result is a new **look** that you pass as `avatar_id` to video creation endpoints. To browse existing avatars and looks instead, see [Avatars](/docs/avatars) and [Avatar Looks](/docs/avatar-looks).

## Pick your flow

| You have...               | You want...                                        | Use                                                     |
| ------------------------- | -------------------------------------------------- | ------------------------------------------------------- |
| Video footage of a person | A reusable digital twin of that person             | [`type: "digital_twin"`](#digital-twin)                 |
| A photo of a person       | An avatar from that photo, fast                    | [`type: "photo"`](#photo-avatar)                        |
| Just a text description   | A fully synthetic AI character                     | [`type: "prompt"`](#prompt-to-avatar)                   |
| An existing HeyGen avatar | A **new look** for it (new outfit, setting, style) | [`type: "prompt"`](#prompt-to-avatar) **+** `avatar_id` |

The last row is the most-overlooked path: once you have any HeyGen avatar (digital twin, photo, or prompt), you can use the prompt endpoint to generate additional looks for that same character — see [Generate new looks for an existing avatar](#generate-new-looks-for-an-existing-avatar).

## Creation Methods

<Tabs>
  <Tab title="Digital Twin">
    ### Digital Twin (`type: "digital_twin"`)

    Create an avatar from video footage. The speaker in the video becomes a reusable digital 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": "My Digital Twin",
        "file": { "type": "url", "url": "https://example.com/training-footage.mp4" }
      }'
    ```

    | Parameter         | Type   | Required | Description                                                                                                                                                                                                              |
    | ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | `type`            | string | Yes      | Must be `"digital_twin"`.                                                                                                                                                                                                |
    | `name`            | string | Yes      | Display name for the avatar.                                                                                                                                                                                             |
    | `file`            | object | Yes      | Training video. `{ "type": "url", "url": "..." }`, `{ "type": "asset_id", "asset_id": "..." }` (from [`POST /v3/assets`](/reference/upload-asset)), or `{ "type": "base64", "media_type": "video/mp4", "data": "..." }`. |
    | `avatar_group_id` | string | No       | Attach to an existing character identity. Omit to create a new one.                                                                                                                                                      |
  </Tab>

  <Tab title="Photo Avatar">
    ### Photo Avatar (`type: "photo"`)

    Create an avatar from a single photo. Quick to set up — no video recording needed.

    ```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": "My Photo Avatar",
        "file": { "type": "url", "url": "https://example.com/headshot.png" }
      }'
    ```

    | Parameter         | Type   | Required | Description                                                         |
    | ----------------- | ------ | -------- | ------------------------------------------------------------------- |
    | `type`            | string | Yes      | Must be `"photo"`.                                                  |
    | `name`            | string | Yes      | Display name for the avatar.                                        |
    | `file`            | object | Yes      | Photo image. Same format options as digital twin `file`.            |
    | `avatar_group_id` | string | No       | Attach to an existing character identity. Omit to create a new one. |

    <Tip>
      **Want to generate new outfits or settings from a photo using a prompt?** Create the photo avatar first, then call `type: "prompt"` with the returned `avatar_item.id` as `avatar_id` — see [Generate new looks for an existing avatar](#generate-new-looks-for-an-existing-avatar). The image you upload here becomes the visual reference that prompt-driven variations are conditioned on.
    </Tip>
  </Tab>

  <Tab title="Prompt-to-Avatar">
    ### Prompt-to-Avatar (`type: "prompt"`) — Tokyo Pipeline

    Generate an entirely new AI avatar from a text description. No photo or video needed — describe the character you want and the Tokyo pipeline creates it.

    <Info>
      Prompt-to-Avatar uses HeyGen's Tokyo pipeline to generate a unique AI character from your text description. The avatar is fully synthetic — no real person is depicted.
    </Info>

    ```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": "Young woman, early 30s, confident expression, short silver hair, warm brown eyes, wearing a dark blue space suit with mission patches, standing in a modern spacecraft bridge with holographic displays"
      }'
    ```

    #### Parameters

    | Parameter          | Type   | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
    | ------------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | `type`             | string | Yes      | Must be `"prompt"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
    | `name`             | string | Yes      | Display name for the avatar.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
    | `prompt`           | string | Yes      | Text description of the avatar's appearance, clothing, setting, and style. Max 1000 chars. Be specific for best results.                                                                                                                                                                                                                                                                                                                                                                                                             |
    | `avatar_id`        | string | No       | An existing look ID to use as the **visual reference** for 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. The referenced avatar must exist and have a usable image, otherwise the request is rejected. Use this to create new looks (outfits, settings, styles) for an avatar you already created — see [Generate new looks for an existing avatar](#generate-new-looks-for-an-existing-avatar). |
    | `avatar_group_id`  | string | No       | The identity (group) to **save** the generated avatar to. By default a new identity is created. If `avatar_id` is also provided, it must belong to this group. This field only controls where the result is saved — it does not drive the visual reference; use `avatar_id` for that.                                                                                                                                                                                                                                                |
    | `reference_images` | array  | No       | Up to **3** reference images for additional style/setting guidance. Each entry is `{ "type": "url", "url": "..." }`, `{ "type": "asset_id", "asset_id": "..." }` (from [`POST /v3/assets`](/reference/upload-asset)), or `{ "type": "base64", "media_type": "image/png", "data": "..." }`. Can be used on their own or layered on top of an `avatar_id` reference.                                                                                                                                                                   |

    #### How `avatar_id` and `avatar_group_id` combine

    | `avatar_id` | `avatar_group_id` | Visual reference                        | Saved to                                             |
    | ----------- | ----------------- | --------------------------------------- | ---------------------------------------------------- |
    | ✗           | ✗                 | none — generated purely from the prompt | a new group                                          |
    | ✗           | ✓                 | none — generated purely from the prompt | that group                                           |
    | ✓           | ✗                 | the referenced avatar's image           | the referenced avatar's group                        |
    | ✓           | ✓                 | the referenced avatar's image           | `avatar_group_id` (the avatar **must** belong to it) |

    `reference_images` layer additional guidance on top of any of these combinations; with no `avatar_id` they are used on their own.

    <Warning>
      **Changed behavior (June 2026):** `avatar_group_id` previously conditioned the generation on one of the group's looks. It now only controls where the result is saved. If you relied on it for character consistency, pass the base look's ID as `avatar_id` instead — see the [changelog](/changelog).
    </Warning>

    <Tip>
      **Prompting tips for best results:**

      * Be specific about age, gender, expression, and clothing
      * Describe the setting/background
      * Mention lighting or mood (e.g., `"warm studio lighting"`, `"cinematic"`)
      * Reference images help with style consistency but are optional
    </Tip>

    #### Generate new looks for an existing avatar

    If you already have a HeyGen avatar — from any creation type — you can generate additional looks for that same character by calling `type: "prompt"` with the existing look's ID as `avatar_id`. The referenced look's image is used as the visual reference that conditions the new generation, so the character's identity stays consistent across the new outfit, setting, or style described in your prompt. The new look is saved to the referenced avatar's group automatically — no `avatar_group_id` needed.

    Typical sequence — say you have a photo of a person and want several prompt-driven variations:

    1. Create the photo avatar once:

       ```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" }
         }'
       ```

       Save the returned `avatar_item.id` (e.g. `look_abc123`).

    2. Generate as many additional looks as you need, each conditioned on Sarah's identity:

       ```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 Office",
           "prompt": "Wearing a navy blazer, modern office background with plants, warm natural light",
           "avatar_id": "look_abc123"
         }'
       ```

    Each call returns a new `avatar_item.id` (a new look) attached to the same `avatar_group.id`. Browse all looks for an avatar via [`GET /v3/avatars/looks?group_id=...`](/reference/list-avatar-looks) — and pass any look's ID as `avatar_id` to use it as the reference for the next variation.

    <Note>
      Passing only `avatar_group_id` (without `avatar_id`) saves the new look to that group but does **not** use any of the group's images as a visual reference — the result is generated purely from the prompt. To keep a character's identity consistent, pass the base look's ID as `avatar_id`.
    </Note>

    #### With reference images

    `reference_images` (up to 3) add style or setting guidance to the generation. They can be used on their own — to guide a brand-new identity — or layered on top of an `avatar_id` reference for extra control over the new look:

    ```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": "Brand Ambassador — Plant Studio",
        "prompt": "Professional woman in her 40s, warm smile, wearing a navy blazer, modern office background with plants",
        "avatar_id": "look_abc123",
        "reference_images": [
          { "type": "url", "url": "https://example.com/style-reference.png" },
          { "type": "url", "url": "https://example.com/setting-reference.jpg" }
        ]
      }'
    ```

    #### Errors

    | Condition                                                                               | HTTP status | Error code          |
    | --------------------------------------------------------------------------------------- | ----------- | ------------------- |
    | `avatar_id` not found                                                                   | 404         | `AVATAR_NOT_FOUND`  |
    | `avatar_id` exists but has no usable image (e.g. generation not completed, or rejected) | 400         | `INVALID_PARAMETER` |
    | `avatar_id` does not belong to the provided `avatar_group_id`                           | 400         | `INVALID_PARAMETER` |
  </Tab>
</Tabs>

## Response

All three creation types return the same response shape:

```json theme={null}
{
  "data": {
    "avatar_item": {
      "id": "look_abc123",
      "name": "Space Commander",
      "avatar_type": "studio_avatar",
      "group_id": "group_xyz789",
      "preview_image_url": "https://files.heygen.ai/...",
      "supported_api_engines": ["avatar_iv", "avatar_v"],
      "tags": []
    },
    "avatar_group": {
      "id": "group_xyz789",
      "name": "Space Commander",
      "looks_count": 1,
      "consent_status": null,
      "created_at": 1717000000
    }
  }
}
```

| Field                               | Type           | Description                                                                                                                                                    |
| ----------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `avatar_item.id`                    | string         | The look ID — pass this as `avatar_id` to [`POST /v3/videos`](/reference/create-video) or [Create Video Agent Session](/reference/create-video-agent-session). |
| `avatar_item.avatar_type`           | string         | `"digital_twin"`, `"photo_avatar"`, or `"studio_avatar"`.                                                                                                      |
| `avatar_item.supported_api_engines` | array          | Engine values compatible with this look for [`POST /v3/videos`](/reference/create-video).                                                                      |
| `avatar_item.group_id`              | string         | The character identity this look belongs to.                                                                                                                   |
| `avatar_group.id`                   | string         | Group ID. Use to add more looks or initiate consent.                                                                                                           |
| `avatar_group.consent_status`       | string or null | `null` for photo and prompt avatars. Digital twins may require consent — see below.                                                                            |

## Avatar Consent

Before you can generate video with a **digital twin**, the person depicted must consent to being cloned. Photo avatars and prompt-to-avatar characters do not require consent (their `consent_status` is `null`).

HeyGen offers three increasing levels of consent access — recording via webcam (all customers), uploading a consent video through the same API endpoint, and skipping consent entirely. The two higher levels require a whitelisted enterprise account — reach out to sales or your account team for access. The API flows, the full breakdown of the three levels, and how to request them all live on the dedicated page.

<Card title="Avatar Consent — levels of access & the API flow" icon="shield-halved" href="/docs/avatar-consent">
  How consent works, who each level is for, and the `POST /v3/avatars/{group_id}/consent` flow.
</Card>

## Avatars vs. Looks

An **avatar group** is a character identity (e.g. "Sarah"). Each group can have multiple **looks** — different outfits, poses, or styles. When creating a video, you pass a look ID (not a group ID) as the `avatar_id`. Use [`GET /v3/avatars/looks`](/reference/list-avatar-looks) to browse looks (see [Avatar Looks](/docs/avatar-looks)), or pass `avatar_group_id` when creating a new avatar to add a look to an existing character.


# Discord
Source: https://developers.heygen.com/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 />


# Enterprise Pricing
Source: https://developers.heygen.com/docs/enterprise-pricing

Get HeyGen Enterprise API pricing for high-volume video generation. Custom rate limits, SLAs, dedicated support, and per-second billing. Contact sales.

<img alt="" />

## Overview

Enterprise plans work the same way as [self-serve](/docs/pricing) — the difference is the unit. Where self-serve bills in USD, Enterprise plans are billed in **credits**, and **1 credit costs \$0.50**. To map an enterprise rate to the self-serve page, multiply the credit rate by \$0.50: for example, Photo Avatar video at 0.1 credits / sec is the equivalent of \$0.05 / sec.

## Pricing

### Video Generation — Avatar V

Highest-fidelity engine with cross-reference-driven animation — see the [Avatar V model page](/avatar-v) for engine details. Avatar V supports Digital Twins only.

| Avatar Type  | Rate              |
| ------------ | ----------------- |
| Digital Twin | 0.1 credits / sec |

### Video Generation — Avatar IV

Default v3 engine — see the [Avatar IV model page](/avatar-iv) for engine details.

| Avatar Type   | Rate              |
| ------------- | ----------------- |
| Photo Avatar  | 0.1 credits / sec |
| Digital Twin  | 0.1 credits / sec |
| Studio Avatar | 0.1 credits / sec |

### Video Generation — Avatar III

Dedicated photo-to-video pipeline — see the [Avatar III model page](/avatar-iii) for engine details.

| Avatar Type   | Rate                 |
| ------------- | -------------------- |
| Digital Twin  | 0.0167 credits / sec |
| Studio Avatar | 0.0167 credits / sec |
| Photo Avatar  | 0.0433 credits / sec |

### Video Generation — Avatar III (Legacy v1/v2)

<Warning>
  This is the **older Avatar III engine** on the legacy **v1/v2 endpoints** — a different pipeline from the `avatar_iii` engine above. It is available to existing customers only and is not offered on the new developer platform. For all new integrations use the v3 engines: [Avatar IV](/avatar-iv), [Avatar V](/avatar-v), or [Avatar III](/avatar-iii).
</Warning>

| Avatar Type   | Rate                 |
| ------------- | -------------------- |
| Photo Avatar  | 0.0033 credits / sec |
| Digital Twin  | 0.0033 credits / sec |
| Studio Avatar | 0.0033 credits / sec |

### Cinematic Avatar

Flat rate per video (4–15 seconds, 720p/1080p only), not billed by duration. See the [Cinematic Avatar guide](/cinematic-avatar).

| Item                   | Rate              |
| ---------------------- | ----------------- |
| Cinematic Avatar video | 7 credits / video |

### Avatar Realtime

Live streaming avatar session, billed per second of session duration (720p only). See the [Avatar Realtime guide](/avatar-realtime).

| Feature                 | Rate               |
| ----------------------- | ------------------ |
| Avatar Realtime session | 0.05 credits / sec |

### Video Agent

| Feature         | Rate                 |
| --------------- | -------------------- |
| Prompt to Video | 0.0667 credits / sec |

### HyperFrames

Billed per minute of output video; the rate scales with `resolution` and `fps`. See the [HyperFrames guide](/hyperframes).

| Resolution / Frame Rate | Rate               |
| ----------------------- | ------------------ |
| 1080p / 30 fps          | 0.1 credits / min  |
| 1080p / 60 fps          | 0.2 credits / min  |
| 4K / 30 fps             | 0.15 credits / min |
| 4K / 60 fps             | 0.3 credits / min  |

### Video Translation

| Mode                 | Rate                  |
| -------------------- | --------------------- |
| Speed — Audio Only   | 0.05 credits / sec    |
| Speed — Lip Sync     | 0.05 credits / sec    |
| Precision — Lip Sync | 0.1 credits / sec     |
| Proofread            | 0.00833 credits / sec |

### Lipsync

| Mode      | Rate               |
| --------- | ------------------ |
| Speed     | 0.05 credits / sec |
| Precision | 0.1 credits / sec  |

### AI Clipping

Turn a long-form video into short highlight clips, billed per clip produced. See the [AI Clipping guide](/ai-clipping).

| Item           | Rate                |
| -------------- | ------------------- |
| Highlight clip | 0.15 credits / clip |

### Text-to-Speech

| Model             | Rate                   |
| ----------------- | ---------------------- |
| Speech — Starfish | 0.000333 credits / sec |

### Avatar Creation

| Operation    | Rate            |
| ------------ | --------------- |
| Digital Twin | 1 credit / call |
| Photo Avatar | 1 credit / call |

***

## Concurrency Limits

| Plan       | Max Concurrent Video Jobs |
| ---------- | ------------------------- |
| Enterprise | 20+ (varies by contract)  |

Concurrent jobs include any asynchronous generation in progress: Video Agent sessions, avatar video renders, and video translations. Exceeding the limit returns `429 Too Many Requests` with a `Retry-After` header.

***

## Endpoint Limits

### Video Generation Input

Resources provided to `POST /v3/videos` must meet these limits. Invalid resources will cause render failures.

| 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`), an HTTPS URL, or base64-encoded content.

### Asset Upload (`POST /v3/assets`)

* **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`).
* **Supported types:** Image (PNG, JPEG), video (MP4, WebM), audio (MP3, WAV), and PDF.

### Text-to-Speech Input (`POST /v3/voices/speech`)

* **Text length:** 1–5,000 characters.
* **Speed multiplier:** 0.5× to 2.0×.
* **Input type:** Plain text or SSML markup.

### 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 (up to 4K on Enterprise).
* **Aspect ratio:** 16:9 or 9:16.
* **Maximum scenes:** 50 per video.
* **Maximum duration:** Custom (contact your account team).

***

## 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`                               | 10      | 100 |
| `GET /v3/avatars`                              | 20      | 50  |
| `GET /v3/avatars/looks`                        | 20      | 50  |
| `GET /v3/voices`                               | 20      | 100 |
| `GET /v3/video-agents/styles`                  | 20      | 100 |
| `GET /v3/video-translations`                   | 10      | 100 |
| `GET /v3/webhooks/endpoints`                   | 10      | 100 |
| `GET /v3/webhooks/events`                      | 10      | 100 |
| `GET /v3/video-agents/sessions/{id}/resources` | 8       | 100 |

***

## Rate Limiting

All endpoints enforce rate limits. When exceeded, the API returns `429 Too Many Requests` with a `Retry-After` header indicating the number of seconds to wait before retrying.


# Enterprise Billing — Dollar-Based
Source: https://developers.heygen.com/docs/enterprise-pricing-dollar-base

Buy HeyGen API capacity in dollars, not credits. Enterprise dollar-based billing lets your team forecast spend across avatars, video agent, translation, and.

<img alt="" />

| Model               | How It Works                                                | Best For                                                      |
| ------------------- | ----------------------------------------------------------- | ------------------------------------------------------------- |
| Usage-Based Billing | Monthly Minimum Commitment (MMC) with overage billing       | Teams with predictable, recurring API usage                   |
| Dollar Packages     | Purchase an annual pool of dollars upfront under a contract | Teams that prefer a fixed annual spend with flexible drawdown |

Both models authenticate with an **API Key** (`x-api-key` header). Check your balance at any time with `GET /v3/users/me → wallet`.

## Usage-Based Billing

Usage-based billing pairs a flat Monthly Minimum Commitment (MMC) with per-second usage billing. If you exceed the included usage in a given month, overage is billed at a slightly higher rate.

### How It Works

1. **Monthly Minimum Commitment (MMC):** A flat fee charged monthly, regardless of usage.
2. **Included Usage:** Each tier includes a pool of usage dollars per month at your contracted rate.
3. **Overage:** Usage beyond the included pool is billed at the overage rate per second.

For pricing details and available tiers, [contact our sales team](https://www.heygen.com/contact-us/sales).

## Dollar Packages

Dollar packages let you purchase a fixed annual pool of dollars under a contract. Your balance is drawn down as you use the API throughout the year.

### How It Works

1. **Annual Contract:** You agree to a total dollar amount for the contract term (typically 12 months).
2. **Drawdown:** Your balance is consumed per second as you use HeyGen's API.
3. **Balance Tracking:** Monitor your remaining balance at any time via `GET /v3/users/me → wallet`.

For packaging options and contract terms, [contact our sales team](https://www.heygen.com/contact-us/sales).


# Error Codes
Source: https://developers.heygen.com/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`, and a `doc_url` linking to the relevant section below. Some errors that relate to a specific request field also include a `param` attribute.

## 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"
  }
}
```

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

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

### `forbidden`

**HTTP status:** `403`

The API key is valid but does not have permission to perform the requested action. This can occur when accessing organization-level resources with a member-level key.

### `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.

### `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.

### `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.

### `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 our [rate limits documentation](https://docs.heygen.com/reference/rate-limits) for per-endpoint limits.

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

### `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.

### `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.

Upgrade your plan in the [HeyGen dashboard](https://app.heygen.com/pricing) to access this feature.

### `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 /v1/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.

### `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.

### `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. Use a different value or delete the existing resource first.

### `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 or an instant avatar has not finished training. Poll the resource 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); safe to retry.

### `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 or when submitted content contains inappropriate content. Create a new resource that complies with our [usage policy](https://www.heygen.com/policy).

### `unlimited_mode_disabled`

**HTTP status:** `400`

The avatar does not support unlimited mode. Use a different avatar, or use Avatar IV or Avatar V.

### `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.

### `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.

### `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.

### `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.

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

Check the `message` field for details about which URL failed and why.

### `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) returned an error or was temporarily unavailable. 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.

### `gateway_timeout`

**HTTP status:** `504`

A resource referenced in your request (e.g., a URL for background audio or an image) could not be downloaded within the time limit. Verify that the URL is publicly accessible, responds quickly, and is not blocked by firewall or geo-restrictions. Retry if the target server was temporarily slow.

### `service_unavailable`

**HTTP status:** `503`

A downstream service needed to fulfill your request (e.g., the text-to-speech synthesis backend) is temporarily overloaded and did not respond in time. This is transient and not caused by your request. Back off and retry after a short delay.

### `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 /v1/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.


# For AI Agents
Source: https://developers.heygen.com/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://app.heygen.com/settings?nav=API — 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://app.heygen.com/settings?nav=API (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://app.heygen.com/settings?nav=API), 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. See [Choosing the Right Video API](/docs/choosing-the-right-video-api).
* **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://developers.heygen.com/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">
    Send a message with `auto_proceed: true` or approve the storyboard. 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.                                                                                                                  |
| `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). |
| `auto_proceed` | boolean | No       | If `true`, skip interactive review and go straight to video generation. Default: `false`.                                                         |
| `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.                                                                                             |

<Tip>
  Set `auto_proceed: true` to skip the review step entirely — the session behaves like the one-shot mode but you still get a `session_id` to track.
</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**  | Your message to the agent (1–10,000 characters).                                             |
| `avatar_id`    | string  | No       | Override avatar for this message.                                                            |
| `voice_id`     | string  | No       | Override voice for this message.                                                             |
| `files`        | array   | No       | Additional file attachments (max 20).                                                        |
| `auto_proceed` | boolean | No       | If `true`, skip remaining review steps and generate the video immediately. Default: `false`. |

### 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.",
    "auto_proceed": true
  }'
```

### 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"
  }
}
```


# Overview
Source: https://developers.heygen.com/docs/overview

Get the lay of the land on the HeyGen developer platform. See what's available across avatars, video agent, translation, streaming, MCP, and SDKs in one.

<img alt="" />

Video Agent is the fastest way to create videos programmatically. Describe what you want in plain text, and the agent handles avatar selection, scripting, scene composition, and production — all in a single API call.

## How It Works

<Steps>
  <Step title="Send a prompt">
    POST a text description to `POST /v3/video-agents`. Optionally attach files, pick an avatar, or apply a style.
  </Step>

  <Step title="Agent produces your video">
    The agent writes a script, selects visuals, and renders the video asynchronously. You receive a `session_id` immediately, and a `video_id` once generation begins.
  </Step>

  <Step title="Retrieve the result">
    Poll `GET /v3/videos/{video_id}` until `status` is `completed`, then download via `video_url`. Or use a `callback_url` to get notified automatically.
  </Step>
</Steps>

## Quick Start

<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 30-second product walkthrough for a new project management app"
    }'
  ```

  ```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 30-second product walkthrough for a new project management app"
      },
  )
  data = resp.json()["data"]
  print(data["session_id"], data["status"])
  ```

  ```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 30-second product walkthrough for a new project management app",
    }),
  });
  const { data } = await resp.json();
  console.log(data.session_id, data.status);
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": {
    "session_id": "sess_abc123",
    "status": "generating",
    "video_id": null,
    "created_at": 1711382400
  }
}
```

<Note>
  `video_id` is `null` on creation and is populated once the agent begins rendering. Poll `GET /v3/video-agents/{session_id}` to track progress and retrieve the `video_id`.
</Note>

## Two Modes of Operation

Video Agent supports two workflows depending on how much control you need:

| Mode                              | How to use                                    | Best for                                                                                                                   |
| --------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Generate** (`mode: "generate"`) | `POST /v3/video-agents` — default             | Fire-and-forget. Send a prompt, get a video. The agent auto-proceeds through the storyboard.                               |
| **Chat** (`mode: "chat"`)         | `POST /v3/video-agents` with `"mode": "chat"` | Multi-turn interaction. The agent may pause for decisions (e.g. picking a voice), supports revisions and follow-up videos. |

Both modes support the same file inputs, avatar/voice overrides, and style options.

```json Chat mode example theme={null}
{
  "prompt": "Create a product walkthrough for our new app",
  "mode": "chat"
}
```

Use `POST /v3/video-agents/{session_id}` to send follow-up messages, answer the agent's questions, or request revisions in a chat session.

## Processing Time

<Info>
  Video generation is asynchronous. Processing times depend on video length, complexity, and your plan tier.
</Info>

| Factor               | Typical Range                                                       |
| -------------------- | ------------------------------------------------------------------- |
| **Standard plans**   | 5x–10x the final video length (e.g. a 1-min video takes \~5–10 min) |
| **Enterprise plans** | Faster processing with priority queue access                        |
| **Multi-scene**      | Each scene adds to total processing time                            |
| **Peak hours**       | Processing may take longer during high-traffic periods              |

<Warning>
  If a video has been processing for more than 24 hours, something is likely wrong. Contact [HeyGen Support](https://help.heygen.com) with your `video_id`.
</Warning>

**Best practices:**

* Use `callback_url` instead of polling to reduce unnecessary API calls
* Set reasonable poll intervals (10–30 seconds) if polling
* Display a progress indicator to end users based on the 5x–10x benchmark

## Choosing the Right Video API

| Feature              | Video Agent                     | Direct Video (`v3`)    |
| -------------------- | ------------------------------- | ---------------------- |
| **Endpoint**         | `POST /v3/video-agents`         | `POST /v3/videos`      |
| **Input**            | Natural language prompt         | Structured JSON        |
| **Avatar selection** | Agent chooses (or you override) | You specify            |
| **Script writing**   | Agent writes it                 | You write it           |
| **Best for**         | Quick prototypes, simple videos | Programmatic pipelines |
| **Control level**    | Low (prompt-driven)             | High (explicit)        |

<Tip>
  Start with Video Agent. If you need precise control over script, avatar, or timing, use `POST /v3/videos` directly.
</Tip>

## Key Concepts

**Session** — Every Video Agent request creates a session (`session_id`). Sessions track the agent's work: prompt, storyboard, generated assets, and final video. Retrieve session state via `GET /v3/video-agents/{session_id}`.

**Video ID** — The `video_id` is populated once rendering begins. Poll `GET /v3/videos/{video_id}` for status and the final download URL.

**Styles** — Curated visual templates that control scene composition, pacing, and aesthetics. Browse them via `GET /v3/video-agents/styles` and pass a `style_id` to your request.

**File attachments** — Images, videos, audio, and PDFs you provide as context. The agent uses these as visual references or content sources. Pass them via the `files` array as `url`, `asset_id`, or `base64` inputs.

**Incognito mode** — Set `incognito_mode: true` to disable memory injection and extraction for a session.

## Error Handling

All Video Agent endpoints return errors in a consistent format:

```json theme={null}
{
  "error": {
    "code": "invalid_parameter",
    "message": "'prompt' is required and must be 1-10000 characters.",
    "param": "prompt",
    "doc_url": null
  }
}
```

| Status | Meaning                                                                               |
| ------ | ------------------------------------------------------------------------------------- |
| `400`  | Invalid request parameters. Check the `param` field for which field caused the error. |
| `401`  | Authentication failed. Verify your API key or Bearer token.                           |
| `429`  | Rate limit exceeded. Retry after the seconds specified in the `Retry-After` header.   |

For video-specific failures (e.g. rendering errors), check `failure_code` and `failure_message` on the video status response.


# Self-Serve Pricing
Source: https://developers.heygen.com/docs/pricing

Compare HeyGen API pricing across self-serve plans. See per-minute video costs, monthly credit allocations, and free tier limits. No credit card needed.

<img alt="" />

HeyGen's self-serve (Pay-As-You-Go) plan lets you purchase USD balance when you need it — no monthly subscription, no commitments.

## How Billing Works

When you authenticate with an **API Key** (`x-api-key` header), you are billed under the **API tier**. Usage is deducted from your prepaid USD wallet.

Check your balance at any time:

```text theme={null}
GET /v3/users/me → wallet
```

## Pricing

### Video Generation — Avatar V

Highest-fidelity engine with cross-reference-driven animation — see the [Avatar V model page](/avatar-v) for engine details. Avatar V supports Digital Twins only.

| Avatar Type  | 720p / 1080p   |
| ------------ | -------------- |
| Digital Twin | \$0.0667 / sec |

### Video Generation — Avatar IV

Default v3 engine — see the [Avatar IV model page](/avatar-iv) for engine details.

| Avatar Type   | 720p / 1080p   |
| ------------- | -------------- |
| Photo Avatar  | \$0.05 / sec   |
| Digital Twin  | \$0.0667 / sec |
| Studio Avatar | \$0.0667 / sec |

### Video Generation — Avatar III

Dedicated photo-to-video pipeline — see the [Avatar III model page](/avatar-iii) for engine details.

| Avatar Type   | 720p / 1080p   |
| ------------- | -------------- |
| Digital Twin  | \$0.0167 / sec |
| Studio Avatar | \$0.0167 / sec |
| Photo Avatar  | \$0.0433 / sec |

### Cinematic Avatar

Flat rate per video (4–15 seconds, 720p/1080p only), not billed by duration. See the [Cinematic Avatar guide](/cinematic-avatar).

| Item                   | Rate           |
| ---------------------- | -------------- |
| Cinematic Avatar video | \$7.00 / video |

### Avatar Realtime

Live streaming avatar session, billed per second of session duration (720p only). See the [Avatar Realtime guide](/avatar-realtime).

| Feature                 | Rate         |
| ----------------------- | ------------ |
| Avatar Realtime session | \$0.05 / sec |

### Video Agent

| Feature         | Rate           |
| --------------- | -------------- |
| Prompt to Video | \$0.0333 / sec |

### HyperFrames

Billed per minute of output video; the rate scales with `resolution` and `fps`. See the [HyperFrames guide](/hyperframes).

| Resolution / Frame Rate | Rate         |
| ----------------------- | ------------ |
| 1080p / 30 fps          | \$0.10 / min |
| 1080p / 60 fps          | \$0.20 / min |
| 4K / 30 fps             | \$0.15 / min |
| 4K / 60 fps             | \$0.30 / min |

### Video Translation

| Mode                 | Rate           |
| -------------------- | -------------- |
| Speed — Audio Only   | \$0.0333 / sec |
| Speed — Lip Sync     | \$0.0333 / sec |
| Precision — Lip Sync | \$0.0667 / sec |

> **Note:** Proofread mode is available on Enterprise plans only.

### Lipsync

| Mode      | Rate           |
| --------- | -------------- |
| Speed     | \$0.0333 / sec |
| Precision | \$0.0667 / sec |

### AI Clipping

Turn a long-form video into short highlight clips, billed per clip produced. See the [AI Clipping guide](/ai-clipping).

| Item           | Rate          |
| -------------- | ------------- |
| Highlight clip | \$0.15 / clip |

### Text-to-Speech

| Model             | Rate             |
| ----------------- | ---------------- |
| Speech — Starfish | \$0.000667 / sec |

### Avatar Creation

| Operation    | Rate            |
| ------------ | --------------- |
| Digital Twin | \$1.00 per call |
| Photo Avatar | \$1.00 per call |


# Quick Start
Source: https://developers.heygen.com/docs/quick-start

Generate your first AI video with the HeyGen API in minutes — authenticate, send one request, and get back an MP4.

<img alt="" />

<CardGroup>
  <Card title="Get your API key" icon="key" href="https://app.heygen.com/home?from=&nav=API">
    Create a key in Settings → API. 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>

## Your first video

<Steps>
  <Step title="Authenticate" icon="key">
    Create a key in [Settings → API](https://app.heygen.com/home?from=\&nav=API). 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>

## Pick your endpoint

<CardGroup>
  <Card title="Video Agent" icon="wand-magic-sparkles" href="/docs/video-agent">
    Prompt → finished video. **Flagship.**
  </Card>

  <Card title="Avatar Video" icon="user" href="/generate-avatar-video">
    Pick the avatar, voice, and script yourself.
  </Card>

  <Card title="Cinematic Avatar" icon="clapperboard" href="/cinematic-avatar">
    Prompt-driven cinematic shots from avatar looks.
  </Card>

  <Card title="Video Translation" icon="language" href="/docs/video-translate">
    30+ languages with voice cloning and lip-sync.
  </Card>

  <Card title="Text to Speech" icon="waveform-lines" href="/docs/voices/speech">
    Text → natural speech audio.
  </Card>

  <Card title="HyperFrames" icon="layer-group" href="/hyperframes">
    HTML/CSS/JS → motion-graphics video. **New.**
  </Card>
</CardGroup>

## 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="Limits & Pricing" icon="dollar-sign" href="/docs/pricing" />
</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 [Settings → API](https://app.heygen.com/home?from=\&nav=API).
  </Accordion>

  <Accordion title="429 Too Many Requests" icon="gauge-high">
    Rate or concurrency limit hit. Respect `Retry-After` and back off. 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://developers.heygen.com/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

See [HeyGen pricing](https://heygen.com/pricing) for credit costs.

### 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://developers.heygen.com/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 and pricing, 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://developers.heygen.com/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.

## 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://developers.heygen.com/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. 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) |
| 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. |
| `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. 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.
  </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 allowed upload size in bytes for this flow.                |
| `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 URL. No upload step needed — HeyGen fetches the file directly. Same 32 MB per-file limit as uploads.
  </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 up to 32 MB already hosted publicly.                                                                                               |
| Base64   | `{ "type": "base64", "media_type": "image/png", "data": "iVBOR..." }` | Small files, self-contained requests, no hosting needed.                                                                                 |

<Warning>
  The 32 MB per-file limit also applies to URL inputs — 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>

## 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 or video for avatar creation — 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).                        |

## 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://developers.heygen.com/docs/usage-limits

See HeyGen API rate limits by endpoint and plan tier. Includes concurrent video render quotas, request-per-minute caps, and how to request a quota increase.

<img alt="" />

## Concurrency Limits

| Plan          | Max Concurrent Video Jobs |
| :------------ | :------------------------ |
| Pay-As-You-Go | 10                        |

Concurrent jobs include any asynchronous generation in progress: [Video Agent sessions](/docs/video-agent), avatar video renders, and [video translations](/docs/video-translate). 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).

## 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 or SSML markup.

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

## 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 |
| `GET /v3/video-agents/sessions/{id}/resources`                      | 8       | 100 |

## Rate Limiting

All endpoints enforce rate limits. When exceeded, the API returns `429 Too Many Requests` with a `Retry-After` header indicating the number of seconds to wait before retrying. See [`rate_limit_exceeded`](/docs/error-codes#rate-limit-exceeded) for the error shape and recommended backoff strategy.


# Prompt to Video
Source: https://developers.heygen.com/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>

[`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.

### Request body

| Parameter      | Type   | Required | Description                                                                                                                                                                   |
| -------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt`       | string | **Yes**  | Text description of the video you want (1–10,000 characters).                                                                                                                 |
| `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). |
| `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.                                                                                                                         |

### 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. 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
  }
}
```

## Tips for better results

1. **Be descriptive in your prompt.** Include details about tone, target audience, visual style, and pacing — the agent uses all of this to make better decisions.
2. **Attach reference files.** Pass slides, images, or documents in the `files` array to give the agent visual context.
3. **Use `orientation`** when you know the target platform (e.g. `"portrait"` for mobile/social, `"landscape"` for presentations).
4. **Apply a style** for consistent visual branding across videos. See [Styles & References](/docs/styles-and-references) and [`GET /v3/video-agents/styles`](/reference/list-video-agent-styles).
5. **Pin a specific avatar or voice** with `avatar_id` (see [Avatars](/docs/avatars)) and `voice_id` (see [Browse Voices](/docs/voices/search-voices)) for brand consistency, or omit them to let the agent choose.
6. **Need multi-turn revisions?** Use [Interactive Sessions](/docs/interactive-sessions) instead of one-shot prompts.


# Video Translation -  Speed
Source: https://developers.heygen.com/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      |
| `disable_music_track`       | `false`   | Strips background music from output                                |
| `enable_speech_enhancement` | `false`   | Improves speech audio quality                                      |
| `enable_caption`            | `false`   | Generates captions alongside the video                             |
| `brand_voice_id`            | —         | Apply a custom brand voice (requires setup)                        |
| `callback_url`              | —         | [Webhook](/docs/webhooks) URL notified on completion or failure    |
| `callback_id`               | —         | Your own ID, echoed back in the webhook payload                    |

## 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 voice IDs to draw from. 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
    }
  }'
```

## Captions

To enable captions, set `enable_caption: true` in the translation request. Once completed, download them:

```bash theme={null}
curl --request GET \
  --url 'https://api.heygen.com/v3/video-translations/<video_translation_id>/caption?format=srt' \
  --header 'accept: application/json' \
  --header 'x-api-key: <your-api-key>'
```

Supported formats: `srt`, `vtt`.

## 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://developers.heygen.com/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                       |
| `disable_music_track`       | `false`   | Strips background music from output                                                 |
| `enable_speech_enhancement` | `false`   | Improves speech audio quality                                                       |
| `enable_caption`            | `false`   | Generates captions alongside the video                                              |
| `brand_voice_id`            | —         | Apply a custom brand voice (requires setup)                                         |
| `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

To enable captions, set `enable_caption: true` in the translation request. Once completed, download them:

```bash theme={null}
curl --request GET \
  --url 'https://api.heygen.com/v3/video-translations/<video_translation_id>/caption?format=srt' \
  --header 'accept: application/json' \
  --header 'x-api-key: <your-api-key>'
```

Supported formats: `srt`, `vtt`.

## 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>'
```

## 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://developers.heygen.com/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>


# Voices
Source: https://developers.heygen.com/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 [Text to 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 voice engine (e.g. `"starfish"`). 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 SSML pause/break 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 from audio samples instead, use [`POST /v3/voices/clone`](/reference/clone-a-voice).

<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 speech directly without an avatar, use [Text to 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.      |


# Browse Voices
Source: https://developers.heygen.com/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 [Clone a Voice](/reference/clone-a-voice). For TTS, see [Text to 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 voice engine (e.g. `"starfish"`). 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 SSML pause/break 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"
```

### TTS-Compatible Voices Only

To get voices that work with [`POST /v3/voices/speech`](/reference/generate-speech), filter by the `starfish` engine:

```bash curl theme={null}
curl -X GET "https://api.heygen.com/v3/voices?engine=starfish" \
  -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"
```


# Text to Speech
Source: https://developers.heygen.com/docs/voices/speech

Convert text to audio using any HeyGen voice via the Text-to-Speech API. Useful for previewing voices, generating standalone audio, or pre-rendering speech for.

<img alt="" />

Full schema: [`POST /v3/voices/speech`](/reference/generate-speech).

<Warning>
  Starfish only works with **Starfish-compatible voices**. Not all HeyGen voices support this engine. Use [`GET /v3/voices?engine=starfish`](/reference/list-voices) — see [Browse Voices](/docs/voices/search-voices) — to get a list of compatible voices before calling this endpoint.
</Warning>

## Quick Example

<CodeGroup>
  ```bash curl 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"
    }'
  ```

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

  resp = requests.post(
      "https://api.heygen.com/v3/voices/speech",
      headers={"X-Api-Key": HEYGEN_API_KEY},
      json={
          "text": "Hello from HeyGen!",
          "voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
      },
  )
  data = resp.json()["data"]
  print(data["audio_url"], data["duration"])
  ```

  ```javascript Node.js theme={null}
  const resp = await fetch("https://api.heygen.com/v3/voices/speech", {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.HEYGEN_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      text: "Hello from HeyGen!",
      voice_id: "1bd001e7e50f421d891986aad5c8bbd2",
    }),
  });
  const { data } = await resp.json();
  console.log(data.audio_url, data.duration);
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": {
    "audio_url": "https://files.heygen.ai/audio/req_xyz789.mp3",
    "duration": 2.4,
    "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 }
    ]
  }
}
```

## Finding a Compatible Voice

Before calling this endpoint, find a Starfish-compatible `voice_id`:

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/voices?engine=starfish&language=English&gender=female" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

See [Browse Voices](/docs/voices/search-voices) for full filtering and pagination details.

## Parameters

| Parameter    | Type   | Required | Default       | Description                                                                   |
| ------------ | ------ | -------- | ------------- | ----------------------------------------------------------------------------- |
| `text`       | string | Yes      | —             | Text to synthesize (1–5,000 characters).                                      |
| `voice_id`   | string | Yes      | —             | A Starfish-compatible voice ID.                                               |
| `input_type` | string | No       | `"text"`      | `"text"` for plain text or `"ssml"` for SSML markup.                          |
| `speed`      | number | No       | `1.0`         | Speed multiplier (0.5–2.0).                                                   |
| `language`   | string | No       | auto-detected | Base language code (e.g. `"en"`, `"pt"`, `"zh"`). Auto-detected when omitted. |
| `locale`     | string | No       | —             | BCP-47 locale tag (e.g. `"en-US"`, `"pt-BR"`). Overrides `language` when set. |

## Response Fields

| Field             | Type           | Description                                                                    |
| ----------------- | -------------- | ------------------------------------------------------------------------------ |
| `audio_url`       | string         | URL of the generated audio file.                                               |
| `duration`        | number         | Duration of the audio in seconds.                                              |
| `request_id`      | string or null | Unique identifier for this generation request.                                 |
| `word_timestamps` | array or null  | Word-level timing data — each entry has `word`, `start`, and `end` in seconds. |

## SSML Support

For finer control over pronunciation, pauses, and emphasis, set `input_type` to `"ssml"`. Check the `support_pause` field on the voice object returned by [`GET /v3/voices`](/reference/list-voices) to confirm whether the selected voice supports SSML `<break>` tags.

This also works with [`POST /v3/videos`](/reference/create-video) when generating videos from scripts, letting you control pacing and pauses directly within the narration.\\

```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": "<speak>Welcome to HeyGen. <break time=\"0.5s\"/> Let us get started.</speak>",
    "voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
    "input_type": "ssml"
  }'
```


# Webhook Events
Source: https://developers.heygen.com/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.                |

## 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://developers.heygen.com/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                                                                                                                |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `Heygen-Signature` | Hex-encoded HMAC-SHA256 of the raw request body, computed with your endpoint `secret`.                                     |
| `Heygen-Timestamp` | Unix timestamp (seconds) when the event was dispatched. Reject deliveries older than \~5 minutes to defend against replay. |
| `Heygen-Event-Id`  | Unique ID for this delivery — use to de-duplicate on your side (events can be redelivered on retry).                       |

<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;
  const MAX_SKEW_SECONDS = 300;

  app.post("/webhooks/heygen", (req, res) => {
    const signature = req.header("Heygen-Signature");
    const timestamp = req.header("Heygen-Timestamp");

    if (!signature || !timestamp) return res.status(400).send("missing headers");
    if (Math.abs(Date.now() / 1000 - Number(timestamp)) > MAX_SKEW_SECONDS) {
      return res.status(400).send("stale timestamp");
    }

    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
  import time
  from flask import Flask, abort, request

  app = Flask(__name__)
  SECRET = os.environ["HEYGEN_WEBHOOK_SECRET"].encode()
  MAX_SKEW_SECONDS = 300

  @app.post("/webhooks/heygen")
  def heygen_webhook():
      signature = request.headers.get("Heygen-Signature", "")
      timestamp = request.headers.get("Heygen-Timestamp", "")
      if not signature or not timestamp:
          abort(400, "missing headers")
      if abs(time.time() - int(timestamp)) > MAX_SKEW_SECONDS:
          abort(400, "stale timestamp")

      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 / replay defense:** a single event can be delivered more than once (retry after a transient failure). De-duplicate on `Heygen-Event-Id` — this is your **primary replay defense**, since the signature covers the body only.
* **Stale-delivery rejection:** treat `Heygen-Timestamp` as defense-in-depth — reject deliveries where it's more than \~5 minutes old. (Not a substitute for event-id dedup: an attacker who captured a valid body could replay it with a fresh timestamp header without breaking the signature.)

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.


# E-commerce Product Videos
Source: https://developers.heygen.com/e-commerce-product-videos

Turn product catalogs into avatar-led e-commerce videos via the HeyGen API. One video per SKU, automatically refreshed when prices, photos, or copy change.

## The Problem

Product pages with video significantly outperform those without — higher engagement, longer time on page, and better conversion rates. But with thousands of SKUs, creating individual product videos is impossible with traditional production. Most e-commerce stores have great product images but zero product video.

## How It Works

```
Product catalog (name, description, images) → Prompt per product → Batch generate → Embed on product pages
```

Your product database already has everything Video Agent needs: name, description, features, and images. Turn that structured data into video at scale.

## Build It

<Steps>
  <Step title="Pull product data">
    ```python theme={null}
    # From your catalog API, database, or CSV
    products = [
        {
            "name": "CloudWalk Pro Running Shoes",
            "category": "Footwear",
            "price": "$129",
            "description": "Lightweight performance running shoe with responsive foam midsole and breathable knit upper.",
            "features": [
                "ResponsiveFoam midsole — 30% more energy return",
                "Breathable knit upper — keeps feet cool on long runs",
                "Carbon fiber plate — propels you forward",
                "Only 7.2 oz — one of the lightest in its class",
            ],
            "images": [
                "https://cdn.store.com/products/cloudwalk-hero.jpg",
                "https://cdn.store.com/products/cloudwalk-side.jpg",
                "https://cdn.store.com/products/cloudwalk-sole.jpg",
            ],
        },
        # ... hundreds more
    ]
    ```
  </Step>

  <Step title="Build category-aware prompts">
    Consider using different video styles for different product categories. For example, fashion might benefit from energy and aspiration, while electronics might call for clarity and specs.

    ```python theme={null}
    CATEGORY_STYLES = {
        "Footwear": {
            "tone": "energetic and aspirational, like a Nike ad",
            "focus": "performance benefits, how it feels, lifestyle context",
            "duration": "20 seconds",
        },
        "Electronics": {
            "tone": "clear, knowledgeable, like a trusted tech reviewer",
            "focus": "specs that matter, real-world use cases, comparisons",
            "duration": "30 seconds",
        },
        "Home & Kitchen": {
            "tone": "warm, practical, like a friend recommending a product",
            "focus": "solving everyday problems, quality materials, ease of use",
            "duration": "25 seconds",
        },
    }

    def build_product_prompt(product):
        style = CATEGORY_STYLES.get(product["category"], CATEGORY_STYLES["Electronics"])
        features = "\n".join(f"- {f}" for f in product["features"])

        return f"""Create a {style['duration']} product video for {product['name']}.

    Product: {product['name']} — {product['price']}
    {product['description']}

    Key features:
    {features}

    Video structure:
    - Hook (3s): Bold statement about the key benefit
    - Features (70% of duration): Walk through 2-3 standout features
      with text overlays. Reference the attached product images.
    - CTA (3s): "Available now for {product['price']}"

    Tone: {style['tone']}
    Focus on: {style['focus']}
    Use the attached product images as visual reference.
    """
    ```
  </Step>

  <Step title="Batch generate with rate limiting">
    ```python theme={null}
    import requests
    import time

    video_jobs = []

    for product in products:
        prompt = build_product_prompt(product)
        files = [{"type": "url", "url": img} for img in product["images"][:5]]

        resp = requests.post(
            "https://api.heygen.com/v3/video-agents",
            headers={
                "X-Api-Key": HEYGEN_API_KEY,
                "Content-Type": "application/json",
            },
            json={"prompt": prompt, "files": files},
        )
        video_jobs.append({
            "product_id": product["name"],
            "video_id": resp.json()["data"]["video_id"],
        })
        time.sleep(5)

    print(f"Submitted {len(video_jobs)} product videos")
    ```

    Then poll for completion and match video URLs back to product IDs.
  </Step>

  <Step title="Embed on product pages">
    Once rendered, add video URLs to your product data and display on your store.

    ```python theme={null}
    # After polling all videos to completion:
    for job in video_jobs:
        update_product_page(
            product_id=job["product_id"],
            video_url=job["video_url"],
            thumbnail_url=job["thumbnail_url"],
        )
    ```
  </Step>
</Steps>

## Video Types by Use Case

| Video type               | Duration | When to use                              |
| ------------------------ | -------- | ---------------------------------------- |
| **Product showcase**     | 15–30s   | Product listing page — show key features |
| **How-to-use**           | 30–60s   | Complex products — demonstrate usage     |
| **Comparison**           | 30–45s   | "Pro vs Standard" — help buyers choose   |
| **Unboxing/first look**  | 20–30s   | New arrivals — build excitement          |
| **Customer testimonial** | 30s      | Social proof — pair with review text     |

## Scaling to Thousands of Products

For large catalogs, consider prioritizing by business impact:

1. **Top sellers first** — highest traffic pages get the most ROI from video
2. **High-margin products** — the conversion lift matters most here
3. **New arrivals** — video helps customers understand unfamiliar products
4. **Products with high return rates** — better video = more informed purchases = fewer returns

```python theme={null}
# Prioritize by revenue impact
products.sort(key=lambda p: p["monthly_revenue"], reverse=True)
top_products = products[:100]  # Start with top 100
```

## A/B Testing

Generate multiple video styles for the same product and measure which converts better:

```python theme={null}
variants = [
    {"style": "presenter explaining features", "label": "explainer"},
    {"style": "fast-paced montage with text overlays only", "label": "montage"},
    {"style": "customer testimonial style, first-person", "label": "testimonial"},
]
```

## Variations

* **Seasonal campaigns:** Regenerate product videos with holiday-themed prompts
* **Multi-language:** Translate for international storefronts using [Video Translation](/cookbook/video-agent/multilingual-content)
* **Social ads:** Generate portrait (9:16) versions for social media advertising
* **Bundle videos:** Combine multiple products into "complete the look" or "bundle" showcase videos

***

## Next Steps

<CardGroup>
  <Card title="Real Estate Listings" icon="house" href="/cookbook/video-agent/real-estate-listings">
    Same catalog-to-video pattern, applied to properties.
  </Card>

  <Card title="Social Media Pipeline" icon="share-nodes" href="/cookbook/video-agent/social-media-pipeline">
    Distribute product videos across social platforms.
  </Card>
</CardGroup>


# Endpoint Version Comparison
Source: https://developers.heygen.com/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.             |

## Feature Comparison

| Feature                         | v1                                | v2                                     | v3                              |
| ------------------------------- | --------------------------------- | -------------------------------------- | ------------------------------- |
| **Avatar Video Generation**     | ✅ `POST /v1/video/generate`       | ✅ `POST /v2/video/generate`            | ✅ `POST /v3/videos`             |
| **Video Agent**                 | ✅ `POST /v1/video-agent/generate` | —                                      | ✅ `POST /v3/video-agents`       |
| **Studio API (multi-scene)**    | —                                 | ✅ `POST /v2/video/generate`            | ⏳ Not yet available             |
| **Template API (variables)**    | —                                 | ✅ `POST /v2/template/{id}/generate`    | ✅ `POST /v3/templates/{id}`     |
| **Batch Video Creation**        | —                                 | —                                      | ✅ `POST /v3/videos/batches`     |
| **Video Translation**           | —                                 | ✅ `POST /v2/video_translate/translate` | ✅ `POST /v3/video-translations` |
| **Lipsync**                     | —                                 | —                                      | ✅ `POST /v3/lipsyncs`           |
| **Voice Design (prompt-based)** | —                                 | —                                      | ✅ `POST /v3/voices`             |
| **Text-to-Speech (Starfish)**   | —                                 | —                                      | ✅ `POST /v3/voices/speech`      |
| **Webhook Management**          | —                                 | callback\_url param only               | ✅ Full CRUD + secret rotation   |
| **Asset Upload**                | ✅ `POST /v1/video/upload`         | —                                      | ✅ `POST /v3/assets`             |
| **List Avatars**                | ✅ `GET /v1/avatar.list`           | ✅ `GET /v2/avatars`                    | ✅ `GET /v3/avatars`             |
| **List Voices**                 | ✅ `GET /v1/voice.list`            | ✅ `GET /v2/voices`                     | ✅ `GET /v3/voices`              |
| **Poll Video Status**           | ✅ `GET /v1/video_status.get`      | —                                      | ✅ `GET /v3/videos/{id}`         |
| **User / Account Info**         | ✅ `GET /v1/user/me`               | —                                      | ✅ `GET /v3/users/me`            |

> On v3, avatar video generation supports per-request rendering-engine selection — Avatar III, IV, or V — via the `engine` field. See [Models](/models).

## v3-Only Features (No Legacy Equivalent)

| Feature                   | Endpoint                              | Notes                                             |
| ------------------------- | ------------------------------------- | ------------------------------------------------- |
| Lipsync                   | `POST /v3/lipsyncs`                   | Speed and precision modes                         |
| Voice Design              | `POST /v3/voices`                     | Design a voice from a text prompt                 |
| Text-to-Speech (Starfish) | `POST /v3/voices/speech`              | New TTS engine                                    |
| Proofread Workflow        | `/v3/video-translations/proofreads/*` | SRT review/edit before final render               |
| Webhook Management        | `/v3/webhooks/endpoints/*`            | Full CRUD, secret rotation, event log             |
| Video Agent (full)        | `/v3/video-agents/*`                  | Styles, references, chat mode                     |
| Avatar Realtime           | `POST /v3/avatar-realtime`            | Low-latency streaming avatar sessions             |
| HyperFrames               | `POST /v3/hyperframes/renders`        | Render HTML/CSS/JS projects to video              |
| Background Removal        | `/v3/background-removals`             | Managed background-removal jobs                   |
| Audio Search              | `GET /v3/audio/sounds`                | Background-music and sound-effects catalog        |
| Batch Video Creation      | `POST /v3/videos/batches`             | Submit up to 100 videos in one request            |
| Avatar Consent Flow       | `POST /v3/avatars/{group_id}/consent` | Required for custom avatar creation               |
| Cursor-based Pagination   | All v3 list endpoints                 | Standard across every resource                    |
| Unified Asset Input       | All v3 creation endpoints             | `url` / `asset_id` / `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 only  | Managed endpoints, event types, signed payloads           |
| Video request body | Flat object                | Discriminated union (`type: "avatar"` or `type: "image"`) |
| Voice fallback     | `voice_id` always required | Falls back to avatar's default voice when omitted.        |

## Migration Checklist

* Inventory all v1/v2 endpoint calls in your codebase
* Replace `POST /v1/video/generate` and `POST /v2/video/generate` with `POST /v3/videos`
* Replace `GET /v1/video_status.get` with `GET /v3/videos/{id}`
* Replace avatar and voice listing endpoints with v3 equivalents
* Replace `POST /v1/video/upload` with `POST /v3/assets`
* Replace `GET /v1/user/me` with `GET /v3/users/me`
* Migrate video translation calls to `/v3/video-translations`
* Update webhook handling from `callback_url` to managed `/v3/webhooks/endpoints`
* Update pagination logic to cursor-based where applicable
* **Template API:** now available on v3 — migrate `POST /v2/template/{id}/generate` to [`POST /v3/templates/{id}`](/reference/generate-video-from-template)
* **Flag:** Studio API (multi-scene) remains v2-only for now; monitor the [v3 changelog](/changelog) for a replacement
* Test all migrated endpoints in staging before October 31, 2026


# Examples
Source: https://developers.heygen.com/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://developers.heygen.com/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.


# Digital Twin
Source: https://developers.heygen.com/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.

### 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    | `4k`, `1080p` (recommended), or `720p`                                                                           |
| `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://developers.heygen.com/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. Renders are billed per minute of output — rates are on the [self-serve](/docs/pricing#hyperframes) and [enterprise](/docs/enterprise-pricing#hyperframes) pricing pages. 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`. 4k is billed at 1.5× — see [pricing](/docs/pricing#hyperframes)          |
| `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://developers.heygen.com/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://developers.heygen.com/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. Billed per minute of output. 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://developers.heygen.com/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="" />

## 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  | `4k`, `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://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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 — the interactive counterpart to [Avatar Realtime](/avatar-realtime), which is built for one-way **broadcast** streaming.

Unlike Avatar Realtime — where your application owns STT and the LLM and HeyGen only renders the face — LiveAvatar can run the whole conversational loop for you: 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://developers.heygen.com/mcp/claude-code

Connect HeyGen to Claude Code via MCP. Generate avatar videos, translate clips, and run lipsync from your terminal coding workflow with natural-language.

Connect HeyGen's Video Agent to Claude Code to generate AI avatar videos directly from your terminal. Once configured, Claude Code can script, render, and deliver videos through natural-language prompts without leaving your development workflow.

## Prerequisites

* Claude Code installed ([installation guide](https://docs.claude.com/en/docs/claude-code/overview))
* Node.js installed (required for MCP server resolution)
* A HeyGen account with Video Agent access

## Adding the MCP Server

Run the following command in your terminal (not inside the Claude Code CLI):

```text theme={null}
claude mcp add --transport http heygen https://mcp.heygen.com/mcp/v1/
```

To make the server available across all projects, add the `-s user` scope flag:

```text theme={null}
claude mcp add --transport http -s user heygen https://mcp.heygen.com/mcp/v1/
```

### Alternative: Direct Config Edit

You can also add the server by editing `~/.claude.json` directly:

```text theme={null}
{
  "mcpServers": {
    "heygen": {
      "type": "http",
      "url": "https://mcp.heygen.com/mcp/v1/"
    }
  }
}
```

Restart Claude Code after editing the config file.

## Authentication

On first use, Claude Code will prompt you to authenticate with HeyGen. Run `/mcp` inside Claude Code and follow the browser-based OAuth flow to authorize access.

## Verifying the Connection

After setup, confirm the server is active:

```text theme={null}
claude mcp list
```

Or from inside Claude Code:

```text theme={null}
/mcp
```

You should see `heygen` listed with a `connected` status.

## Usage

Once connected, prompt Claude Code with a video generation request:

```text theme={null}
Generate a 60-second explainer video about our new API endpoints using HeyGen.
```

Claude Code will call HeyGen's Video Agent to handle scripting, avatar selection, and rendering. Completed videos are accessible from the **Projects** page in your HeyGen dashboard.

### Loading HeyGen Skills (Recommended)

For better prompt structure and higher-quality output, instruct Claude Code to read HeyGen's prompt engineering guidelines before generating:

```text theme={null}
Before writing any video prompts, read the HeyGen skills at:
https://github.com/heygen-com/skills

Follow SKILL.md, references/prompt-optimizer.md, and references/video-agent.md
to structure each prompt with scenes, timing, visual style, and copy rules.
```

## Scoping

| Scope           | Flag      | Config Location                  | Availability                  |
| :-------------- | :-------- | :------------------------------- | :---------------------------- |
| Local (default) | none      | `.mcp.json` in project directory | Current project only          |
| User            | `-s user` | `~/.claude.json`                 | All projects for current user |


# Claude Web
Source: https://developers.heygen.com/mcp/claude-web

Connect HeyGen to Claude via MCP and generate AI avatar videos directly inside the Claude chat. Covers connector setup, available tools, and example prompts.

## Prerequisites

* An active Claude paid plan (required for custom connectors)
* A HeyGen account (Creator plan or above recommended for full video generation access)

## Setup

### 1. Register the Connector

Navigate to **+** → **Connector** → **Manage Connector** → **+ Add custom connector**.

Set the connector name to `HeyGen` and provide the following remote MCP server URL:

```text theme={null}
https://mcp.heygen.com/mcp/v1/
```

<Frame>
  <img alt="H Cvxlz DWIA Awx O6" />
</Frame>

<Frame>
  <img alt="H Cvy Fxba UAA0C Gl" />

  <img alt="H Cvy UKI Wo A Ale2x" />
</Frame>

### 2. Authenticate

After saving the connector, click **Connect**. You will be redirected to HeyGen's authorization page. Approve the requested access to complete the OAuth flow.

<Frame>
  <img alt="H Cvz Fgb Xmaa7t Vo" />

  <img alt="H Cvz S Bd Xk A Ek SZL" />
</Frame>

### 3. Configure Permissions (Optional)

To avoid repeated permission prompts, set the HeyGen connector permissions to **Always Allow**.

## Usage

Open a new Claude chat and provide a video generation prompt. Example:

```text theme={null}
Generate a video using HeyGen MCP about the difference between Skills and MCP.
```

Claude will handle avatar selection, script generation, and video rendering via the HeyGen API. Completed videos are also accessible from the **Projects** page in your HeyGen dashboard.

<Frame>
  <img alt="H Cvws P0W8A Eb Nk G" />
</Frame>

<Frame>
  <img alt="H Cvw2e2xk A Ae8o K" />
</Frame>

## Limitations

| Constraint       | Detail                                                                        |
| ---------------- | ----------------------------------------------------------------------------- |
| HeyGen Free Tier | Limited video generation credits. Upgrade to Creator plan for production use. |
| Claude Free Tier | Custom connectors are not available. A paid Claude subscription is required.  |


# Cursor
Source: https://developers.heygen.com/mcp/cursor

Add HeyGen to Cursor via the marketplace or a custom MCP server. Generate AI avatar videos from natural-language prompts without leaving your editor.

## Prerequisites

* Cursor installed (latest version recommended)
* A HeyGen account with Video Agent access

## Install from the Cursor Marketplace (Recommended)

HeyGen is listed in the Cursor marketplace, so setup is one click.

<Steps>
  <Step title="Open the HeyGen listing">
    Go to [cursor.com/marketplace/heygen](https://cursor.com/marketplace/heygen) and sign in to Cursor if prompted.
  </Step>

  <Step title="Add it to Cursor">
    Click **Add**. Cursor opens with the HeyGen MCP server pre-filled — confirm to install it.
  </Step>

  <Step title="Verify">
    Open **Cursor Settings → MCP** (or **Tools & Integrations**) and confirm **HeyGen** is listed with its tools enabled.
  </Step>
</Steps>

## Add Manually (Alternative)

To configure it yourself, add HeyGen under **Cursor Settings → MCP → Add new MCP server**, or edit `~/.cursor/mcp.json` directly:

```json theme={null}
{
  "mcpServers": {
    "heygen": {
      "url": "https://mcp.heygen.com/mcp/v1/"
    }
  }
}
```

If you already have other MCP servers configured, add `heygen` alongside them inside the existing `mcpServers` block.

## Authentication

On first tool use, Cursor opens a browser-based OAuth flow. Sign in to HeyGen and approve access to link the connector to your account — no API key required.

## Usage

In Cursor's chat (Agent mode), prompt a video generation request:

```text theme={null}
Generate a 60-second explainer video about our new API release using HeyGen.
```

Cursor calls HeyGen's tools to handle scripting, avatar selection, and rendering. Completed videos are also accessible from the **Projects** page in your HeyGen dashboard.

## Limitations

| Constraint       | Detail                                                                          |
| ---------------- | ------------------------------------------------------------------------------- |
| HeyGen Free Tier | Limited video generation credits. Upgrade to Creator plan for production use.   |
| OAuth required   | The connector authenticates via OAuth against your HeyGen account on first use. |


# Gemini CLI
Source: https://developers.heygen.com/mcp/gemini-cli

Wire HeyGen into Gemini CLI via MCP. Generate AI avatar videos from natural-language prompts in your terminal as part of any development or content workflow.

## Prerequisites

* Gemini CLI installed (`npm install -g @google/gemini-cli@latest`)
* A HeyGen account with Video Agent access

## Adding the MCP Server

Open your Gemini CLI settings file and add the HeyGen server under the `mcpServers` key.

**Global (all projects):** `~/.gemini/settings.json`

**Project-scoped:** `.gemini/settings.json` in your project root

```json theme={null}
{
  "mcpServers": {
    "heygen": {
      "httpUrl": "https://mcp.heygen.com/mcp/v1/"
    }
  }
}
```

If you already have other MCP servers configured, add `heygen` alongside them inside the existing `mcpServers` block.

Restart Gemini CLI after saving the file.

## Verifying the Connection

Launch Gemini CLI and run:

```text theme={null}
/mcp
```

You should see `heygen` listed under connected MCP servers with its available tools displayed.

## Authentication

On first tool invocation, Gemini CLI will prompt you to authorize access to your HeyGen account through a browser-based OAuth flow. Follow the prompt to complete authentication.

## Usage

Once connected, prompt Gemini CLI with a video generation request:

```text theme={null}
Generate a 60-second explainer video about our new API release using HeyGen.
```

Gemini will call HeyGen's Video Agent to handle scripting, avatar selection, and rendering. Completed videos are accessible from the **Projects** page in your HeyGen dashboard.

### Loading HeyGen Skills (Recommended)

For better prompt structure and higher-quality output, instruct Gemini to reference HeyGen's prompt engineering guidelines before generating:

```text theme={null}
Before writing any video prompts, read the HeyGen skills at:
https://github.com/heygen-com/skills

Follow SKILL.md, references/prompt-optimizer.md, and references/video-agent.md
to structure each prompt with scenes, timing, visual style, and copy rules.
```

## Configuration Scoping

| Scope   | File Location                          | Availability         |
| ------- | -------------------------------------- | -------------------- |
| Global  | `~/.gemini/settings.json`              | All projects         |
| Project | `.gemini/settings.json` (project root) | Current project only |


# Grok
Source: https://developers.heygen.com/mcp/grok

Connect HeyGen to Grok with a custom MCP connector, and add HyperFrames from Grok's connector directory. Generate AI avatar videos and render programmatic video without leaving the Grok chat.

Grok supports two HeyGen connectors. Add **HeyGen** as a custom connector to generate avatar videos, and add **HyperFrames by HeyGen** — an official, listed connector — to render programmatic HTML video. Both authenticate with OAuth and draw on your existing HeyGen plan's credits — no API key required.

## Prerequisites

* A Grok account with connector support (custom connectors require a paid Grok plan)
* A HeyGen account (Creator plan or above recommended for full video generation access)

## Connect HeyGen (Custom Connector)

HeyGen isn't listed in Grok's connector directory yet, so add it as a custom connector with the remote MCP server URL.

<Steps>
  <Step title="Open the connector menu">
    In the Grok prompt bar, click **+** → **Add connector**.
  </Step>

  <Step title="Choose Custom">
    In the **New Connector** dialog, select **Custom — Add your own custom connector**.
  </Step>

  <Step title="Enter the HeyGen MCP endpoint">
    Set **Name** to `HeyGen` and **Server URL** to the remote MCP server URL, then click **Add Connector**:

    ```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.
  </Step>
</Steps>

For the full set of tools this unlocks — video generation, avatars, voices, translation, lip-sync, and more — see the [MCP overview](/mcp/overview).

## Connect HyperFrames (Official Connector)

[HyperFrames](/hyperframes) is an official connector in Grok's directory, so there's nothing to paste — just search for it.

<Steps>
  <Step title="Open the connector directory">
    Click **+** → **Add connector** to open the **New Connector** dialog.
  </Step>

  <Step title="Search for HyperFrames">
    Type `hyp` in the search box. **HyperFrames by HeyGen** appears under **Productivity** — select it.
  </Step>

  <Step title="Connect">
    Click **Connect** and approve access via OAuth to link HyperFrames to your account.
  </Step>
</Steps>

Once connected, ask Grok to build and render a programmatic video project — HyperFrames turns a self-contained HTML composition into an MP4, WebM, or MOV, ideal for motion graphics and data-driven visuals. See the [HyperFrames guide](/hyperframes) for what it can produce.

## Usage

Open a new Grok chat and prompt a request. For example:

```text theme={null}
Generate a 30-second product explainer video with HeyGen.
```

```text theme={null}
Use HyperFrames to render a data-driven motion graphic of our Q2 revenue.
```

Grok calls the connector's tools to handle scripting, avatar selection, rendering, and more. Completed HeyGen videos are also accessible from the **Projects** page in your HeyGen dashboard.

## Limitations

| Constraint       | Detail                                                                           |
| ---------------- | -------------------------------------------------------------------------------- |
| Grok plan        | Custom connectors require a paid Grok plan.                                      |
| HeyGen Free Tier | Limited video generation credits. Upgrade to Creator plan for production use.    |
| OAuth required   | Both connectors authenticate via OAuth against your HeyGen account on first use. |


# Lovable
Source: https://developers.heygen.com/mcp/lovable

Connect HeyGen to Lovable as a custom MCP chat connector. Generate AI avatar videos from prompts while you build apps in Lovable.

## Prerequisites

* A Lovable account
* A HeyGen account with Video Agent access

## Add the Connector

Lovable supports custom MCP servers as **chat connectors** — per-user connections that give Lovable's chat context while you build.

<Steps>
  <Step title="Open chat connectors">
    Go to **Connectors → Chat connectors**. You can also reach this from the **+** menu next to the prompt input, or via the command palette (**Cmd/Ctrl+K**).
  </Step>

  <Step title="Add a custom MCP server">
    Choose **Add custom MCP server**, name it `HeyGen`, and enter the remote MCP server URL:

    ```text theme={null}
    https://mcp.heygen.com/mcp/v1/
    ```
  </Step>

  <Step title="Authenticate with OAuth">
    Save and connect, then complete the one-time OAuth sign-in to HeyGen to approve access — no API key required.
  </Step>
</Steps>

## Usage

In Lovable's chat, prompt a video generation request:

```text theme={null}
Generate a short product walkthrough video with HeyGen for this app.
```

Lovable calls HeyGen's tools to handle scripting, avatar selection, and rendering. Completed videos are accessible from the **Projects** page in your HeyGen dashboard.

<Note>
  Custom MCP servers in Lovable are **per-user** connections — they are personal, not shared with your workspace, and provide context to Lovable's chat during app creation. They are not bundled into your deployed app. See Lovable's [Integrations overview](https://docs.lovable.dev/integrations/introduction) for details.
</Note>


# Manus
Source: https://developers.heygen.com/mcp/manus

Manus agents can generate fully scripted AI avatar videos through the HeyGen MCP connection. Supports automated schedules and unattended video production runs.

## Prerequisites

* A [Manus](https://manus.im/app) account with access to Manus Computer (Agents)
* A HeyGen account with Video Agent access

## Connecting HeyGen

In Manus, go to **Connect Your Tools**, search for `HeyGen`, and click **Connect**. You will be prompted to authorize access to your HeyGen account.

```text theme={null}
https://manus.im/app
```

Once authorized, HeyGen tools become available to any Manus agent.

<Frame>
  <img alt="Hero5f Ka IA Amxxy" />
</Frame>

<Frame>
  <img alt="Hero9km X0A Ayi PG" />

  <img alt="HERO 6NWAAABPX" />
</Frame>

<Frame>
  <img alt="HERPC Rz Wc A Ae Ifz" />
</Frame>

## Using HeyGen in Manus Computer

Open **Manus Computer** under the Agents section and select the HeyGen tools for your agent.

```text theme={null}
https://manus.im/app/agents
```

<Frame>
  <img alt="HER Qw G6WEAA Fqh H" />
</Frame>

From here, you write a natural-language prompt describing what you want the agent to produce. Manus handles orchestration — it will call HeyGen's Video Agent to script, render, and deliver the output.

**Example prompt:**

```text theme={null}
Every morning at 7 AM Pacific, automatically produce three short (~60-second)
AI-generated videos summarizing the top viral tech stories, then deliver them
in a neat package. Use HeyGen Video Agent.
```

## Improving Output with HeyGen Skills

For higher-quality video prompts, you can instruct the Manus agent to reference HeyGen's open-source prompt engineering guidelines before generating anything. Add the following to your agent instructions:

```text theme={null}
Before writing any prompts, read the HeyGen skills at:

    https://github.com/heygen-com/skills

Specifically read SKILL.md, references/prompt-optimizer.md, and
references/video-agent.md. Follow those guidelines to structure
each video prompt — scene types, visual style, timing, copy rules,
media selection, and the optimization checklist.

Each prompt must be:
- Thesis-driven (one argument per video, not a listicle)
- Scene-by-scene with VO, visuals, and timestamps
- ~150 words of voiceover total (~60 seconds)
- Under 10,000 characters
- Any real quotes, numbers, or company names marked CRITICAL
  for on-screen text
```

<Frame>
  <img alt="HER Sdc Bw A Aj9f8" />
</Frame>


# OpenAI
Source: https://developers.heygen.com/mcp/open-ai

Add HeyGen video generation to OpenAI ChatGPT via MCP. ChatGPT can script, render, and download AI avatar videos using the HeyGen toolset inside any.

If you've been bouncing between tabs trying to create AI-generated videos, there's a simpler way now. HeyGen — one of the more popular AI video platforms — has an app that plugs right into ChatGPT. That means you can script, customize, and generate a video without ever leaving the chat

## Step 1: Open ChatGPT

Head to [chat.openai.com](http://chat.openai.com) and log into your account.

<Frame>
  <img alt="Screenshot 2026 04 02 At 8 52 33 AM" />
</Frame>

## Step 2: Find the HeyGen App

Look for the [**Apps**](https://chatgpt.com/apps) section in the left sidebar (or in the GPT store area, depending on your interface version). Search for [**HeyGen App**](https://chatgpt.com/apps/heygen/asdk_app_69418aad55e08191aa5e437b649ca2e4). It should come up as an official integration.\\

<Frame>
  <img alt="Screenshot 2026 04 02 At 8 53 39 AM" />
</Frame>

<Frame>
  <img alt="Screenshot 2026 04 02 At 8 54 15 AM" />
</Frame>

## Step 3: Connect and Authorize

Click on the HeyGen app, then hit **Connect**. ChatGPT will ask you to authorize a connection between your OpenAI account and HeyGen. This is a standard OAuth flow — you're giving ChatGPT permission to talk to HeyGen's API on your behalf.

If you don't already have a HeyGen account, you'll be prompted to create one during this step. HeyGen does offer a free tier with basic access, though generation limits are tight. If you're planning to use it regularly, HeyGen paid plans unlock longer videos, more avatar options, and higher resolution output.

<Frame>
  <img alt="Screenshot 2026 04 02 At 8 54 50 AM" />

  <img alt="Screenshot 2026 04 02 At 8 55 35 AM" />
</Frame>

## Step 4: Generate Your Video

Once the app is connected, you just ask ChatGPT to make a video. Be specific about what you want — the more detail you give, the better the result.

For example, you might say something like:

> "Use HeyGen to create a 60-second product explainer video. Use a female avatar, professional tone, and include a brief intro and call to action at the end."

<Frame>
  <img alt="Screenshot 2026 04 02 At 8 57 01 AM" />
</Frame>

ChatGPT will handle the back-and-forth with HeyGen's system, and you'll get your video generated directly in the conversation.


# Overview
Source: https://developers.heygen.com/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 message to an existing session. Use to answer agent questions, add context, or request edits to a generated video. Only valid for sessions created in chat mode.                 |
| `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 a video from a HeyGen avatar or an arbitrary image. Supports scripts or pre-recorded audio for lip-sync. Supports the Avatar III, Avatar IV, and Avatar V engines; set the 'engine' field to select. Avatar IV is used by default when 'engine' is omitted. |
| `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.                                                                                                                                                                                 |

### 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.                                                                                                                                                                                                                                                                                                            |
| `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 the template by replacing its variables (text, image, video, audio, character, voice). Use scene\_ids to select, reorder, or repeat scenes — scenes must already exist in the template; the API cannot create new ones. Returns the created video object; poll `GET /v3/videos/{video_id}` or use webhooks for completion. Idempotent replays return the original creation-time snapshot (status and URLs as of the first request), not the video's current state. |

### Voices

| Tool Name       | Description                                                                                                                                                                                                                                                                                                                                              |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_voices`   | Returns a paginated list of voices, filterable by type, engine, language, and gender. Use engine=starfish for voices compatible with the TTS endpoint.                                                                                                                                                                                                   |
| `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` | Synthesize speech audio from text using a specified voice. The voice must support the starfish engine — use GET /v3/voices?engine=starfish to find compatible voices. Supports plain text and SSML. Speed range: 0.5–2.0x. Returns a URL to the generated audio file along with duration and optional word-level timestamps.                             |
| `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 owned by the caller. The voice must not be in use by any template. The voice is removed from your voice list and no longer counts against your voice clone limit. Deleting an already-deleted or unknown voice returns 404 `voice\_not\_found` (not 200) — a delete-then-list flow should treat that 404 as success, not an error. |

### Audio

| Tool Name             | Description                                                                                                                                                                                                                                                                                                                                                                           |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search_audio_sounds` | Semantically search the audio catalog by natural-language description — set type=music (the default) for background music (e.g. 'upbeat lofi hip-hop', 'tense cinematic riser') or type=sound\_effects for SFX (e.g. 'whoosh for a scene change', 'cash register cha-ching'). Returns tracks ranked by similarity, each with a pre-signed download URL, plus cursor-based pagination. |

### 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`  | Submit up to 100 video-translation payloads (identical in shape to POST /v3/video-translations) as a single batch. A payload targeting multiple output\_languages expands to one batch item per language, and each item is created and processed independently so one bad source does not fail the rest. Returns 202 with a batch\_id; poll `GET /v3/video-translations/batches/{batch_id}` for progress. Pass an Idempotency-Key header to make retries safe — the same key returns the same batch. |
| `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 in one request, addressed by comma-separated video\_translation\_ids and/or batch\_ids query params. Statuses are one of queued, processing, completed, or failed, plus not\_found for unknown or unowned ids. Each returned entry carries its id as video\_id (the status read model is shared with the videos batch API).                                                                                                                        |

### Lipsync Batches

| Tool Name               | Description                                                                                                                                                                                                                                                                                                                                               |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_lipsync_batch`  | Submit up to 100 lipsync payloads as a single batch. Each payload becomes one batch item, created and processed independently so one bad source does not fail the rest. Returns 202 with a batch\_id; poll `GET /v3/lipsyncs/batches/{batch_id}` for progress. Pass an Idempotency-Key header to make retries safe — the same key returns the same batch. |
| `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 in one request, addressed by comma-separated lipsync\_ids and/or batch\_ids query params. Statuses are one of queued, processing, completed, or failed, plus not\_found for unknown or unowned ids. Each returned entry carries its id as video\_id (the status read model is shared with the videos batch API).  |

### 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`      | Finalize every uploaded file in a batch. Call after all upload PUTs return 200. Each file is validated and ingested asynchronously and independently, so one bad file does not fail the rest. Returns 202 with the batch\_id; poll `GET /v3/assets/batches/{batch_id}` for per-item progress. Idempotent: a repeated call re-drives the same batch.                                                                                               |
| `create_asset_upload_batch` | Request up to 100 presigned direct-to-S3 upload URLs in a single call. Returns a batch\_id and one upload slot per file (asset\_id + presigned upload\_url + required headers). PUT each file's bytes to its upload\_url, then call POST /v3/assets/complete/batches to finalize the whole batch. This is synchronous — no bytes flow through the API. Pass an Idempotency-Key header to make retries safe (the same key returns the same batch). |
| `bulk_asset_statuses`       | Returns statuses for up to 100 assets in one request, addressed by comma-separated asset\_ids and/or batch\_ids query params. Statuses are one of queued, processing, completed, or failed, plus not\_found for unknown or unowned ids. Each returned entry carries its id as video\_id (the status read model is shared with the videos batch API).                                                                                              |

### 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_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.                                                                                                                                                                                                       |
| `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 and its backing resource. Supported types: photo\_avatar, digital\_twin, and kit-based looks. Studio avatar (model\_index) types cannot be deleted via the API. **Warning:** deleting the last look in a group also deletes the parent group. Subsequent requests referencing that group id (e.g. `POST /v3/avatars` with `avatar\_group\_id`) return 404 not found. |
| `get_avatar_group`      | Returns details for a specific avatar group including name, gender, preview URLs, looks count, and training status.                                                                                                                                                                                                                                                                         |
| `delete_avatar_group`   | Permanently deletes an avatar group and all its associated looks. Cannot delete public or community groups.                                                                                                                                                                                                                                                                                 |
| `create_avatar_consent` | Initiates the consent flow for an avatar group and returns a URL for the user to complete approval in their browser. Required before a private avatar can be used for video generation.                                                                                                                                                                                                     |

### Assets

| Tool Name               | Description                                                                                                                                                                                                                                                     |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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.                                                                                                        |

### 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` | List brand glossaries (custom term mappings, a.k.a. brand voices) in the authenticated user's workspace. A brand glossary enforces custom term translations during video translation — for example, translating "Reformer" as Pilates equipment instead of as a political activist. Brand glossaries are created and edited in the HeyGen web app under Brand Kit; this endpoint is read-only for discovery. Pass the returned `brand\_glossary\_id` (or the legacy alias `brand\_voice\_id`) on POST /v2/video\_translate to apply the glossary during translation. |
| `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.                                                                                                                                                                                                                                                                                                            |

## Supported Products

HeyGen Remote MCP works with any MCP-compatible agent, including:

* **Claude** (Web, Desktop, and Code)
* **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.

**To request domain whitelisting**, submit your domain via the [Integration Intake form](https://form.typeform.com/to/m3EYcOaM).

## 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://developers.heygen.com/mcp/superhuman

Generate AI avatar videos from inside Superhuman via MCP. Compose personalized video emails, sales outreach, and follow-ups without leaving the email client.

If you spend most of your day inside the browser — researching, editing, summarising — there's now a way to turn whatever's on your screen into a HeyGen video without context-switching. Superhuman Go (the agent platform from Grammarly) connects directly to HeyGen via MCP + OAuth, so you can prompt it from anywhere on the web.

## Step 1: Open Superhuman Go

Make sure the Grammarly browser extension is installed, then open the **Superhuman Go** side panel. You'll see your default agents in the sidebar (Grammarly, Calendar, Gmail, etc.).

<Frame>
  <img alt="Screenshot 2026 05 04 152150" />
</Frame>

## Step 2: Find the HeyGen agent

Click the **+** (Add agents) button in the sidebar. In the search field, type `heygen` — the **HeyGen** agent (by HeyGen Integrations) will show up.

<Frame>
  <img alt="Screenshot 2026 05 04 152555" />
</Frame>

## Step 3: Connect and authorize

Click on the HeyGen agent to see its skills (Turn this into a video, Check video status, Text to speech, Browse voices, Manage videos) and privacy details. Hit **Sign in** to start the OAuth flow.

Superhuman Go will ask you to authorize access to your HeyGen account. Confirm, and once authentication completes you'll see the **Successfully signed in** confirmation. If you don't already have a HeyGen account, you can create one during this step (free tier available; paid plans unlock longer videos and more avatar options).

<Frame>
  <img alt="Screenshot 2026 05 04 153146" />
</Frame>

## Step 4: HeyGen agent is now active

After authorizing, the HeyGen agent appears in your Superhuman Go sidebar with its own chat surface. You can now ask it directly: **"Ask HeyGen"**.

<Frame>
  <img alt="Screenshot 2026 05 04 154256" />
</Frame>

## Step 5: Generate a video from any page

Browse to any page you want to turn into a video — a doc, an article, your own work. In the HeyGen panel, prompt it naturally. For example, while looking at one of HeyGen's own developer docs:

> *"Create a short video summary of the content on my screen."*

The agent will read your screen context, build an optimized prompt, and call the HeyGen Video Agent. You'll see the `Create_video_agent` step fire, and a few moments later the video appears with preview frames and quick options to regenerate (vertical, subtitled, alternative tone).

The final rendered video plays directly inside the Superhuman panel, with links to **Watch full video** and **Open in HeyGen** for sharing or editing further.

<Frame>
  <img alt="Screenshot 2026 05 04 154417" />
</Frame>

## Beyond a single page — chaining tools

Because Superhuman Go is an agent platform, HeyGen plays well with the other tools you've connected. For example, if you also have **Granola** connected, you can ask the agent to pull your meeting notes and turn them into a HeyGen video in a single prompt:

> *"Can you get my notes from Granola and create a HeyGen video summary of them?"*

The agent will fetch the latest notes from Granola, write a script, and kick off the HeyGen Video Agent — all in one chat turn.

## What's available

The HeyGen agent in Superhuman Go currently supports:

* **HeyGenAssistant** — default chat skill; reads your screen / editor / selected text and creates videos, checks status, generates speech audio
* **QuickVideoFromScreen** — one-shot 60-second landscape video from your current screen
* **CheckVideoStatus** — polls a session and fetches the final video when ready
* **TextToSpeech** — generates speech audio (≤1000 chars, Starfish engine)
* **BrowseVoices** — lists and filters HeyGen voices
* **ManageVideos** — lists, searches, and deletes videos in your HeyGen library

All actions run on your authenticated HeyGen account — videos appear in your HeyGen workspace as if you'd created them through the standard API or UI.


# Models
Source: https://developers.heygen.com/models

Browse every HeyGen avatar rendering engine behind the API - Avatar V, Avatar IV, and Avatar III - and learn how to choose between them.

<img alt="" />

# HeyGen Avatar Rendering Engines

HeyGen has three avatar rendering engines, all available on the v3 API and selected per request through the `engine` field on `POST /v3/videos`. New integrations should default to [Avatar IV](/avatar-iv) for broad coverage, opt into [Avatar V](/avatar-v) for the highest-fidelity motion and lip-sync, and use [Avatar III](/avatar-iii) for its dedicated photo-to-video pipeline.

```json theme={null}
{
  "type": "avatar",
  "avatar_id": "YOUR_LOOK_ID",
  "script": "Hello from HeyGen.",
  "voice_id": "YOUR_VOICE_ID",
  "engine": { "type": "avatar_iv" }
}
```

Before requesting an engine, confirm the avatar look supports it by checking `supported_api_engines` on the look (`GET /v3/avatars/looks/{look_id}`) — the array lists which of `avatar_iii`, `avatar_iv`, and `avatar_v` the look accepts, and requesting an engine that isn't listed returns a `400` error.

## Choosing an engine

|                            | [Avatar V](/avatar-v) | [Avatar IV](/avatar-iv) | [Avatar III](/avatar-iii)   |
| -------------------------- | --------------------- | ----------------------- | --------------------------- |
| `engine.type`              | `avatar_v`            | `avatar_iv`             | `avatar_iii`                |
| API version                | v3                    | v3                      | v3                          |
| Default engine             | ✗ (explicit opt-in)   | ✓                       | ✗ (explicit opt-in)         |
| Available to new users     | ✓                     | ✓                       | ✓                           |
| Digital Twin               | ✓                     | ✓                       | ✓                           |
| Photo Avatar               | ✗                     | ✓                       | ✓ (dedicated pipeline)      |
| Studio Avatar              | ✗                     | ✓                       | ✓ (renders as Digital Twin) |
| Arbitrary image input      | ✗                     | ✓                       | ✗                           |
| `motion_prompt`            | ✓                     | ✓                       | ✗                           |
| `expressiveness`           | ✗                     | ✓                       | ✗                           |
| Cross-reference animation  | ✓                     | ✗                       | ✗                           |
| 4K output                  | ✗                     | ✗                       | ✓ (except Photo Avatar)     |
| Eligibility check required | ✓                     | ✗                       | ✗                           |

<Note>
  A separate, older Avatar III engine remains available to existing customers through the **legacy v1/v2 endpoints**. It uses a different pipeline and is **not** the same as the Avatar III (`avatar_iii`) engine documented here. It is not offered on the new developer platform. See [Avatar III](/avatar-iii#legacy-avatar-iii-v1v2) for the distinction.
</Note>


# Motion Graphics from a Prompt
Source: https://developers.heygen.com/motion-graphics

Generate motion graphics and animated text overlays from a natural-language prompt. The HeyGen API outputs broadcast-ready animations, no timeline needed.

## Examples

These were created with Hyperframes + Claude Code in a single session — from idea to MP4 in under 5 minutes each.

<Tabs>
  <Tab title="Product Promo">
    <div>
      <iframe />
    </div>

    HeyGen product promo — animated text, voiceover, motion graphics. Built from a single prompt.
  </Tab>

  <Tab title="Architecture Explainer">
    <div>
      <iframe />
    </div>

    Minerva AI Tutor architecture — animated system diagram with TTS voiceover explaining how each component works.
  </Tab>
</Tabs>

## The Problem

Motion graphics traditionally require After Effects, Remotion (React), or hiring a designer. AI agents can write code — but most video tools don't speak code. There's no way to go from "make me a product launch video" to a rendered MP4 without a human in the middle.

## How It Works

```
Describe what you want → AI agent writes HTML + GSAP → Preview in browser → Render to MP4
```

Hyperframes turns HTML into video. Your AI coding agent (Claude Code, Cursor, Copilot) writes the HTML composition, and Hyperframes renders it frame-by-frame into a video file.

## Build It

<Steps>
  <Step title="Install and scaffold">
    ```bash theme={null}
    npx hyperframes init my-video
    cd my-video
    ```

    This creates a project with an empty composition, installs AI skills, and sets up the preview server. The skills tell your AI agent how to write valid Hyperframes compositions.
  </Step>

  <Step title="Describe what you want to your AI agent">
    Open the project in Claude Code (or your preferred AI agent) and describe the video:

    ```
    Create a 15-second product launch video for "Acme AI" —
    dark background, animated headline that types in letter by letter,
    stats that count up (10K users, 99.9% uptime, 50ms latency),
    and a logo reveal at the end. Vertical 9:16 for social.
    ```

    The agent uses the installed Hyperframes skills to write a valid HTML composition with GSAP animations.

    <Tip>
      **Write like you're briefing a designer, not writing code.** Describe the vibe, the content, and the pacing. The AI agent handles the implementation — `data-start`, `data-duration`, `class="clip"`, GSAP timeline registration, etc.
    </Tip>
  </Step>

  <Step title="Preview and iterate">
    ```bash theme={null}
    npx hyperframes dev
    ```

    Opens a browser preview at `localhost:3002` with hot reload. Edit the composition (or ask your agent to), and changes appear instantly.

    Common follow-ups:

    * "Make the text bigger"
    * "Change the background to a gradient"
    * "Speed up the transitions"
    * "Add a sound effect when the stats appear"
  </Step>

  <Step title="Render to MP4">
    ```bash theme={null}
    npx hyperframes render
    ```

    Captures every frame via headless Chrome, encodes with FFmpeg. Output lands in `renders/`.

    | Flag                              | What it does   | Default  |
    | --------------------------------- | -------------- | -------- |
    | `--fps 24\|30\|60`                | Frame rate     | 30       |
    | `--quality draft\|standard\|high` | Render quality | standard |
    | `--format mp4\|webm`              | Output format  | mp4      |

    <Tip>
      Use `--quality draft` while iterating — it's significantly faster. Switch to `standard` or `high` for the final export.
    </Tip>
  </Step>
</Steps>

## What Makes a Good Prompt

Based on testing 13+ videos in a single session:

| Approach                                              | Result                                                                             |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------- |
| "Make a video about X"                                | Works, but generic. Agent defaults to dark bg + centered text.                     |
| "Make a video about X, inspired by \[specific style]" | Much better. Give a reference and the agent adapts.                                |
| "Make a video about X" + 2-3 rounds of feedback       | Best results. Start broad, then refine ("make it more playful", "less corporate"). |

**1-3 prompts** gets you a good result if you describe the idea clearly. Complex compositions (multi-scene, data-driven) take 3-6 prompts.

## Beyond Text and Shapes

Hyperframes renders anything a browser can render. This means:

* **SVG animations** — Logo reveals, icon transitions, animated illustrations
* **Canvas/WebGL** — Particle systems, generative art, 3D scenes
* **Data visualizations** — Charts, graphs, dashboards that animate
* **Game-like content** — Simulations, interactive-looking demos
* **Math-driven patterns** — Physics simulations, algorithmic art

If you can build it in a browser, Hyperframes can turn it into a video.

## Add Audio

Hyperframes supports audio tracks natively. You can:

1. **Use HeyGen TTS** to generate voiceover (see [Voices](/docs/voices/speech))
2. **Add music** as an `<audio>` element with `data-start` and `data-volume`
3. **Synthesize sounds** programmatically (sorting visualizers, game SFX)

```html theme={null}
<audio id="voiceover" data-start="0" data-track-index="5"
       data-volume="0.9" src="voiceover.wav"></audio>
<audio id="music" data-start="0" data-track-index="6"
       data-volume="0.3" src="background.mp3"></audio>
```

***

## Next Steps

<CardGroup>
  <Card title="Data Visualization Videos" icon="chart-bar" href="/cookbook/hyperframes/data-to-video">
    Turn data into animated video — charts, dashboards, algorithmic visualizations.
  </Card>

  <Card title="Automated Pipeline" icon="gears" href="/cookbook/hyperframes/automated-pipeline">
    CI/CD integration for continuous video generation from data.
  </Card>

  <Card title="Hyperframes Docs" icon="book" href="https://hyperframes.heygen.com/introduction">
    Full framework reference — data attributes, templates, rendering options.
  </Card>
</CardGroup>


# Multilingual Content
Source: https://developers.heygen.com/multilingual-content

Localize video content into 175+ languages with the HeyGen API. Preserves voice characteristics and lipsync; pairs with translation for end-to-end global.

## See It in Action

One video, generated in English, then translated into multiple languages with lip-sync — stitched together:

<iframe />

## The Problem

Professional dubbing costs thousands of dollars per language. Most companies either skip localization entirely or settle for subtitles — missing the large audience that prefers content in their native language.

## How It Works

```
Create source video (Video Agent) → Translate (Video Translation API) → Distribute per region
```

Generate your video once in one language. Then translate it into as many languages as you need — with lip-sync so the avatar's mouth matches the translated audio.

## Build It

<Steps>
  <Step title="Create your source video">
    Generate the original video using any workflow — [social content](/cookbook/video-agent/social-media-pipeline), [product demo](/cookbook/video-agent/product-demos), [training](/cookbook/video-agent/training-and-onboarding), etc.

    ```python theme={null}
    import requests

    resp = requests.post(
        "https://api.heygen.com/v3/video-agents",
        headers={
            "X-Api-Key": HEYGEN_API_KEY,
            "Content-Type": "application/json",
        },
        json={
            "prompt": "Create a 60-second product overview of TaskFlow, a project management app..."
        },
    )
    source_video_id = resp.json()["data"]["video_id"]
    # ... poll until completed, get video_url
    ```
  </Step>

  <Step title="Translate into multiple languages">
    Use the Video Translation API to translate into multiple languages in a single request.

    ```python theme={null}
    target_languages = ["Spanish", "French", "German", "Japanese", "Chinese", "Portuguese", "Korean", "Arabic", "Hindi"]

    resp = requests.post(
        "https://api.heygen.com/v3/video-translations",
        headers={
            "X-Api-Key": HEYGEN_API_KEY,
            "Content-Type": "application/json",
        },
        json={
            "video": {"type": "url", "url": source_video_url},
            "output_languages": target_languages,
            "enable_caption": True,
            # "mode": "precision"  # For premium lip-sync quality
        },
    )
    translation_ids = resp.json()["data"]["video_translation_ids"]  # one per language
    ```

    Language names come from [`GET /v3/video-translations/languages`](/reference/list-supported-translation-languages) — pass names (e.g. `"Spanish (Spain)"`), not ISO codes.

    See [Video Translation docs](/docs/video-translate) for all supported languages and options.
  </Step>

  <Step title="Choose your quality mode">
    Two modes with different cost/quality tradeoffs:

    | Mode                | Cost          | Lip-sync quality | Best for                         |
    | ------------------- | ------------- | ---------------- | -------------------------------- |
    | **Speed** (default) | \$0.05/second | Good             | Most content, fast turnaround    |
    | **Precision**       | \$0.10/second | Premium          | Face-heavy videos, brand content |

    For a 60-second video translated into 9 languages:

    * Speed mode: 60s × 9 × $0.05 = **$27\*\*
    * Precision mode: 60s × 9 × $0.10 = **$54\*\*

    See [Pricing](/docs/pricing) for current rates.
  </Step>

  <Step title="Generate captions">
    Get subtitle files for each translated version.

    ```python theme={null}
    # After translation is complete (enable_caption was set at create time)
    for translation_id in translation_ids:
        job = requests.get(
            f"https://api.heygen.com/v3/video-translations/{translation_id}",
            headers={"X-Api-Key": HEYGEN_API_KEY},
        ).json()["data"]
        srt_url = job["srt_caption_url"]   # or job["vtt_caption_url"]
    ```

    <Info>
      Caption URLs expire after 7 days but are regenerated each time you request them.
    </Info>
  </Step>

  <Step title="Distribute per region">
    Now you have the source video + 9 translated versions + captions for each. Distribute based on your audience's region.

    ```python theme={null}
    # Example: organize outputs by language
    for lang in target_languages:
        print(f"{lang}: video_url=..., caption_url=...")
        # Upload to regional CDN, post to regional social accounts, etc.
    ```
  </Step>
</Steps>

## Real-World Results

These results are reported by companies via [HeyGen's customer stories](https://www.heygen.com/customer-stories):

| Company        | What they did                                   | Reported result                             |
| -------------- | ----------------------------------------------- | ------------------------------------------- |
| **Trivago**    | Localized TV ads across 30 markets              | Halved post-production time                 |
| **Würth**      | Translated employee training                    | Reported 80% reduction in translation costs |
| **McDonald's** | "Grandma McFlurry" campaign translated globally | Used HeyGen for multi-language distribution |

## Workflow: Translate Everything You Generate

Once you have a translation pipeline, apply it to every video you create:

```
Social Media Pipeline → Generate 5 English videos → Translate each to 9 languages = 45 videos
Training Pipeline → Generate 10 module videos → Translate to 7 languages = 70 training videos
Product Demo → Generate 1 demo → Translate to 5 key markets = 5 localized demos
```

The marginal cost per additional language is minimal compared to the reach it unlocks.

## Variations

* **Audio-only translation:** Keep the original video visuals, just change the voiceover — useful when lip-sync isn't critical
* **Subtitle-only:** Generate captions without re-rendering the video — cheapest option for supplementary languages
* **Regional adaptation:** Use different Video Agent prompts per region (not just translation but cultural adaptation) for high-priority markets

***

## Next Steps

<CardGroup>
  <Card title="Training & Onboarding" icon="book-open" href="/cookbook/video-agent/training-and-onboarding">
    Generate the training content that feeds into this pipeline.
  </Card>

  <Card title="Social Media Pipeline" icon="share-nodes" href="/cookbook/video-agent/social-media-pipeline">
    Multiply your social content across languages.
  </Card>
</CardGroup>


# Output Modes
Source: https://developers.heygen.com/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
```


# Overview
Source: https://developers.heygen.com/overview

The CookBook is a library of end-to-end recipes — copy-and-adapt workflows for the most common ways teams build with HeyGen. Pick a path below.

## CLI Recipes

Get up and running fast with these step-by-step CLI workflows.

<CardGroup>
  <Card title="Photo to Video" icon="camera" href="/photo-to-video">
    Turn a single headshot into a talking avatar video.
  </Card>

  <Card title="Design a Custom Voice" icon="microphone" href="/design-a-voice">
    Describe a voice in plain English and generate it instantly.
  </Card>

  <Card title="Video Agent Styles" icon="clapperboard-play" href="/video-agent-with-styles">
    Pick a visual style and let the agent handle the rest.
  </Card>
</CardGroup>

## Video Agent Workflows

Prompt-to-video recipes for the most common business use cases.

<CardGroup>
  <Card title="Social Media Pipeline" icon="share-nodes" href="/social-media-content-pipeline">
    Create social videos at scale with Video Agent.
  </Card>

  <Card title="Content Repurposing" icon="repeat" href="/content-repurposing">
    Turn blogs and docs into ready-to-publish video.
  </Card>

  <Card title="Multilingual Content" icon="earth-americas" href="/multilingual-content">
    Reach global audiences with localized video.
  </Card>

  <Card title="Personalized Outreach" icon="envelope" href="/personalized-sales-outreach">
    Personalized video at scale for sales teams.
  </Card>

  <Card title="Product Demos" icon="display" href="/product-demo-videos">
    Auto-generate demos directly from your product.
  </Card>

  <Card title="Training & Onboarding" icon="graduation-cap" href="/training-and-onboarding-videos">
    Convert documentation into training videos.
  </Card>

  <Card title="Real Estate Listings" icon="house" href="/real-estate-listing-videos">
    Property tour videos from listing data.
  </Card>

  <Card title="E-commerce Videos" icon="bag-shopping" href="/e-commerce-product-videos">
    Product videos generated from your catalog.
  </Card>

  <Card title="Docs to Video" icon="file-code" href="/docs-to-video">
    Auto-generate video in your CI/CD pipeline.
  </Card>

  <Card title="Automated Broadcast" icon="tower-broadcast" href="/automated-broadcast">
    Automated news and media broadcasts.
  </Card>

  <Card title="Personalized Greetings" icon="hand-wave" href="/personalized-greetings-and-recognition">
    Recognition and milestone videos for HR teams.
  </Card>
</CardGroup>

## Hyperframes Workflows

Programmatic, code-driven video — render HTML/CSS/JS and live data into MP4.

<CardGroup>
  <Card title="Motion Graphics" icon="wand-magic-sparkles" href="/motion-graphics">
    AI-assisted motion graphics with HTML-to-video.
  </Card>

  <Card title="Data to Video" icon="chart-bar" href="/data-to-video">
    Animate data into video automatically.
  </Card>

  <Card title="Automated Pipeline" icon="gear" href="/automated-pipeline">
    End-to-end programmatic video generation.
  </Card>
</CardGroup>

## Foundations

Concepts and inspiration that every workflow builds on.

<CardGroup>
  <Card title="Prompt Engineering" icon="pen-nib" href="/writing-effective-video-prompts">
    The foundation every Video Agent workflow depends on.
  </Card>

  <Card title="Showcase" icon="sparkles" href="/showcase">
    Real projects built with HeyGen — get inspired, then build your own.
  </Card>
</CardGroup>


# Personalized Greetings & Recognition
Source: https://developers.heygen.com/personalized-greetings-and-recognition

Generate thousands of personalized video greetings and employee recognition clips programmatically. Each video uses the recipient's name, role, and context.

## The Problem

A personalized video message makes someone's day. But recording individual videos for every employee birthday, customer milestone, or team celebration doesn't scale past a handful of people.

## How It Works

```
Recipient data (name, occasion, details) → Personalized prompt → Video Agent renders → Deliver
```

Define a template that feels personal, fill in recipient-specific details, and generate a unique video for each person.

## Build It

<Steps>
  <Step title="Define your occasions and templates">
    ```python theme={null}
    TEMPLATES = {
        "birthday": {
            "prompt": """Create a 20-second birthday video for {name}.

    The presenter should be warm and genuine: "Happy birthday, {name}!
    From everyone at {company}, we hope your day is amazing.
    {personal_note}
    Here's to a great year ahead!"

    Tone: Celebratory, warm, genuine — like a friend, not a corporate card.
    Background: Festive but tasteful. Include subtle confetti or balloons.
    """,
        },
        "work_anniversary": {
            "prompt": """Create a 25-second work anniversary video for {name}.

    "Congratulations {name} on {years} years at {company}!
    {achievement_note}
    Thank you for everything you bring to the team. Here's to many more!"

    Tone: Appreciative and sincere. Professional but warm.
    """,
        },
        "welcome": {
            "prompt": """Create a 20-second welcome video for {name} joining {team}.

    "Welcome to {company}, {name}! We're so excited to have you on the
    {team} team. {welcome_note}
    Can't wait to work with you!"

    Tone: Enthusiastic, welcoming, energetic.
    """,
        },
        "customer_milestone": {
            "prompt": """Create a 20-second milestone video for {name} at {company}.

    "Hey {name}, we just wanted to say thank you. {milestone_detail}
    We really appreciate your trust in us. Here's to what's next!"

    Tone: Grateful, personal, not salesy.
    """,
        },
    }
    ```
  </Step>

  <Step title="Generate for a batch of recipients">
    ```python theme={null}
    import requests
    import time

    recipients = [
        {
            "name": "Sarah Chen",
            "occasion": "birthday",
            "company": "Acme Corp",
            "personal_note": "We heard you're celebrating with a trip to Japan — enjoy every moment!",
        },
        {
            "name": "Marcus Johnson",
            "occasion": "work_anniversary",
            "company": "Acme Corp",
            "years": "5",
            "achievement_note": "From leading the product launch to mentoring three new engineers — your impact has been incredible.",
        },
        {
            "name": "Priya Patel",
            "occasion": "welcome",
            "company": "Acme Corp",
            "team": "Engineering",
            "welcome_note": "The team has been looking forward to having a Kubernetes expert on board.",
        },
    ]

    jobs = []
    for r in recipients:
        template = TEMPLATES[r["occasion"]]
        prompt = template["prompt"].format(**r)

        resp = requests.post(
            "https://api.heygen.com/v3/video-agents",
            headers={
                "X-Api-Key": HEYGEN_API_KEY,
                "Content-Type": "application/json",
            },
            json={"prompt": prompt},
        )
        jobs.append({
            "recipient": r,
            "video_id": resp.json()["data"]["video_id"],
        })
        time.sleep(5)
    ```

    Then poll for completion and deliver via email, Slack, or your HR platform.
  </Step>
</Steps>

## What Makes It Feel Personal

The difference between a greeting that lands and one that feels generic:

| Generic (don't do this)         | Personal (do this)                                                               |
| ------------------------------- | -------------------------------------------------------------------------------- |
| "Happy birthday from the team!" | "Happy birthday, Sarah! We heard you're heading to Japan — enjoy!"               |
| "Congrats on your anniversary"  | "5 years, Marcus — from leading the product launch to mentoring three engineers" |
| "Welcome aboard"                | "Welcome Priya! The team's been looking forward to having a K8s expert"          |

The specific detail is what makes it feel like someone actually thought about this person.

## Automation Ideas

| Trigger             | Source                | Delivery                         |
| ------------------- | --------------------- | -------------------------------- |
| Employee birthday   | HRIS/HR platform      | Email + Slack channel            |
| Work anniversary    | HRIS with start dates | Email + manager notification     |
| New hire start date | Onboarding system     | Email on day 1                   |
| Customer renewal    | CRM                   | Email from account manager       |
| Deal closed         | CRM                   | Slack celebration + email to rep |
| Usage milestone     | Product analytics     | In-app or email                  |

## Variations

* **Manager from-the-desk:** Use a specific avatar that represents the CEO or team lead for extra impact
* **Team compilations:** Generate individual short clips from each team member, then concatenate into a group video
* **Holiday greetings:** Batch-generate for all clients or employees with holiday-themed prompts
* **Multi-language:** Use [Video Translation](/cookbook/video-agent/multilingual-content) for global teams

***

## Next Steps

<CardGroup>
  <Card title="Personalized Outreach" icon="envelope" href="/cookbook/video-agent/personalized-outreach">
    Same personalization pattern, applied to sales.
  </Card>

  <Card title="Training & Onboarding" icon="book-open" href="/cookbook/video-agent/training-and-onboarding">
    Generate onboarding content for new hires.
  </Card>
</CardGroup>


# Personalized Sales Outreach
Source: https://developers.heygen.com/personalized-sales-outreach

Generate one AI avatar sales video per prospect with the HeyGen API — their name, company, and pain points baked into the script.

## The Problem

Generic sales emails have notoriously low response rates. Personalized video consistently outperforms text — but recording a custom video for each prospect doesn't scale past a handful per day.

## How It Works

```
CRM/prospect data → Personalized prompt per contact → Batch generate → Deliver via email/LinkedIn
```

You define a prompt template with variables (name, company, pain point). For each prospect, the template fills in their details and Video Agent generates a personalized video.

## Build It

<Steps>
  <Step title="Prepare your prospect data">
    Export from your CRM or create a structured list. Each entry needs enough context to personalize the video.

    ```python theme={null}
    prospects = [
        {
            "name": "Sarah Chen",
            "company": "Acme Corp",
            "role": "VP of Marketing",
            "pain_point": "spending 40+ hours/month on video content creation",
            "value_prop": "cut video production time by 90% with AI-generated content",
        },
        {
            "name": "Marcus Johnson",
            "company": "TechStart Inc",
            "role": "Head of Sales",
            "pain_point": "low response rates on cold outreach",
            "value_prop": "personalized video messages that get 10x more replies",
        },
        # ...
    ]
    ```
  </Step>

  <Step title="Build a prompt template">
    The template should produce a video that feels personally recorded — not like a mail merge.

    ```python theme={null}
    def build_outreach_prompt(prospect):
        return f"""Create a 30-second personalized sales video.

    The presenter should speak directly to the viewer as if recording
    a quick personal message. Warm, genuine, not salesy.

    Script direction:
    - Open: "Hi {prospect['name']}, I was looking at what {prospect['company']}
      is doing and had a quick thought for you."
    - Problem: Briefly mention that many {prospect['role']}s are
      {prospect['pain_point']}.
    - Solution: Share that there's a way to {prospect['value_prop']}.
    - CTA: "Would love to show you how this works — mind if I send
      over a 5-minute demo? Just reply to this email."

    Tone: Conversational and genuine. This should feel like a real person
    who took 30 seconds to record a message, not a polished ad.
    Keep it under 35 seconds. Landscape orientation.
    """
    ```

    <Tip>
      **The key to personalized video:** The prompt should include specific details about the prospect (company name, role, pain point) but the delivery should feel natural and unrehearsed. Avoid making it sound like a template — that defeats the purpose.
    </Tip>
  </Step>

  <Step title="Generate videos in batch">
    Submit all videos with rate limit spacing.

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

    HEYGEN_API_KEY = "your-api-key"
    jobs = []

    for prospect in prospects:
        prompt = build_outreach_prompt(prospect)
        resp = requests.post(
            "https://api.heygen.com/v3/video-agents",
            headers={
                "X-Api-Key": HEYGEN_API_KEY,
                "Content-Type": "application/json",
            },
            json={"prompt": prompt},
        )
        data = resp.json()["data"]
        jobs.append({
            "prospect": prospect,
            "video_id": data["video_id"],
        })
        print(f"Submitted for {prospect['name']}: {data['video_id']}")
        time.sleep(5)
    ```
  </Step>

  <Step title="Collect results and deliver">
    Once all videos are rendered, pair each video URL with the prospect for delivery.

    ```python theme={null}
    import time

    for job in jobs:
        while True:
            resp = requests.get(
                f"https://api.heygen.com/v3/videos/{job['video_id']}",
                headers={"X-Api-Key": HEYGEN_API_KEY},
            ).json()["data"]

            if resp["status"] == "completed":
                job["video_url"] = resp["video_url"]
                job["thumbnail_url"] = resp["thumbnail_url"]
                print(f"Ready for {job['prospect']['name']}: {resp['video_url']}")
                break
            elif resp["status"] == "failed":
                job["video_url"] = None
                print(f"Failed for {job['prospect']['name']}")
                break

            time.sleep(10)

    # Now you have a list of prospects with their personalized video URLs
    # Feed this into your email/LinkedIn outreach tool
    ```
  </Step>
</Steps>

## Delivery Strategies

| Channel            | How to embed                                                        | Tips                                                           |
| ------------------ | ------------------------------------------------------------------- | -------------------------------------------------------------- |
| **Email**          | Use the `thumbnail_url` as a clickable image linking to `video_url` | GIF thumbnails get higher click rates than static images       |
| **LinkedIn**       | Upload the video directly or share the link in a message            | Video messages tend to get significantly higher response rates |
| **Landing page**   | Embed the video on a personalized page per prospect                 | Combine with personalized page content for full experience     |
| **Sales platform** | Most platforms (Outreach, Salesloft, HubSpot) support video embeds  | Check your platform's video integration docs                   |

## Brand Consistency

When generating videos for many prospects, you want every video to feel on-brand:

* **Same avatar:** Pass a specific `avatar_id` to ensure the same "salesperson" appears in every video. See [Avatars](/docs/avatars) to browse options.
* **Same voice:** Pass a specific `voice_id` for consistent voice. See [Voices](/docs/voices).
* **Same style instructions:** Include brand colors, background, and tone in every prompt.

```python theme={null}
def build_outreach_prompt(prospect):
    return f"""Create a 30-second personalized sales video.

Avatar: Use avatar look_id "josh_lite3_20230714".
Background: Clean, modern office with warm lighting.
Brand: Professional but approachable. No flashy graphics.

...rest of the prompt...
"""
```

## Variations

* **Follow-up sequences:** Generate a series of videos per prospect — intro, value prop, case study, final nudge
* **Event-triggered:** Generate a welcome video when a prospect signs up for a trial or downloads a resource
* **Account-based marketing:** Generate company-specific videos that reference the prospect's recent news or achievements

***

## Next Steps

<CardGroup>
  <Card title="Social Media Pipeline" icon="share-nodes" href="/cookbook/video-agent/social-media-pipeline">
    Use similar batch techniques for social content.
  </Card>

  <Card title="Prompt Engineering" icon="wand-magic-sparkles" href="/cookbook/patterns/prompt-engineering">
    Craft prompts that make each video feel genuinely personal.
  </Card>
</CardGroup>


# Photo Avatar
Source: https://developers.heygen.com/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  | `4k`, `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`.


# Photo to Video
Source: https://developers.heygen.com/photo-to-video

Turn a photo into a talking avatar video with the HeyGen API. Upload an image, attach a script, and HeyGen renders a lipsynced video starring that photo.

## Prerequisites

* HeyGen CLI installed and authenticated (`heygen auth login`)
* A headshot photo (PNG or JPEG, max 32 MB). Front-facing, good lighting, and a neutral expression works best.

## Steps

<Steps>
  <Step title="Upload the photo">
    Upload your image to get an `asset_id`:

    ```bash theme={null}
    heygen asset create --file ./headshot.jpg
    ```

    ```json theme={null}
    {
      "data": {
        "asset_id": "ast_abc123"
      }
    }
    ```
  </Step>

  <Step title="Create a Photo Avatar">
    Pass the asset to `avatar create`. This trains a Photo Avatar from your image:

    ```bash theme={null}
    heygen avatar create -d '{
      "files": [{"type": "asset_id", "asset_id": "ast_abc123"}]
    }'
    ```

    ```json theme={null}
    {
      "data": {
        "avatar_id": "avt_xyz789",
        "avatar_group_id": "grp_def456",
        "status": "processing"
      }
    }
    ```

    Avatar training takes a few minutes. Poll the status:

    ```bash theme={null}
    heygen avatar looks get avt_xyz789
    ```

    Wait until `status` is `completed` before proceeding.

    <Note>
      Use `--request-schema` on any command to discover all available fields: `heygen avatar create --request-schema`
    </Note>
  </Step>

  <Step title="Pick a voice">
    Browse available voices:

    ```bash theme={null}
    heygen voice list --language English --gender female --limit 5
    ```

    ```json theme={null}
    {
      "data": [
        {
          "voice_id": "1bd001e7e50f421d891986aad5e3e5d2",
          "name": "Sara",
          "gender": "female",
          "language": "English"
        }
      ]
    }
    ```

    Copy the `voice_id` you want. If none of the stock voices fit, see the **Design a Custom Voice** recipe.
  </Step>

  <Step title="Generate the video">
    ```bash theme={null}
    heygen video create -d '{
      "type": "avatar",
      "avatar_id": "avt_xyz789",
      "script": "Hi there! I was created from a single photo using the HeyGen CLI.",
      "voice_id": "1bd001e7e50f421d891986aad5e3e5d2",
      "aspect_ratio": "auto"
    }'
    ```

    Add `--wait` to block until the video is ready, or poll manually with `heygen video get <video_id>`.
  </Step>

  <Step title="Download">
    ```bash theme={null}
    heygen video download vid_qrs321 --output-path ./my-avatar-video.mp4
    ```
  </Step>
</Steps>

## Full shell script

Chain everything together in one script:

```bash theme={null}
#!/bin/bash
set -e

# 1. Upload
ASSET_ID=$(heygen asset create --file ./headshot.jpg | jq -r '.data.asset_id')
echo "Uploaded: $ASSET_ID"

# 2. Create avatar
AVATAR_ID=$(heygen avatar create -d "{\"files\": [{\"type\": \"asset_id\", \"asset_id\": \"$ASSET_ID\"}]}" \
  | jq -r '.data.avatar_id')
echo "Avatar: $AVATAR_ID (training...)"

# 3. Wait for avatar training
while true; do
  STATUS=$(heygen avatar looks get "$AVATAR_ID" | jq -r '.data.status')
  [ "$STATUS" = "completed" ] && break
  [ "$STATUS" = "failed" ] && echo "Avatar training failed" && exit 1
  sleep 10
done
echo "Avatar ready"

# 4. Create video and wait
VIDEO=$(heygen video create --wait -d "{
  \"type\": \"avatar\",
  \"avatar_id\": \"$AVATAR_ID\",
  \"script\": \"Hello! This video was generated from a single photo.\",
  \"voice_id\": \"1bd001e7e50f421d891986aad5e3e5d2\"
}")
VIDEO_ID=$(echo "$VIDEO" | jq -r '.data.id')
echo "Video ready: $VIDEO_ID"

# 5. Download
heygen video download "$VIDEO_ID" --output-path ./result.mp4
echo "Done: ./result.mp4"
```

## Optional parameters

| Parameter      | Description                                                                                                 |
| -------------- | ----------------------------------------------------------------------------------------------------------- |
| `aspect_ratio` | `auto` (recommended — matches the source, falling back to `16:9`), `16:9` (landscape), or `9:16` (portrait) |
| `background`   | Set a solid color or image background                                                                       |
| `callback_url` | Webhook URL — skip polling and get notified when the video is ready                                         |

<Warning>
  Photo Avatars use the `avatar_iv` engine. The `avatar_id` you pass to `video create` is the **look ID** from `avatar looks list`, not the group ID.
</Warning>


# Product Demo Videos
Source: https://developers.heygen.com/product-demo-videos

Generate product demo videos programmatically from product data sheets, feature lists, and screenshots. HeyGen renders avatar-led explainers ready to publish.

## The Problem

Product demos require screen recording, narration, and editing. They go stale with every UI update. Most teams have a backlog of features that should have demo videos but don't, because production can't keep up.

## How It Works

```
Screenshots + feature specs → Video Agent prompt → Narrated walkthrough → Update by regenerating
```

Attach your product screenshots as file inputs. Video Agent creates a narrated walkthrough with an avatar presenter. When your UI changes, take new screenshots and re-run.

## Build It

<Steps>
  <Step title="Capture your product screenshots">
    Take screenshots of each feature or flow you want to demo. Name them descriptively — the file names won't matter to the API, but they help you organize.

    ```python theme={null}
    features = [
        {
            "name": "Dashboard Overview",
            "screenshot": "https://your-cdn.com/screenshots/dashboard.png",
            "description": "Main dashboard showing key metrics, recent activity, and quick actions",
        },
        {
            "name": "Kanban Board",
            "screenshot": "https://your-cdn.com/screenshots/kanban.png",
            "description": "Drag-and-drop task management with customizable columns and filters",
        },
        {
            "name": "Analytics",
            "screenshot": "https://your-cdn.com/screenshots/analytics.png",
            "description": "Team performance metrics with trend charts and export options",
        },
    ]
    ```
  </Step>

  <Step title="Build a feature-by-feature prompt">
    Structure the prompt around your features, not around a generic "product overview." Each feature gets its own segment.

    ```python theme={null}
    def build_demo_prompt(product_name, features, duration="60 seconds", audience="product managers"):
        feature_list = "\n".join(
            f"- {f['name']}: {f['description']}"
            for f in features
        )

        return f"""Create a {duration} product demo video for {product_name}.

    Target audience: {audience}

    Walk through these features using the attached screenshots as visual reference:
    {feature_list}

    Structure:
    - Hook (5s): "{product_name} helps you [key value prop] — let me show you how."
    - Feature walkthrough (80% of duration): Cover each feature with the presenter
      pointing out the key elements visible in the screenshots. Explain the benefit,
      not just what it does.
    - CTA (5s): "Start your free trial at [url]"

    Tone: Knowledgeable but approachable — like a product manager giving a live demo
    to a colleague. Not a sales pitch.

    IMPORTANT: Reference the attached screenshots as visual context. The viewer
    should see the product interface while the presenter explains each feature.
    """

    prompt = build_demo_prompt("TaskFlow", features)
    ```
  </Step>

  <Step title="Submit with screenshots as file inputs">
    Attach your screenshots so Video Agent can use them as visual context.

    ```python theme={null}
    import requests

    files = [{"type": "url", "url": f["screenshot"]} for f in features]

    resp = requests.post(
        "https://api.heygen.com/v3/video-agents",
        headers={
            "X-Api-Key": HEYGEN_API_KEY,
            "Content-Type": "application/json",
        },
        json={
            "prompt": prompt,
            "files": files,
        },
    )
    video_id = resp.json()["data"]["video_id"]
    ```

    See [Video Agent → File Input Formats](/docs/video-agent#file-input-formats) for all supported file types and upload methods.
  </Step>

  <Step title="Poll and download">
    Wait for rendering, then download. See [Video Agent docs](/docs/video-agent) for the polling pattern.
  </Step>
</Steps>

## Demo Styles

Generate different versions for different audiences:

| Style                   | Duration | Audience                | Prompt focus                                      |
| ----------------------- | -------- | ----------------------- | ------------------------------------------------- |
| **Quick overview**      | 30s      | Social media, ads       | One key value prop, fast-paced, visual-heavy      |
| **Feature walkthrough** | 60–90s   | Prospects, landing page | Feature-by-feature with benefits                  |
| **Deep dive**           | 2–3min   | Evaluators, tech buyers | Detailed functionality, integrations, edge cases  |
| **What's new**          | 30–45s   | Existing users          | Just the new/changed features from latest release |

## Staying Current

The key advantage: **when your product changes, re-run the pipeline with new screenshots.**

```python theme={null}
# Automate: take screenshots programmatically with Playwright
from playwright.sync_api import sync_playwright

def capture_screenshots(urls, output_dir="screenshots"):
    with sync_playwright() as p:
        browser = p.chromium.launch()
        page = browser.new_page(viewport={"width": 1280, "height": 720})

        for name, url in urls.items():
            page.goto(url)
            page.screenshot(path=f"{output_dir}/{name}.png")

        browser.close()

# Run this before each demo generation to always use current UI
capture_screenshots({
    "dashboard": "https://app.taskflow.com/dashboard",
    "kanban": "https://app.taskflow.com/board",
    "analytics": "https://app.taskflow.com/analytics",
})
```

<Tip>
  Combine this with [Docs to Video](/cookbook/video-agent/docs-to-video) to trigger demo regeneration automatically when your product releases a new version.
</Tip>

## Variations

* **Comparison videos:** "TaskFlow vs. Competitor" — show side-by-side screenshots
* **Customer-specific demos:** Customize the prompt with the prospect's industry and pain points for personalized demos at scale (see [Personalized Outreach](/cookbook/video-agent/personalized-outreach))
* **Interactive follow-up:** After the pre-recorded demo, offer a [Live Avatar interactive demo](/cookbook/live-avatar/interactive-product-demo) for Q\&A

***

## Next Steps

<CardGroup>
  <Card title="Interactive Product Demo" icon="comment-dots" href="/cookbook/live-avatar/interactive-product-demo">
    Add live Q\&A to your demos with a Live Avatar.
  </Card>

  <Card title="Prompt Engineering" icon="wand-magic-sparkles" href="/cookbook/patterns/prompt-engineering">
    Write prompts that make your demos shine.
  </Card>
</CardGroup>


# Real Estate Listing Videos
Source: https://developers.heygen.com/real-estate-listing-videos

Turn listing data, photos, and agent scripts into branded property-tour videos with the HeyGen API.

## The Problem

Listings with video consistently get more inquiries than those without. But professional property tour videos cost thousands of dollars each — making them viable only for luxury properties. Most agents have great photos but no video.

## How It Works

```
Property photos + listing data → Video Agent prompt → Narrated property tour → Post to listing sites
```

Attach your property photos as file inputs and describe the property in your prompt. Video Agent creates a narrated walkthrough with an avatar presenting the property highlights.

## Build It

<Steps>
  <Step title="Structure your listing data">
    ```python theme={null}
    listing = {
        "address": "742 Evergreen Terrace, Springfield",
        "price": "$485,000",
        "bedrooms": 4,
        "bathrooms": 2.5,
        "sqft": 2200,
        "highlights": [
            "Renovated chef's kitchen with quartz countertops and stainless appliances",
            "Primary suite with walk-in closet and spa-like bathroom",
            "Landscaped backyard with covered patio and fire pit",
            "Walking distance to top-rated schools",
        ],
        "neighborhood": "Quiet, family-friendly street with mature trees",
        "photos": [
            "https://cdn.realty.com/photos/exterior.jpg",
            "https://cdn.realty.com/photos/kitchen.jpg",
            "https://cdn.realty.com/photos/primary-suite.jpg",
            "https://cdn.realty.com/photos/backyard.jpg",
        ],
    }
    ```
  </Step>

  <Step title="Build the tour prompt">
    ```python theme={null}
    def build_listing_prompt(listing):
        highlights = "\n".join(f"- {h}" for h in listing["highlights"])

        return f"""Create a 45-second property tour video for a real estate listing.

    Property: {listing['address']}
    Price: {listing['price']} | {listing['bedrooms']} bed / {listing['bathrooms']} bath | {listing['sqft']} sq ft

    Tour structure using the attached property photos:
    - Opening (5s): Presenter stands in front of the home. "Welcome to {listing['address']}
      — let me show you why this {listing['bedrooms']}-bedroom home is something special."
    - Kitchen & living (15s): Walk through the main living areas, highlighting:
      {highlights[0] if len(listing['highlights']) > 0 else ''}
    - Primary suite (10s): Showcase the bedroom and bathroom
    - Outdoor space (10s): Show the backyard and patio
    - Closing (5s): "{listing['price']}. Schedule your private showing today."

    Tone: Warm, professional, inviting — like a top-producing agent
    who genuinely loves this home. Not salesy.
    Neighborhood note: {listing['neighborhood']}
    """

    prompt = build_listing_prompt(listing)
    ```
  </Step>

  <Step title="Submit with property photos">
    ```python theme={null}
    import requests

    files = [{"type": "url", "url": url} for url in listing["photos"]]

    resp = requests.post(
        "https://api.heygen.com/v3/video-agents",
        headers={
            "X-Api-Key": HEYGEN_API_KEY,
            "Content-Type": "application/json",
        },
        json={
            "prompt": prompt,
            "files": files,
        },
    )
    video_id = resp.json()["data"]["video_id"]
    ```

    Then poll for completion — see [Video Agent docs](/docs/video-agent).
  </Step>

  <Step title="Batch generate for your portfolio">
    Generate videos for all your active listings in one run.

    ```python theme={null}
    import time

    listings = load_from_mls()  # Your listing data source

    for listing in listings:
        prompt = build_listing_prompt(listing)
        files = [{"type": "url", "url": url} for url in listing["photos"]]

        resp = requests.post(
            "https://api.heygen.com/v3/video-agents",
            headers={
                "X-Api-Key": HEYGEN_API_KEY,
                "Content-Type": "application/json",
            },
            json={"prompt": prompt, "files": files},
        )
        listing["video_id"] = resp.json()["data"]["video_id"]
        time.sleep(5)  # Rate limit spacing
    ```
  </Step>
</Steps>

## Video Styles by Property Type

| Property type        | Duration | Style                     | Focus                                  |
| -------------------- | -------- | ------------------------- | -------------------------------------- |
| **Starter home**     | 30s      | Friendly, energetic       | Value, neighborhood, schools           |
| **Luxury**           | 60–90s   | Elegant, cinematic        | Design details, materials, views       |
| **Investment**       | 30s      | Numbers-driven            | ROI, rental income, location           |
| **Commercial**       | 45s      | Professional              | Square footage, traffic, zoning        |
| **New construction** | 45s      | Exciting, forward-looking | Customization options, builder quality |

## Cost Comparison

| Approach                    | Cost per video  | Time        | Scalability |
| --------------------------- | --------------- | ----------- | ----------- |
| Professional videographer   | \$1,000+        | Days–weeks  | Low         |
| DIY with phone + editing    | \$0 (your time) | 2–4 hours   | Very low    |
| **Video Agent from photos** | **\~\$2–5**     | **Minutes** | **High**    |

## Variations

* **Neighborhood spotlight:** Generate a separate video about the area — schools, dining, parks, commute times
* **Open house invite:** Short 15-second teaser: "Open house this Saturday at \[address]. Here's a sneak peek."
* **Multi-language:** Translate for international buyers using [Video Translation](/cookbook/video-agent/multilingual-content)
* **Agent branding:** Use the same avatar and style across all listings for consistent personal brand

***

## Next Steps

<CardGroup>
  <Card title="Product Demos" icon="desktop" href="/cookbook/video-agent/product-demos">
    Same screenshot-to-video pattern, applied to software.
  </Card>

  <Card title="E-commerce Product Videos" icon="cart-shopping" href="/cookbook/video-agent/ecommerce-product-videos">
    Same catalog-to-video pattern, applied to products.
  </Card>
</CardGroup>


# Append Avatar Realtime Text
Source: https://developers.heygen.com/reference/append-avatar-realtime-text

/openapi/external-api.json post /v3/avatar-realtime/{stream_id}/text
Append a text delta to a session created with `type: text_stream`. Send fragments as they become available (e.g. tokens streamed from an upstream LLM); the avatar speaks them in order. Set `final: true` on the last delta to close input — further appends to a closed stream return 410. Returns the total bytes buffered so far.



# Bulk Asset Statuses
Source: https://developers.heygen.com/reference/bulk-asset-statuses

/openapi/external-api.json get /v3/assets/statuses
Returns statuses for up to 100 assets in one request, addressed by comma-separated asset_ids and/or batch_ids query params. Statuses are one of queued, processing, completed, or failed, plus not_found for unknown or unowned ids. Each returned entry carries its id as video_id (the status read model is shared with the videos batch API).



# Bulk Lipsync Statuses
Source: https://developers.heygen.com/reference/bulk-lipsync-statuses

/openapi/external-api.json get /v3/lipsyncs/statuses
Returns statuses for up to 100 lipsyncs in one request, addressed by comma-separated lipsync_ids and/or batch_ids query params. Statuses are one of queued, processing, completed, or failed, plus not_found for unknown or unowned ids. Each returned entry carries its id as video_id (the status read model is shared with the videos batch API).



# Bulk Video Statuses
Source: https://developers.heygen.com/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://developers.heygen.com/reference/bulk-video-translation-statuses

/openapi/external-api.json get /v3/video-translations/statuses
Returns statuses for up to 100 video translations in one request, addressed by comma-separated video_translation_ids and/or batch_ids query params. Statuses are one of queued, processing, completed, or failed, plus not_found for unknown or unowned ids. Each returned entry carries its id as video_id (the status read model is shared with the videos batch API).



# Cancel Avatar Realtime Session
Source: https://developers.heygen.com/reference/cancel-avatar-realtime-session

/openapi/external-api.json post /v3/avatar-realtime/{stream_id}/cancel
Cancel a running streaming session. Idempotent: `cancelled` is true when this request initiated the cancellation, or false when the session was already terminal (completed, failed, or previously cancelled).



# Clone a Voice
Source: https://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/reference/complete-asset-upload-batch

/openapi/external-api.json post /v3/assets/complete/batches
Finalize every uploaded file in a batch. Call after all upload PUTs return 200. Each file is validated and ingested asynchronously and independently, so one bad file does not fail the rest. Returns 202 with the batch_id; poll GET /v3/assets/batches/{batch_id} for per-item progress. Idempotent: a repeated call re-drives the same batch.



# Create AI Clipping
Source: https://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/reference/create-asset-upload-batch

/openapi/external-api.json post /v3/assets/direct-uploads/batches
Request up to 100 presigned direct-to-S3 upload URLs in a single call. Returns a batch_id and one upload slot per file (asset_id + presigned upload_url + required headers). PUT each file's bytes to its upload_url, then call POST /v3/assets/complete/batches to finalize the whole batch. This is synchronous — no bytes flow through the API. Pass an Idempotency-Key header to make retries safe (the same key returns the same batch).



# Create Avatar
Source: https://developers.heygen.com/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://developers.heygen.com/reference/create-avatar-consent

/openapi/external-api.json post /v3/avatars/{group_id}/consent
Initiates the consent flow for an avatar group and returns a URL for the user to complete approval in their browser. Required before a private avatar can be used for video generation.



# Create Avatar Realtime Session
Source: https://developers.heygen.com/reference/create-avatar-realtime-session

/openapi/external-api.json post /v3/avatar-realtime
Start a low-latency streaming avatar session and return a `stream_id`. Three modes, selected by the `type` discriminator: `tts` (speak a fixed script), `audio` (drive lip-sync from a pre-existing audio asset), and `text_stream` (seed with initial text, then append more text deltas over time via POST /v3/avatar-realtime/{stream_id}/text — e.g. as an upstream LLM streams tokens). Poll GET /v3/avatar-realtime/{stream_id} for the session status and HLS playback URL.



# Create HyperFrames Render
Source: https://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/reference/create-lipsync-batch

/openapi/external-api.json post /v3/lipsyncs/batches
Submit up to 100 lipsync payloads as a single batch. Each payload becomes one batch item, created and processed independently so one bad source does not fail the rest. Returns 202 with a batch_id; poll GET /v3/lipsyncs/batches/{batch_id} for progress. Pass an Idempotency-Key header to make retries safe — the same key returns the same batch.



# Create Proofread Session
Source: https://developers.heygen.com/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 Video
Source: https://developers.heygen.com/reference/create-video

/openapi/external-api.json post /v3/videos
Creates a video from a HeyGen avatar or an arbitrary image. Supports scripts or pre-recorded audio for lip-sync. Supports the Avatar III, Avatar IV, and Avatar V engines; set the 'engine' field to select. Avatar IV is used by default when 'engine' is omitted.



# Create Video Agent Session
Source: https://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/reference/create-video-translation-batch

/openapi/external-api.json post /v3/video-translations/batches
Submit up to 100 video-translation payloads (identical in shape to POST /v3/video-translations) as a single batch. A payload targeting multiple output_languages expands to one batch item per language, and each item is created and processed independently so one bad source does not fail the rest. Returns 202 with a batch_id; poll GET /v3/video-translations/batches/{batch_id} for progress. Pass an Idempotency-Key header to make retries safe — the same key returns the same batch.



# Create Webhook Endpoint
Source: https://developers.heygen.com/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://developers.heygen.com/reference/delete-a-voice

/openapi/external-api.json delete /v3/voices/{voice_id}
Deletes a voice clone owned by the caller. The voice must not be in use by any template. The voice is removed from your voice list and no longer counts against your voice clone limit. Deleting an already-deleted or unknown voice returns 404 `voice_not_found` (not 200) — a delete-then-list flow should treat that 404 as success, not an error.



# Delete AI Clipping
Source: https://developers.heygen.com/reference/delete-ai-clipping

/openapi/external-api.json delete /v3/ai-clipping/{job_id}
Soft-deletes an AI clip job and its clips.



# Delete Asset
Source: https://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/reference/delete-avatar-look

/openapi/external-api.json delete /v3/avatars/looks/{look_id}
Deletes an avatar look and its backing resource. Supported types: photo_avatar, digital_twin, and kit-based looks. Studio avatar (model_index) types cannot be deleted via the API. **Warning:** deleting the last look in a group also deletes the parent group. Subsequent requests referencing that group id (e.g. `POST /v3/avatars` with `avatar_group_id`) return 404 not found.



# Delete HyperFrames Render
Source: https://developers.heygen.com/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://developers.heygen.com/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 Video
Source: https://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/reference/generate-speech

/openapi/external-api.json post /v3/voices/speech
Synthesize speech audio from text using a specified voice. The voice must support the starfish engine — use GET /v3/voices?engine=starfish to find compatible voices. Supports plain text and SSML. Speed range: 0.5–2.0x. Returns a URL to the generated audio file along with duration and optional word-level timestamps.



# Generate Video from Proofread
Source: https://developers.heygen.com/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://developers.heygen.com/reference/generate-video-from-template

/openapi/external-api.json post /v3/templates/{template_id}
Generates a video from the template by replacing its variables (text, image, video, audio, character, voice). Use scene_ids to select, reorder, or repeat scenes — scenes must already exist in the template; the API cannot create new ones. Returns the created video object; poll GET /v3/videos/{video_id} or use webhooks for completion. Idempotent replays return the original creation-time snapshot (status and URLs as of the first request), not the video's current state.



# Get AI Clipping
Source: https://developers.heygen.com/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 Asset
Source: https://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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 Avatar Realtime Session
Source: https://developers.heygen.com/reference/get-avatar-realtime-session

/openapi/external-api.json get /v3/avatar-realtime/{stream_id}
Get the status of a streaming avatar session. `status` is one of `pending` (workflow starting), `streaming` (the `hls_url` is live), `completed` (finished — `end_reason` describes how), or `error` (`error_message` describes the failure). Poll this after POST /v3/avatar-realtime until `hls_url` is present.



# Get Current User
Source: https://developers.heygen.com/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 HyperFrames Render
Source: https://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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 Translation
Source: https://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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 Avatar Groups
Source: https://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/reference/list-brand-glossaries

/openapi/external-api.json get /v3/brand-glossaries
List brand glossaries (custom term mappings, a.k.a. brand voices) in the authenticated user's workspace. A brand glossary enforces custom term translations during video translation — for example, translating "Reformer" as Pilates equipment instead of as a political activist. Brand glossaries are created and edited in the HeyGen web app under Brand Kit; this endpoint is read-only for discovery.

Pass the returned `brand_glossary_id` (or the legacy alias `brand_voice_id`) on POST /v2/video_translate to apply the glossary during translation.



# List Brand Kits
Source: https://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/reference/list-lipsyncs

/openapi/external-api.json get /v3/lipsyncs
Returns a paginated list of all lipsync jobs in the account.



# List Session Videos
Source: https://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/reference/list-voices

/openapi/external-api.json get /v3/voices
Returns a paginated list of voices, filterable by type, engine, language, and gender. Use engine=starfish for voices compatible with the TTS endpoint.



# List Webhook Endpoints
Source: https://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/reference/search-audio-music-or-sound-effects

/openapi/external-api.json get /v3/audio/sounds
Semantically search the audio catalog by natural-language description — set type=music (the default) for background music (e.g. 'upbeat lofi hip-hop', 'tense cinematic riser') or type=sound_effects for SFX (e.g. 'whoosh for a scene change', 'cash register cha-ching'). Returns tracks ranked by similarity, each with a pre-signed download URL, plus cursor-based pagination.



# Send Message or Request Revision
Source: https://developers.heygen.com/reference/send-message-or-request-revision

/openapi/external-api.json post /v3/video-agents/{session_id}
Sends a follow-up message to an existing session. Use to answer agent questions, add context, or request edits to a generated video. Only valid for sessions created in chat mode.



# Stop Video Agent Session
Source: https://developers.heygen.com/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 Avatar Realtime Word Timestamps
Source: https://developers.heygen.com/reference/stream-avatar-realtime-word-timestamps

/openapi/external-api.json get /v3/avatar-realtime/{stream_id}/words
Open a Server-Sent Events (`text/event-stream`) stream of per-word timestamps for a session. Each `data:` frame is a `WordBatch` (`{"words": [{"word", "start", "end"}, ...]}`); times are in seconds from the start of the streamed audio (matching OpenAI Whisper and ElevenLabs). Punctuation is emitted as its own word event. Batches are capped at ~1s of audio or 10 words, whichever comes first. Late subscribers receive the full session history; completed sessions are served from a durable snapshot. The stream ends with a single `event: end` frame carrying a `WordsEndEvent`.



# Update Avatar Look
Source: https://developers.heygen.com/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 Lipsync
Source: https://developers.heygen.com/reference/update-lipsync

/openapi/external-api.json patch /v3/lipsyncs/{lipsync_id}
Updates the display title of a lipsync job.



# Update Video Translation
Source: https://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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.



# Showcase
Source: https://developers.heygen.com/showcase

See real HeyGen CLI recipes in action - README-to-video, social media pipelines, sales outreach, and more. Each recipe is a copy-paste command set you can run.

These projects demonstrate what's possible when you combine Video Agent with AI coding agents, browser extensions, CI/CD pipelines, and more.

***

## README-to-Video

**Auto-generate video walkthroughs from GitHub README changes.**

A GitHub Action watches for README changes, uses Claude to write a scene-by-scene production prompt, and sends it to Video Agent. The rendered video is automatically embedded back in the README.

* **HeyGen features:** Video Agent API
* **Stack:** TypeScript, GitHub Actions, Claude
* **Key insight:** The quality gap between good and mediocre videos comes down to the prompt. This project uses an LLM to write production-quality briefs with specific visual directions — not just narration scripts.
* **Cost:** \~\$0.05–0.15 per video

<Accordion title="How the prompt pipeline works">
  Instead of passing the README text directly to Video Agent, the system uses a two-stage prompt:

  1. **Meta-prompt** — Claude receives the README content + instructions on how to write a great Video Agent prompt (scene structure, visual style, B-roll descriptions, pacing)
  2. **Video prompt** — Claude outputs a detailed production brief that Video Agent can execute

  This "prompt-that-writes-a-prompt" pattern is reusable for any content-to-video workflow.
</Accordion>

***

## Viral Video Pipeline

**Research trending topics, then batch-generate short-form videos.**

Researches trending self-improvement topics via web search, then generates 6 TikTok/Reels/Shorts-ready videos in one run. Fully automated — no camera, no mic, no editing.

* **HeyGen features:** Video Agent API (batch generation, portrait mode)
* **Stack:** Claude Code + HeyGen Skills
* **Key insight:** Rate limit handling is critical for batch generation. This pipeline fires videos sequentially with 5–10 second gaps and tracks all video IDs for async polling.
* **Output:** 6 videos (25–40s each) + batch report with performance predictions
* **Cost:** \~\$6 in HeyGen credits for the full batch

***

## Site2Video — Chrome Extension

**One-click: turn any website into a professional, brand-consistent video.**

A Chrome extension captures a full-page screenshot, analyzes the site's visual DNA (colors, typography, layout), generates a style-aware Video Agent prompt, and renders a branded video.

* **HeyGen features:** Video Agent API, Asset Upload, 1,200+ avatars
* **Stack:** Vite + React (extension), Next.js (backend), Gemini/Claude (LLM)
* **Key insight:** Every prompt is generated from scratch using LLM analysis — no static templates. The system extracts visual style from the page itself and translates it into Video Agent prompt instructions.
* **Video modes:** Founder Pitch (60s), Product Walkthrough (90s), Teardown (75s), Investor Summary (45s), Social Ad (30s)
* **Visual styles:** 14 curated styles + Auto mode that extracts style from the website

***

## AI News Broadcast

**Automated daily AI briefings: scrape → script → render → distribute.**

A pipeline that gathers AI papers from arXiv and Hacker News, builds a script with an LLM, generates a video via Video Agent, and posts it to Telegram.

* **HeyGen features:** Video Agent API
* **Stack:** Bun + TypeScript
* **Key insight:** The modular architecture (research → script → video → deliver) makes each stage independently testable and swappable. You could replace the Telegram delivery with email, Slack, or YouTube upload.

***

## AI Mafia — Live Avatar Game

**Social deduction game with AI-powered Live Avatar NPCs.**

A Mafia/Werewolf game where 3 AI players argue, accuse, bluff, and vote in real-time using HeyGen Live Avatars. Each NPC has a distinct personality and is powered by Claude for decision-making.

* **HeyGen features:** Live Avatar SDK (real-time streaming)
* **Stack:** Next.js, React, HeyGen Live Avatar SDK, Claude
* **Key insight:** Live Avatars enable real-time interactive experiences — not just pre-rendered videos. The NPCs read game state, develop strategies, and respond with natural speech and expressions.
* **Characters:** Maria (expressive), Chen (calm analyst), Alex (emotional reactor)

<Info>
  This project uses **Live Avatars** (real-time streaming), not Video Agent. It showcases a different interaction model — live, conversational AI rather than pre-rendered video content.
</Info>

***

## Build Your Own

These projects share common patterns you can reuse:

1. **Content → LLM → Video Agent prompt** — The meta-prompt pattern works for any content type
2. **Batch generation with rate limit handling** — Sequential queuing with status tracking
3. **Style extraction → prompt instructions** — Translate visual context into Video Agent language
4. **Modular pipelines** — Separate research, scripting, rendering, and delivery stages

Start with a [workflow](/cookbook/video-agent/social-media-pipeline), learn the [prompt techniques](/cookbook/patterns/prompt-engineering), and build from there.


# heygen-avatar
Source: https://developers.heygen.com/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 [Create Avatar](/docs/create-avatar#prompt-to-avatar) 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://developers.heygen.com/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://developers.heygen.com/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://developers.heygen.com/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 [app.heygen.com/api](https://app.heygen.com/api), 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://app.heygen.com/api) 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://developers.heygen.com/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>


# Social Media Content Pipeline
Source: https://developers.heygen.com/social-media-content-pipeline

Automate social media video creation end-to-end. Use the HeyGen API to convert posts, articles, and product feeds into avatar videos sized for every platform.

## Examples

These were generated with Video Agent from a text prompt — no camera, no editing, no mic.

<Tabs>
  <Tab title="Freelancing story">
    <div>
      <iframe title="HeyGen video player" />
    </div>
  </Tab>

  <Tab title="AI editing story">
    <div>
      <iframe title="HeyGen video player" />
    </div>
  </Tab>
</Tabs>

## The Problem

Creating consistent social media video content requires a camera, microphone, editing skills, and hours of time per video. Most teams can't keep up with the pace platforms demand — daily or weekly posts across TikTok, Reels, and Shorts.

## How It Works

```
Choose topics → Write prompts → Batch generate videos → Post
```

You define the topics and tone. Video Agent handles avatar selection, scripting, visuals, and rendering. Generate a week's worth of content in one run.

## Build It

<Steps>
  <Step title="Choose your topics">
    You can source topics manually, from trending data, or from audience research. Here's an example batch of 5 topics for a SaaS marketing account:

    ```python theme={null}
    topics = [
        "Why your onboarding flow is losing users in the first 60 seconds",
        "The 3 metrics every SaaS founder checks before coffee",
        "Stop building features nobody asked for — do this instead",
        "Your pricing page is broken and here's the proof",
        "The hiring mistake that kills startups faster than bad code",
    ]
    ```

    <Tip>
      **Use an LLM for topic research.** Ask Claude or ChatGPT: "Give me 10 trending topics in \[your niche] that would perform well as 30-second TikToks." You can also use web search APIs to find what's trending right now.
    </Tip>
  </Step>

  <Step title="Write prompts optimized for short-form">
    Short-form video has a specific structure: **hook → content → CTA**, all in under 60 seconds. Your prompts should reflect this.

    ```python theme={null}
    def build_prompt(topic):
        return f"""Create a 30-second vertical video (portrait orientation) for TikTok/Reels.

    Topic: {topic}

    Structure:
    - Hook (0-5s): Open with a bold, scroll-stopping statement or question.
    - Content (5-25s): Deliver 2-3 punchy insights. Fast pacing, one idea
      every 5-7 seconds. Use text overlays for key points.
    - CTA (25-30s): End with a clear call-to-action.

    Tone: Casual and energetic, like talking to a friend who's also in the industry.
    Orientation: portrait.
    """

    prompts = [build_prompt(t) for t in topics]
    ```

    See [Prompt Engineering](/cookbook/patterns/prompt-engineering) for more techniques — especially the scene-by-scene structure for longer videos.
  </Step>

  <Step title="Batch generate with rate limit handling">
    Submit all videos to Video Agent. Space them out to respect [rate limits](/docs/pricing).

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

    HEYGEN_API_KEY = "your-api-key"
    video_ids = []

    for i, prompt in enumerate(prompts):
        resp = requests.post(
            "https://api.heygen.com/v3/video-agents",
            headers={
                "X-Api-Key": HEYGEN_API_KEY,
                "Content-Type": "application/json",
            },
            json={
                "prompt": prompt,
                "orientation": "portrait",
            },
        )
        data = resp.json()["data"]
        video_ids.append(data["video_id"])
        print(f"[{i+1}/{len(prompts)}] Submitted: {data['video_id']}")

        # Wait between submissions to avoid rate limits
        if i < len(prompts) - 1:
            time.sleep(5)

    print(f"\nAll {len(video_ids)} videos submitted.")
    ```
  </Step>

  <Step title="Poll for completion">
    Wait for all videos to finish rendering.

    ```python theme={null}
    import time

    def poll_videos(video_ids):
        results = {}
        pending = set(video_ids)

        while pending:
            for vid in list(pending):
                resp = requests.get(
                    f"https://api.heygen.com/v3/videos/{vid}",
                    headers={"X-Api-Key": HEYGEN_API_KEY},
                )
                data = resp.json()["data"]

                if data["status"] == "completed":
                    results[vid] = data["video_url"]
                    pending.discard(vid)
                    print(f"Completed: {vid}")
                elif data["status"] == "failed":
                    results[vid] = None
                    pending.discard(vid)
                    print(f"Failed: {vid} — {data.get('failure_message')}")

            if pending:
                print(f"Waiting... {len(pending)} still rendering")
                time.sleep(15)

        return results

    results = poll_videos(video_ids)
    ```

    <Tip>
      For production pipelines, use [webhooks](/docs/webhooks) instead of polling. Pass a `callback_url` in each creation request and handle notifications as they arrive.
    </Tip>
  </Step>

  <Step title="Download and distribute">
    Download all completed videos, then post to your platforms.

    ```python theme={null}
    import os

    os.makedirs("output", exist_ok=True)

    for i, (vid, url) in enumerate(results.items()):
        if url:
            video_data = requests.get(url).content
            filename = f"output/video_{i+1}.mp4"
            with open(filename, "wb") as f:
                f.write(video_data)
            print(f"Saved: {filename}")
    ```
  </Step>
</Steps>

## Platform Optimization

Different platforms have different sweet spots:

| Platform        | Ideal Duration | Orientation      | Tips                                      |
| --------------- | -------------- | ---------------- | ----------------------------------------- |
| TikTok          | 15–60s         | Portrait (9:16)  | Strong hook in first 2s, fast pacing      |
| Instagram Reels | 15–60s         | Portrait (9:16)  | Clean visuals, text overlays              |
| YouTube Shorts  | 15–60s         | Portrait (9:16)  | Slightly more polished, educational angle |
| LinkedIn        | 30–90s         | Landscape (16:9) | Professional tone, industry insights      |

Pass `"orientation": "portrait"` or `"orientation": "landscape"` in your API call. See [Video Agent docs](/docs/video-agent) for all parameters.

## Variations

* **Themed series:** Generate 5 videos on the same topic from different angles (beginner, advanced, myth-busting, case study, hot take)
* **Multi-language:** Generate in English, then use [Video Translation](/docs/video-translate) to create versions in other languages
* **A/B testing:** Generate 2 versions of the same topic with different hooks, measure which performs better

***

## Next Steps

<CardGroup>
  <Card title="Prompt Engineering" icon="wand-magic-sparkles" href="/cookbook/patterns/prompt-engineering">
    Write prompts that produce scroll-stopping content.
  </Card>

  <Card title="Content Repurposing" icon="recycle" href="/cookbook/video-agent/content-repurposing">
    Already have blog content? Turn it into video.
  </Card>
</CardGroup>


# Sound effects
Source: https://developers.heygen.com/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://developers.heygen.com/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                                       | The clip itself                             |

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.

<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`. Each scene is center-cropped to this canvas.            |
| `resolution`   | string | No       | —       | Global output resolution: `720p`, `1080p`, or `4k`.                                                                                 |
| `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 carries the source, discriminated by its own `type`: `avatar` (an avatar you already have) or `image` (a still image animated with lip-sync). The scene's duration is derived from the audio.

#### `avatar` input

Mirrors the standalone [avatar creation mode](/generate-avatar-video), minus the output settings — those are global on the studio request.

```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                        | Solid-color background composited behind the avatar: `{ "type": "color", "color": "#RRGGBB" }`.                                                                  |

Provide exactly one audio source: `script` (with `voice_id` or a default voice), `audio_url`, or `audio_asset_id`.

#### `image` input

Animates a still image with lip-sync — the studio counterpart of [Image to Video](/image-to-video).

```json theme={null}
{
  "type": "avatar_video",
  "input": {
    "type": "image",
    "image": { "type": "url", "url": "https://example.com/portrait.png" },
    "script": "Hi, I'm your presenter today.",
    "voice_id": "YOUR_VOICE_ID"
  }
}
```

| Field                                                                     | Type   | Required                  | Description                                         |
| ------------------------------------------------------------------------- | ------ | ------------------------- | --------------------------------------------------- |
| `type`                                                                    | string | Yes                       | Must be `image`.                                    |
| `image`                                                                   | object | Yes                       | Image to animate — see [Asset input](#asset-input). |
| `script` / `voice_id` / `audio_url` / `audio_asset_id` / `voice_settings` | —      | One audio source required | Same audio rules as the `avatar` input above.       |
| `motion_prompt`                                                           | string | No                        | Natural-language prompt controlling body motion.    |
| `expressiveness`                                                          | string | No                        | Expressiveness level. Defaults to `low`.            |

#### 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. `expressiveness` applies on Avatar IV; `motion_prompt` applies to photo avatars on either engine and to video avatars on Avatar V.

### 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 at its own length.

```json theme={null}
{
  "type": "video",
  "source": { "type": "asset_id", "asset_id": "YOUR_ASSET_ID" },
  "playback": { "mute": true }
}
```

| Field      | Type   | Required | Description                                                                                                                                       |
| ---------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`     | string | Yes      | Must be `video`.                                                                                                                                  |
| `source`   | object | Yes      | Video clip to include — see [Asset input](#asset-input).                                                                                          |
| `playback` | object | No       | Audio control: `volume` (`0.0`–`1.0`, where `1.0` is the source level) and `mute` (force the clip silent). Omit to keep the clip's source volume. |

## Asset input

Scene `source` and `image` fields 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  | `{ "type": "base64", "media_type": "image/png", "data": "<base64>" }`                                                              |

## Captions

Pass a `caption` object to generate captions across the full composed video. 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. |

## Rendering at Scale

Studio requests batch like every other `/v3/videos` creation mode: include them as items in [`POST /v3/videos/batches`](/reference/create-video-batch) to submit many compositions in one call and poll a single `batch_id` — see [Batch Videos](/batch-videos).


# HeyGen Studio Template
Source: https://developers.heygen.com/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>
  Templates are created and edited in the HeyGen web editor. Only templates that have **variables defined** appear in the list, and the detail endpoint supports templates built in the **current editor format** (draft version 4). [Create a template in HeyGen Studio](https://app.heygen.com/avatar/studio) first, then drive it from the API.
</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 | Default  | Description                                                              |
| ---------------- | ------ | -------- | -------- | ------------------------------------------------------------------------ |
| `character_id`   | string | Yes      | —        | Avatar ID or talking photo ID to place.                                  |
| `character_type` | string | No       | `avatar` | Kind of character `character_id` refers to: `avatar` or `talking_photo`. |

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

## 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). Only include the variables you want to change.                |
| `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_voice_id`                | string           | No       | —       | Brand voice ID controlling pronunciation and term handling.                                                                                                                 |

### 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://developers.heygen.com/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.

<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", "character_id": "Annie_expressive5_public", "character_type": "avatar" },
          "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", "character_id": "Annie_expressive5_public", "character_type": "avatar" },
            "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", "character_id": "Annie_expressive5_public", "character_type": "avatar"},
                  "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", character_id: "Annie_expressive5_public", character_type: "avatar" },
              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>Only include the variables you want to change, any you omit keep their template defaults. 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>


# Training & Onboarding Videos
Source: https://developers.heygen.com/training-and-onboarding-videos

Produce training and onboarding videos with the HeyGen API — update the script and regenerate when a policy or process changes.

## The Problem

Corporate training content is expensive to produce, goes stale fast, and doesn't scale across languages. A single compliance training video can cost $5,000–$15,000 to produce professionally — and needs to be re-recorded every time a policy changes.

## How It Works

```
Training docs/policies → LLM structures into video modules → Video Agent renders → Translate for global teams
```

Generate training videos from your existing materials. When the source document updates, regenerate the video. Need it in 10 languages? Use Video Translation.

## Build It

<Steps>
  <Step title="Structure your training material">
    Break content into modules. Each module becomes a separate video — this keeps videos short (2–5 minutes) and makes updates surgical.

    ```python theme={null}
    modules = [
        {
            "title": "Data Privacy Basics",
            "source": "policies/data-privacy.pdf",
            "duration": "3 minutes",
            "style": "professional, clear, reassuring",
        },
        {
            "title": "Handling Customer Data",
            "source": "policies/data-handling.md",
            "duration": "4 minutes",
            "style": "professional, specific, example-driven",
        },
        {
            "title": "Reporting a Breach",
            "source": "policies/breach-response.md",
            "duration": "2 minutes",
            "style": "urgent but calm, step-by-step",
        },
    ]
    ```
  </Step>

  <Step title="Generate video prompts with an LLM">
    Use an LLM to convert each training document into a structured video prompt. The LLM acts as an instructional designer.

    ```python theme={null}
    import anthropic

    client = anthropic.Anthropic()

    def generate_training_prompt(module, content):
        message = client.messages.create(
            model="claude-sonnet-4-20250514",
            max_tokens=1500,
            messages=[{
                "role": "user",
                "content": f"""You are an instructional designer creating a training
    video from a policy document. Convert this into a HeyGen Video Agent prompt.

    Structure the video as:
    1. Introduction (10s) — What this training covers and why it matters
    2. Key concepts (60-70% of duration) — Break into 2-4 clear sections
       with specific examples and scenarios employees will recognize
    3. Do's and Don'ts (15s) — Quick visual checklist
    4. Summary + quiz teaser (10s) — Recap key points, prompt to take the quiz

    Requirements:
    - Tone: {module['style']}
    - Duration: {module['duration']}
    - Use text overlays for key terms and definitions
    - Include scenario-based examples ("Imagine you receive an email from...")
    - Make it engaging — this isn't a lecture, it's a conversation

    Training document:
    {content}

    Output ONLY the Video Agent prompt."""
            }],
        )
        return message.content[0].text

    # Generate prompt for each module
    for module in modules:
        with open(module["source"]) as f:
            content = f.read()
        module["video_prompt"] = generate_training_prompt(module, content)
    ```
  </Step>

  <Step title="Generate videos">
    Submit each module to Video Agent. Space them out for rate limits.

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

    HEYGEN_API_KEY = "your-api-key"

    for module in modules:
        resp = requests.post(
            "https://api.heygen.com/v3/video-agents",
            headers={
                "X-Api-Key": HEYGEN_API_KEY,
                "Content-Type": "application/json",
            },
            json={
                "prompt": module["video_prompt"],
                # Optional: attach policy document for visual context
                # "files": [{"type": "url", "url": "https://..."}]
            },
        )
        module["video_id"] = resp.json()["data"]["video_id"]
        print(f"Submitted: {module['title']} → {module['video_id']}")
        time.sleep(5)
    ```

    Then poll for completion — see [Video Agent docs](/docs/video-agent) for the polling pattern.
  </Step>

  <Step title="Translate for global teams">
    Once your English videos are ready, translate them for every region in one batch.

    ```python theme={null}
    languages = ["Spanish", "French", "German", "Japanese", "Chinese", "Portuguese", "Korean"]

    for module in modules:
        resp = requests.post(
            "https://api.heygen.com/v3/video-translations",
            headers={
                "X-Api-Key": HEYGEN_API_KEY,
                "Content-Type": "application/json",
            },
            json={
                "video": {"type": "url", "url": module["video_url"]},
                "output_languages": languages,
            },
        )
        module["translation_ids"] = resp.json()["data"]["video_translation_ids"]
        print(f"Translating {module['title']} into {len(languages)} languages")
    ```

    Translating many modules? Submit them all in one call with [`POST /v3/video-translations/batches`](/reference/create-video-translation-batch) — see [Batch Video Translations](/batch-video-translations).

    See [Video Translation docs](/docs/video-translate) for speed vs precision mode and all supported languages.
  </Step>
</Steps>

## Training Categories

This workflow applies to any training content:

| Category                          | Source material                       | Key considerations                                   |
| --------------------------------- | ------------------------------------- | ---------------------------------------------------- |
| **Compliance** (HIPAA, GDPR, SOX) | Regulatory docs, policies             | Must be accurate, auditable, up-to-date              |
| **Onboarding**                    | Employee handbook, culture docs       | Warm and welcoming tone, company-specific            |
| **Software training**             | Help docs, screenshots                | Attach screenshots as file inputs for visual context |
| **Safety**                        | Safety procedures, SOPs               | Clear, step-by-step, scenario-based                  |
| **Sales enablement**              | Product knowledge, objection handling | Conversational, example-heavy                        |

## Keeping Videos in Sync

The biggest advantage of generated training videos: **when the policy changes, regenerate the video.**

```
Policy doc updated → Detect change (git diff, CMS webhook, manual trigger)
                   → Re-run the same pipeline
                   → New video replaces the old one
                   → Re-translate if needed
```

No re-recording, no scheduling a film crew, no editing. Just re-run the pipeline.

## Variations

* **Interactive follow-up:** After the pre-rendered training video, launch a [Live Avatar AI Tutor](/cookbook/live-avatar/ai-tutor) for Q\&A and knowledge checks
* **Manager versions:** Generate a shorter executive summary version alongside the full training
* **Assessment-ready:** End each video with key questions that feed into your LMS quiz system

***

## Next Steps

<CardGroup>
  <Card title="Multilingual Content" icon="globe" href="/cookbook/video-agent/multilingual-content">
    Deep dive into translating videos across languages.
  </Card>

  <Card title="AI Tutor" icon="graduation-cap" href="/cookbook/live-avatar/ai-tutor">
    Add interactive Q\&A after training with a Live Avatar tutor.
  </Card>
</CardGroup>


# Transparent Background Videos
Source: https://developers.heygen.com/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://developers.heygen.com/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 Agent Styles
Source: https://developers.heygen.com/video-agent-with-styles

Apply curated visual styles to HeyGen Video Agent outputs. Choose cinematic looks, brand presets, or custom style references to control the agent's video.

## Steps

<Steps>
  <Step title="Browse available styles">
    List all visual styles to find one that fits:

    ```bash theme={null}
    heygen video-agent styles list
    ```

    ```json theme={null}
    {
      "data": [
        {
          "style_id": "349d91e1ad2444eabab2672a9057f298",
          "name": "Thriller",
          "aspect_ratio": "16:9",
          "tags": ["cinematic"]
        },
        {
          "style_id": "be9f5b18fb294c99a0e34c15707145fc",
          "name": "Lego",
          "aspect_ratio": "16:9",
          "tags": ["handmade"]
        },
        {
          "style_id": "13898c3b01ec4dafae5fc17753c7dd7a",
          "name": "iOS",
          "aspect_ratio": "9:16",
          "tags": ["retro-tech"]
        }
      ]
    }
    ```

    Each style has an `aspect_ratio` — some are landscape (`16:9`), others portrait (`9:16`). Use `--human` for a readable table view.

    <Note>
      Each style includes a `preview_video_url` and `thumbnail_url` — open them to preview the visual treatment before choosing.
    </Note>
  </Step>

  <Step title="Generate a styled video">
    Pass the `style_id` along with your prompt:

    ```bash theme={null}
    heygen video-agent create \
      --prompt "A 30-second explainer about how AI is transforming video production" \
      --style-id "349d91e1ad2444eabab2672a9057f298"
    ```

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

    The agent picks the avatar, voice, and layout. The style controls the visual treatment.

    To override the agent's choices, pass additional flags:

    ```bash theme={null}
    heygen video-agent create \
      --prompt "A product launch announcement" \
      --style-id "349d91e1ad2444eabab2672a9057f298" \
      --avatar-id "avt_angela_01" \
      --voice-id "1bd001e7e50f421d891986aad5e3e5d2" \
      --orientation landscape
    ```
  </Step>

  <Step title="Wait and download">
    ```bash theme={null}
    # Block until ready
    heygen video-agent create \
      --prompt "A quick intro to our company" \
      --style-id "be9f5b18fb294c99a0e34c15707145fc" \
      --wait

    # Or poll manually
    heygen video get vid_xyz789

    # Download
    heygen video download vid_xyz789 --output-path ./styled-video.mp4
    ```
  </Step>
</Steps>

## Batch: same content, multiple styles

Generate the same prompt across different visual styles:

```bash theme={null}
#!/bin/bash
set -e

PROMPT="A 30-second pitch for an AI-powered design tool"

STYLES=(
  "349d91e1ad2444eabab2672a9057f298:Thriller"
  "be9f5b18fb294c99a0e34c15707145fc:Lego"
  "279082e3beda4ac5a4e9a4f2a36c7d74:Silent-Film"
)

for entry in "${STYLES[@]}"; do
  STYLE_ID="${entry%%:*}"
  STYLE_NAME="${entry##*:}"

  echo "Generating $STYLE_NAME..."
  VIDEO_ID=$(heygen video-agent create \
    --prompt "$PROMPT" \
    --style-id "$STYLE_ID" \
    | jq -r '.data.video_id')

  echo "  Video ID: $VIDEO_ID (generating...)"
done

echo "All videos submitted. Poll with: heygen video get <video-id>"
```

## Interactive sessions for iteration

Review and refine before generating:

```bash theme={null}
# Start a session
SESSION=$(heygen video-agent sessions create \
  --prompt "A product demo video in Lego style" \
  --style-id "be9f5b18fb294c99a0e34c15707145fc" \
  | jq -r '.data.session_id')

# Check the storyboard
heygen video-agent sessions get "$SESSION"

# Send feedback
heygen video-agent sessions messages create "$SESSION" \
  -d '{"message": "Make the intro more energetic and add a CTA at the end"}'

# Stop if you want to start over
heygen video-agent sessions stop "$SESSION"
```

## Available flags

| Flag               | Description                                     |
| ------------------ | ----------------------------------------------- |
| `--prompt`         | Text prompt describing the video **(required)** |
| `--style-id`       | Visual style from `styles list`                 |
| `--avatar-id`      | Override the agent's avatar choice              |
| `--voice-id`       | Override the agent's voice choice               |
| `--orientation`    | `landscape` or `portrait`                       |
| `--incognito-mode` | Disable memory for this session                 |
| `--callback-url`   | Webhook URL for completion notifications        |
| `--wait`           | Block until ready (default timeout: 20 min)     |
| `--timeout`        | Override wait timeout (e.g. `--timeout 30m`)    |


# Writing Effective Video Prompts
Source: https://developers.heygen.com/writing-effective-video-prompts

Get better video agent results with prompt engineering. Covers structure, specificity, style direction, and common pitfalls, with before-and-after prompt.

Video Agent is prompt-driven. But "more detail" doesn't always mean "better video." We ran 14 experiments with different prompting strategies to find out what actually produces the best results. Here's what we learned.

## See the Difference

Same topic, different prompts. Watch both — the difference is the entire argument of this page.

<Tabs>
  <Tab title="Vague prompt">
    Prompt:

    ```text theme={null}
    Make a video about remote work benefits.
    ```

    <iframe title="HeyGen video player" />
  </Tab>

  <Tab title="Crafted prompt">
    Prompt:

    ```text theme={null}
    Two years ago, I could only hire people within 30 miles of our
    office. Today, my team spans 4 countries and 3 time zones. We
    found engineers we never would have found locally. Our office
    costs dropped to nearly zero. And here's the surprising part —
    people actually stayed longer. Remote isn't the future. It's
    already the default.

    Tone: Like a founder on a podcast — reflective, honest, sharing
    a personal experience. Not a pitch, not a lecture. Just someone
    who tried something and it worked.
    Background: Casual home office or coffee shop. Warm, natural.
    30 seconds. Landscape.
    ```

    <iframe title="HeyGen video player" />
  </Tab>
</Tabs>

Both are about remote work benefits. The second used a natural story script with a tone description — no timestamps, no scene structure, no prescribed overlays. Just a great script and a feeling.

## The #1 Rule: Write a Great Script

The single biggest factor in video quality is the script — the actual words the presenter will say. Everything else (visuals, overlays, pacing) is secondary. Video Agent makes good production decisions on its own. Your job is to give it great words to work with.

<Tabs>
  <Tab title="Weak script">
    ```text theme={null}
    Here are three science-backed ways to sleep better tonight.
    First: cut screens 30 minutes before bed — blue light
    suppresses melatonin. Second: cool your room to 65 degrees.
    Third: wake up at the same time every day.
    ```

    Informational, clinical, reads like a textbook. The video will be competent but forgettable.
  </Tab>

  <Tab title="Strong script">
    ```text theme={null}
    Six months ago I was averaging 5 hours of broken sleep. I
    tried everything — supplements, meditation apps, white noise
    machines. Nothing worked. Then I did three stupidly simple
    things: I put my phone charger in the kitchen. I turned the
    thermostat down to 65. And I set one alarm — same time, every
    single day. No more negotiating with the snooze button. Within
    two weeks I was sleeping 7 hours straight. No supplements. No
    apps. Just discipline and a cold room.
    ```

    Personal, narrative, has an arc. The viewer is hooked because someone is telling a real story — not listing facts.
  </Tab>
</Tabs>

In our experiments, the personal story consistently produced better videos than the informational version — better B-roll choices, better pacing, more engaging delivery.

## What Makes a Script Work

**Stories beat lists.** First-person narratives ("I tried X, then Y happened") give Video Agent richer material to work with than bullet points. The agent generates better visuals when the script has emotional texture.

**Bold beats safe.** Provocative framing ("Stop trying to sleep 8 hours. Seriously.") produced more engaging videos than neutral framing. The agent matched the script's energy with bolder visual choices.

**Flow beats structure.** Scripts that read naturally — like someone talking to a friend — deliver better than scripts chopped into rigid segments. If it sounds awkward to read aloud, it'll sound awkward in the video.

**Questions don't work well.** Scripts built around questions ("Do you check your phone before bed? What temperature is your bedroom?") felt unnatural with a single speaker. Save the Socratic method for [Live Avatar](/cookbook/live-avatar/ai-tutor) conversations.

## Add Tone, Not Timestamps

After writing your script, the most useful thing you can add is a **tone description** — how the video should *feel*, not how it should be structured.

<Tabs>
  <Tab title="Tone description (do this)">
    ```text theme={null}
    [your script here]

    Tone: Like a founder on a podcast — reflective, honest, no
    corporate speak. The presenter should feel like they're sharing
    a personal experience, not reading a script.
    Background: Casual home office or coffee shop. Warm, natural.
    Duration: 30 seconds.
    ```

    Guides the delivery and mood without constraining the production.
  </Tab>

  <Tab title="Timestamp structure (avoid this)">
    ```text theme={null}
    Scene 1 (0-5s): Hook — "..."
    Scene 2 (5-12s): Tip 1 — "..."
    Scene 3 (12-20s): Tip 2 — "..."
    Scene 4 (20-27s): Tip 3 — "..."
    Scene 5 (27-30s): Close — "..."
    ```

    Gives you precise control but makes the delivery feel robotic. The agent follows the timing exactly, and the result sounds choppy.
  </Tab>
</Tabs>

In our tests, adding tone improved delivery quality. Adding timestamps and scene structure gave more control but hurt the natural flow of speech.

## Let Video Agent Handle Production

Video Agent makes surprisingly good decisions about:

* **B-roll selection** — relevant, well-timed visuals
* **Text overlays** — clean typography, good placement
* **Color palette** — matches the mood of the script
* **Music** — appropriate energy and tone
* **Pacing** — natural rhythm based on the script

You don't always need to specify these. In our experiments (tested on a health/wellness topic), the minimal prompt ("Make a 30-second video about 3 tips for better sleep") produced a video with solid B-roll, thoughtful overlays, and a calming color palette — all chosen by the agent. Results may vary by topic and content type.

**Only override production decisions when you have a specific need.** For example:

* `Orientation: portrait` — when targeting TikTok/Reels
* `Duration: 30 seconds` — when you have a length constraint
* Keep the presenter on screen (see below for translation-ready videos)

## Reference Files for Context

When your video is about something visual — a product, a document, a website — attach files so the agent has context to work with.

```json theme={null}
{
  "prompt": "Create a product walkthrough based on the attached screenshots...",
  "files": [
    { "type": "url", "url": "https://example.com/screenshot.png" }
  ]
}
```

This works well for product demos, content summaries, and brand-consistent videos. See [Video Agent docs](/docs/video-agent#file-input-formats) for supported file types.

## Translation-Ready Videos

If you plan to translate your video into other languages using [Video Translation](/cookbook/video-agent/multilingual-content), the presenter's face needs to be visible throughout for lip-sync to work. Add this to your prompt:

```text theme={null}
This is a direct-to-camera message. Think of it like a FaceTime
call — one person, one camera, sincere eye contact throughout.
The presenter should be visible and speaking for the entire video.
```

<Warning>
  **Don't use restrictive language** like "No B-roll, no cutaway scenes, no stock footage." In our tests, this produced a flat, visually boring result. The positive framing above keeps the avatar on screen while still allowing the agent to add text overlays for visual interest.
</Warning>

## Prompt Templates

These templates use the patterns that worked best in our experiments: natural scripts, tone descriptions, and minimal production direction.

<Accordion title="Personal Story (30s)">
  ```text theme={null}
  [Write a first-person story about your topic. Include a problem,
  what you tried, what actually worked, and the result. Make it
  conversational — read it aloud to check if it flows naturally.]

  Tone: Honest, slightly amazed it worked. Like a podcast story.
  Not polished — real.
  Duration: 30 seconds.
  ```
</Accordion>

<Accordion title="Bold Take (30s)">
  ```text theme={null}
  [Open with a contrarian or surprising statement. Challenge a
  common assumption. Then deliver 2-3 rapid points that support
  your take. Close with a memorable line.]

  Tone: Confident, slightly provocative. Not angry — just done
  with bad advice. Like a friend who's tired of watching you
  struggle.
  Duration: 30 seconds.
  ```
</Accordion>

<Accordion title="Micro-Story (30s, portrait)">
  ```text theme={null}
  [Write one continuous thought — no bullet points, no lists, no
  sections. Just a person telling a 30-second story directly to
  camera. The simpler and more honest, the better.]

  Tone: Deadpan, honest, slightly amused. The humor is in the
  delivery, not the words.
  Orientation: portrait.
  ```
</Accordion>

<Accordion title="Translation-Ready Message (30-45s)">
  ```text theme={null}
  [Write a warm, universal message. Avoid idioms, slang, or
  culturally specific references — this will be translated into
  multiple languages. Keep sentences short and clear.]

  This is a direct-to-camera message — one person, one camera,
  sincere eye contact throughout. Like a FaceTime call from a
  friend.
  Tone: Warm, sincere, inclusive.
  Duration: 35 seconds. Landscape.
  ```
</Accordion>

## Common Mistakes

<Warning>
  **Don't over-structure.** Timestamps per scene (0-5s, 5-12s) make the delivery sound robotic. Write a flowing script and let the agent decide the pacing.
</Warning>

<Warning>
  **Don't prescribe visuals you don't need.** "Text overlay: Global Talent Pool" or "Show a visual of a thermostat" — the agent makes good visual choices on its own. Only specify visuals when they're critical to the message.
</Warning>

<Warning>
  **Don't use question-driven scripts.** "Do you check your phone before bed?" feels unnatural coming from a single presenter talking to camera. Questions work in conversations, not monologues.
</Warning>

<Warning>
  **Don't use restrictive instructions.** "Do NOT use stock footage. Do NOT include music." Telling the agent what NOT to do makes it play safe. Use positive framing: describe what you want, not what you don't.
</Warning>

<Info>
  **How we know this:** We ran 14 experiments generating the same topic ("3 tips for better sleep") with different prompting strategies — varying detail level, script style, format instructions, and avatar visibility. The findings on this page are based on those rendered videos, not theory.
</Info>

***

## Next Steps

<CardGroup>
  <Card title="Social Media Pipeline" icon="share-nodes" href="/cookbook/video-agent/social-media-pipeline">
    Apply these techniques to batch-generate social content.
  </Card>

  <Card title="Multilingual Content" icon="globe" href="/cookbook/video-agent/multilingual-content">
    Generate translation-ready videos using the positive framing technique.
  </Card>
</CardGroup>