> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

![](https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-5.webp?fit=max\&auto=format\&n=hfMXXwJzjE7vBSYZ\&q=85\&s=422da140ece4b799d490f85bb2013ca5)

## Create a Clip Job

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

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

`video` takes a public HTTPS URL or an `asset_id` from [`POST /v3/assets`](https://heygen-1fa696a7.mintlify.site/reference/upload-asset) (see [Upload Assets](https://heygen-1fa696a7.mintlify.site/docs/upload-assets.md)). `input_language` (ISO-639-1, e.g. `en`) auto-detects when omitted, and `title` defaults to the source video's title. The [create reference](https://heygen-1fa696a7.mintlify.site/reference/create-ai-clipping.md) has the full schema.

### Output settings

* `duration_types`: 1–4 target durations from `"30"`, `"60"`, `"180"` and `"long"`. Each duration produces a separate clip.
* `aspect_ratio`: `portrait` (9:16, the default), `landscape` (16:9) or `square` (1:1), applied to every clip.
* `captions`: burned in by default (`true`). Set `false` for clean, caption-free footage. `caption_style` picks a named preset such as `classic` or `bold`.
* `prompt`: editorial guidance for the highlight model, such as which speaker or what topics (max 500 chars). Without it, 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.

## Get a Clip Job

[`GET /v3/ai-clipping/{job_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-ai-clipping) returns the job's live status and `progress` (0–100), and its `clips` array populates as each clip renders, empty until the first one finishes. Job `status` moves `pending` → `running` → `completed` | `failed` (or `cancelled`); each clip has its own `status` plus a model-generated `title`, `duration_seconds`, a `virality_score` (0–100), and pre-signed `thumbnail_url` and `video_url` (MP4). On failure, read `failure_message`.

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

For long recordings, prefer a [`callback_url`](https://heygen-1fa696a7.mintlify.site/docs/webhooks) over tight polling: HeyGen will POST you the finished job instead (`ai_clipping.success` / `ai_clipping.fail` [webhook events](https://heygen-1fa696a7.mintlify.site/docs/webhook-events.md)), echoing your `callback_id`.

## List and Delete

[`GET /v3/ai-clipping`](https://heygen-1fa696a7.mintlify.site/reference/list-ai-clipping) lists jobs with `limit` (default `10`) and a `token` cursor from `next_token`. It reports coarse `progress`; poll [Get a Clip Job](#get-a-clip-job) for live in-flight progress on a specific job. [`DELETE /v3/ai-clipping/{job_id}`](https://heygen-1fa696a7.mintlify.site/reference/delete-ai-clipping) permanently deletes a clip job and its clips.

Pairing clips with audio? The same [Tools](https://heygen-1fa696a7.mintlify.site/background-music.md) suite covers [background music](https://heygen-1fa696a7.mintlify.site/background-music.md) and [sound effects](https://heygen-1fa696a7.mintlify.site/sound-effects.md) to score your cuts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.